Operator Manual for the Laundromat Website Build System
This manual is the system map for this repo — the Agent-SDD build framework plus the BCB WordPress themes and plugins: what's here, how the pieces fit, and how the canonical sources stay in lock-step. For the step-by-step build procedure, see the build runbook in suds-agent-sdd/.claude/docs/workflow-manual.html.
Workspace Snapshot
SD-*-client.json/suds:* · $suds-build1. Purpose
This repository is the build system for Suds laundromat websites: an agent-neutral build protocol, supported Claude Code and Codex adapters, and the Bootstrap Component Blox (BCB) WordPress engine, parent theme, thin brand themes, and bundled plugins. An operator points either supported agent at one prepared client intake and drives the same locked project state to a launch-ready site.
The intended users are internal Suds Digital operators, developers, and AI agents working under operator direction. This manual is the system map — what's here and how it fits. The build runbook (the step-by-step) lives separately at suds-agent-sdd/.claude/docs/workflow-manual.html.
SD-<id>-client.json intake this repo consumes. Downstream, a separate Sitechange app handles post-launch edit tickets. The separately deployed Suds Release & Fleet Control Center distributes signed Engine releases and records fleet/audit state at https://suds.themecontrol.website. None of these services is part of this workspace, and none is in a completed site's public render path.
2. What's in This Repo
The repository has an agent-neutral protocol, two supported agent adapters, the canonical WordPress engine, and the glue that keeps every shipped copy honest:
Documentation index: DOCUMENTATION.md at the repo root maps every doc into the two product manuals — the Owner Manual (this file, the site-build runbook, the engine plugin's docs/workbench-runbook.html Section Studio guide) and the AI Dev Operator Manual (CLAUDE.md, AGENTS.md, the section-library contracts). Start there when you don't know where something is written down.
suds-build-protocol/ owns facts, decisions, projections, locks, and gates. Claude uses suds-agent-sdd/.claude/ and /suds:*; Codex uses suds-agent-codex/skills/suds-build and $suds-build.
The BCB parent, shared Engine plugin, canonical thin starter, generated client brand themes, and bundled utilities under wordpress/. The retired classic starter is historical only.
The suds-digital-website-builder engine plugin ships the protocol plus both agent adapters and installs them into a client site via Prepare Build (wp suds prepare-build <uuid>); the build scripts regenerate the payloads from their canonical sources so they never drift (see §6).
Directory Roles
| Path | Role |
|---|---|
suds-agent-sdd/.claude/ |
Canonical Agent-SDD framework: commands, agents, config/registry, docs, templates, reference manifest, Mission Control. |
suds-agent-sdd/CLAUDE.md |
Auto-loaded project memory: blueprint boundary, task schema, naming, global rules. |
suds-agent-codex/skills/suds-build/ |
Supported Codex adapter: skill instructions, initialization, and shared workspace contract. |
suds-build-protocol/ |
Agent-neutral schemas, policies, workflows, projector, lock verifier, guarded handoff, and golden fixtures. |
wordpress/themes/ |
BCB parent theme, canonical suds-build-system-2 thin starter, generated client brand themes, and built theme ZIP. The classic child theme is retired archaeology. |
wordpress/plugins/ |
Blueprint plugins, including the suds-digital-website-builder engine plugin (THE ENGINE; also ships the framework payload and installs it into a client site via its Prepare Build screen). |
scripts/sync-blueprint.sh |
Regenerates the engine plugin's blueprint payload from the canonical framework (parity — see §6). |
HANDOFF.md |
Working session hand-off for continuing build / maintenance sessions. |
3. Quick Start for a New Website Build
/suds-placeholder-kit skill on the intake before wp suds import-assets to generate claim-safe, clearly-temporary brand placeholders for empty image slots. Real photos always replace them later.
SD-<id>-client.json plus its checksum is present under the installed .claude/intake/. Manual placement is a recovery path, not the normal flow.
/suds:init. In Codex, invoke $suds-build and ask it to initialize and build from the newest prepared intake. Both follow the same protocol gates and project roadmap.
/suds:mission-control for the live operator dashboard — status, tasks, decisions, brand, assets, and docs. Leave it open during the build.
Core SDD Command Flow
/suds:init
/suds:bootstrap
wp suds import-intake .claude/intake/SD-<id>-client.json
/suds:copy
/suds:next
/suds:execute TASK-001
/suds:improve launch-readiness "resolve open launch gates"
/suds:qa --fix # launch-readiness gate — "ready to share with the client?"
/suds:mission-control4. Prerequisites
Workspace
- Use this repo as the build system and central operator reference.
- The Onboarder (intake) and Sitechange (tickets) apps live in their own repos — only the intake JSON contract crosses into this workspace.
- Do not treat generated client files as reusable templates unless they are sanitized.
WordPress Build
- Use a WordPress install with
wp-config.phpandwp-content/. - Ensure the BCB parent theme, canonical thin starter, and Suds Engine plugin are available.
- Use Prepare Build to install the managed agent payload and intake; do not clone a client theme.
Supported Agent Adapters
- Claude Code runs the native commands in
.claude/commands/suds/.CLAUDE.mdauto-loads its adapter rules. - Codex invokes
$suds-buildfrom.codex/skills/suds-build; the skill routes initialization, planning, execution, and QA through the same shared files and engine. - Use
.claude/config/registry.ymlas the registry for paths, subagents, blueprint boundaries, and templates. - Keep one active intake JSON and one active agent. Switch with
wp suds handoff-agent --to=claude|codex, never by reinitializing the project.
5. Agent-SDD + BCB Build
The agent-neutral build brain lives under suds-build-protocol/. Claude's interface lives under suds-agent-sdd/.claude/; Codex's interface lives under suds-agent-codex/skills/suds-build/. The Bootstrap Component Blox parent theme, thin-theme starter, and engine plugin live under wordpress/. Prepare Build installs both adapters into a client site, but only one drives the project at a time.
Choose or switch the agent
| Situation | Operator action |
|---|---|
| Fresh project with Claude | Open the site's wp-content workspace and run /suds:init. |
| Fresh project with Codex | Open the same workspace, invoke $suds-build, and ask it to initialize from the newest prepared intake. |
| Existing project changes agent | From the WordPress root run wp suds handoff-agent --to=claude or --to=codex, then continue the active roadmap/task in the target agent. |
build-plan.json. It may replace only the adapter projection, comparison report, and adjacent lock. A factual mismatch stops; REVIEW_DIFFERENCES requires review before --accept-review-differences.Install Location
The workflow supports either of these layouts:
<wp_root>/.claude
<wp_root>/wp-content/.claude
Workflows must resolve WordPress paths through {{paths.wp_root}}, {{paths.wp_content_dir}}, {{paths.themes_dir}}, and {{paths.plugins_dir}}. Do not assume the parent of .claude is the WordPress root.
Intake Contract
- Place one active intake file in
.claude/intake/. - Use
SD-<id>-client.jsonorsd-<id>-client.json. - Archive old intake files outside the active intake directory so discovery stays unambiguous.
/suds:initlocalizesassets[].download_urlinto.claude/intake/assets/<project_id>/.
Active Commands
| Command | Use | Key Files |
|---|---|---|
/suds:init |
Read the intake, localize assets, compile the build plan/page map, and generate product/standards docs. | .claude/commands/suds/init.md |
/suds:backfill |
Onboard an already-built site by reconciling framework artifacts from the live site ("reconcile, don't recreate"). /suds:init routes here when it detects an existing build. |
.claude/commands/suds/backfill.md |
/suds:bootstrap |
Generate and activate the client's thin brand theme, confirm one of 7 design archetypes plus one of 4 hero layouts, derive accessible brand tokens, and generate theme standards. The Engine remains the shared implementation. | .claude/commands/suds/bootstrap.md |
/suds:copy |
Expert copywriter pass: generate claim-safe, on-brand, client-tailored copy from the intake and write it into the site's empty copy fields (set-once; operator edits win). Run after bootstrap + wp suds import-intake. |
.claude/commands/suds/copy.md |
/suds:enrich |
Backfill verified public contact/listing/review/pricing facts into an already-built site. Existing values win; unknown surfaces stay gated and become operator decisions. | .claude/commands/suds/enrich.md |
/suds:next |
Read the roadmap and generate the next focused spec/tasks. | .claude/commands/suds/next.md |
/suds:execute <task-id> |
Execute a planned task and run WordPress/BCB verification. | .claude/commands/suds/execute.md |
/suds:improve |
Handle launch-readiness cleanup, fixes, accessibility, responsive, or polish work. | .claude/commands/suds/improve.md |
/suds:qa |
Launch-readiness gate: run the deterministic wp suds qa check, interpret findings, apply safe fixes (--fix), and return a "ready to share with the client?" verdict + punch-list. |
.claude/commands/suds/qa.md |
/suds:evolve |
Review and clean up the SDD framework itself. | .claude/commands/suds/evolve.md |
/suds:mission-control |
Refresh the rollup and launch the live operator dashboard (Mission Control). | .claude/commands/suds/mission-control.md |
Generated Thin Theme — One Supported Path
/suds:bootstrap uses the Engine's thin-theme generator to create the client's brand wrapper. It does not clone the Engine or a prior client's theme. The reusable section library, templates, CLI, CSS, schema, and agent payload remain in the versioned Engine plugin.
| Starter | What it is | Choose it when… |
|---|---|---|
suds-build-system-2Canonical thin starter |
A minimal brand wrapper generated around the shared Engine: 7 design archetypes × 4 hero layouts, ACF Theme Settings, services/locations/FAQs, import, composition, and schema. | Every new Suds client build. The generator emits a client-named theme and preserves Engine ownership of reusable behavior. |
bootstrap-component-blox-child-themeRetired · historical |
The pre-engine classic starter is retained for archaeology and migration reference. | Do not use for a new build. Migrate legacy work into the shared Engine/section contract instead of creating another fork. |
.claude/docs/archetypes.md and .claude/docs/operator-cheat-sheet.html.
Engine WP-CLI & design-system reference
The Suds Digital Website Builder ENGINE PLUGIN provides the wp suds subcommands and a living design-system reference (the active theme is just the client's thin brand wrapper):
| Command / surface | Use |
|---|---|
wp suds import-intake <file> | Scaffold pages + menu + front page, write Theme Settings / CPTs from the intake. |
wp suds import-assets <file> | Sideload the intake assets[] (local path / --assets dir / download_url) into the media library and assign to slots via sbs_asset_slot (logo→custom_logo, storefront→hero, interior→why, vehicle→service-area). Real photos beat placeholders; idempotent. |
wp suds scaffold · wp suds apply-palette | Just the page/menu shell; seed brand colors from the logo. |
wp suds tokens [--format=json|css|acf] | Export the site's effective design tokens (reuse / seed another site / agent input). |
wp suds preview · ?sbs_preview=<id|all> | Render any section on the real path; tools/build-preview.sh writes an offline gallery. |
wp suds qa | Deterministic launch-readiness report (the engine behind /suds:qa). |
| Appearance → Design System | In-dashboard: token swatches + export + a browsable section library with live previews. |
docs/manual.html · docs/manifest.json | Generated human manual + machine-readable manifest (agents: .claude/reference/design-manifest.md). |
docs/catalog.html | Visual section catalog — every section as a real thumbnail with when-it-fires metadata, plus a category×scenario coverage matrix (gap finder). Run php tools/build-catalog.php --base=<clone>. |
Mission Control (Live Dashboard)
Mission Control is the operator's single live surface — the always-on ops view of the build: current phase, progress, tasks, blockers, decisions, brand, assets, and a docs reader, refreshed automatically as the agent works. Launch it with /suds:mission-control (or python3 .claude/tools/mission_control_server.py --port 8976) and open http://localhost:8976/. It is loopback-only.
Answer Decisions Needed inline (saved to .claude/product/operator-decisions.json), and use the copy buttons to hand the next command, a task's /suds:execute, or a full status briefing to Claude Code Desktop. Full guide: .claude/mission-control/manual.html (also linked inside the dashboard).
Blueprint Boundary
.claude/config/registry.yml treats the BCB parent, Engine plugin, canonical thin starter, and blueprint plugins as already present. SDD work should focus on strategy, IA, WordPress data and composition, design tokens, copy, reusable Engine sections/knobs, asset wiring, SEO/schema, QA, and operator review.
Expected Generated State
| Directory | Purpose |
|---|---|
.claude/product/ |
Build plan, page map, overview, roadmap, strategy, copy deck, SEO plan, claim-safety notes, and related product docs from real runs. |
.claude/standards/ |
Tech stack, best practices, architecture, and theme standards. |
.claude/specs/ |
Generated specs and tasks.json files for focused build phases. |
wp-content/themes/<client-slug>/ |
The generated thin client brand theme. Reusable rendering remains in the Engine plugin. |
6. Parity — Keeping the Canonical Sources in Lock-Step
The protocol, both adapters, generated engine documentation, and distributable packages each have a canonical source plus a generated copy. The copies must equal their source. After editing a canonical source, regenerate its copy and run the parity gate.
| Canonical source | Generated copy | Regenerate & verify |
|---|---|---|
suds-build-protocol/ + suds-agent-sdd/ + suds-agent-codex/ |
wordpress/plugins/suds-digital-website-builder/blueprint/ |
Run ./scripts/sync-blueprint.sh, then ./scripts/verify-parity.sh. |
wordpress/plugins/suds-digital-website-builder/ (THE ENGINE) |
wordpress/plugins/suds-digital-website-builder.zip + generated docs (docs/manifest.json, manual.html, catalog.html) + the framework reference manifest |
Run make build at the repo root — it regenerates docs, syncs the protocol plus both adapter payloads, rebuilds both ZIPs (engine plugin + thin theme), and gates on verify-parity.sh. |
wordpress/themes/suds-build-system-2/ (thin starter) |
wordpress/themes/suds-build-system-2.zip |
Covered by the same make build gate. |
SD-<id>-client.json. Confirm exactly one active file is present in .claude/intake/, the filename matches the pattern, and assets[] have slugs and (fresh) signed URLs before running /suds:init.
7. Safety Rules
Secrets
- Do not commit or share real
.env.localfiles. - Keep API keys and any other secrets out of manuals, examples, and committed files.
- Rotate exposed secrets immediately.
Client Data
- Treat intake JSON, images, exported ZIPs, and manifests as client data.
- Use sanitized fixtures for docs, tests, and future AI-agent examples.
- Do not upload client assets to unrelated systems unless the workflow explicitly requires it.
WordPress
- Do not modify the BCB parent theme for client-specific work.
- Do not generate DNS, hosting, SMTP credential, ACF license, or plugin-install tasks inside SDD.
- Use escaped output and BCB conventions for child theme templates.
Claims
- Separate confirmed client facts from operator-decision gaps.
- Avoid unverifiable claims such as "largest" unless the intake or operator confirms them.
- Run claim-safety review before launch.
8. Troubleshooting
| Symptom | Likely Cause | What to Check |
|---|---|---|
/suds:init cannot find intake. |
Filename does not match the documented pattern, or multiple active files create ambiguity. | Use .claude/intake/SD-<id>-client.json and archive old intake files. |
| SDD resolves WordPress paths incorrectly. | .claude location is being interpreted as WordPress root. |
Follow .claude/docs/root-detection.md; verify wp-config.php and wp-content/. |
| Generated SDD task tries to install blueprint plugins. | Blueprint boundary was ignored. | Re-read .claude/config/registry.yml and regenerate the spec with the boundary enforced. |
| A client site behaves differently from the framework. | The engine plugin's blueprint payload drifted from the canonical framework. | Run ./scripts/sync-blueprint.sh and diff -rq the payload against suds-agent-sdd/.claude/ (see §6). |
9. File Index
Repo Root
OPERATOR-MANUAL.html- This system manual (overview of the repo).HANDOFF.md- Active session hand-off for continuing work.scripts/sync-blueprint.sh- Regenerates the engine plugin's protocol, Claude, and Codex payloads from their canonical sources.suds-build-protocol/- Agent-neutral schemas, policies, workflow, projection/lock tools, guarded handoff, and golden cases.suds-agent-codex/skills/suds-build/- Supported Codex adapter and workspace contract.
Agent-SDD Framework
suds-agent-sdd/README.md- Framework quick start and command overview.suds-agent-sdd/CLAUDE.md- Agent-SDD operating instructions (auto-loaded project memory).suds-agent-sdd/.claude/commands/suds/- The 11 native/suds:*slash commands.suds-agent-sdd/.claude/agents/- The 12 Claude Code subagents.suds-agent-sdd/.claude/config/registry.yml- Registry: paths, errors, constraints, blueprint boundary, templates.suds-agent-sdd/.claude/docs/workflow-rules.md- Sequence guards and dependency matrix.suds-agent-sdd/.claude/docs/workflow-manual.html- The build runbook (step-by-step).suds-agent-sdd/.claude/reference/design-manifest.md- How agents use the design-system manifest.suds-agent-sdd/.claude/tools/mission_control_server.py- Mission Control dashboard server.suds-agent-sdd/.claude/mission-control/- Mission Control dashboard UI +manual.html.
BCB WordPress (wordpress/)
themes/bootstrap-component-blox/- BCB parent theme.plugins/suds-digital-website-builder/- THE ENGINE (7 skins × 4 hero layouts, section library, plugin-served templates,wp sudsCLI, design-system reference). It also carries the shared protocol and both adapter payloads, installs them via Prepare Build, and exposeswp suds handoff-agent.themes/suds-build-system-2/is the thin starter theme its generator assembles per client.themes/bootstrap-component-blox-child-theme/- Retired classic starter retained only for migration/history.plugins/bcb-edit-capture/- Operator edit-capture helper plugin.plugins/suds-popup/·plugins/auto-update-silencer/- Bundled blueprint plugins.plugins/suds-bcb-agent/- Internal, temporary MCP server for guarded post-launch remote edits. It is not shipped to licensees and is not replaced by Prepare Build; enable it only for an authorized editing session, then disable it.