Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions workspaces/workspace-builder/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,9 @@ Pipeline Status: workspace-builder
|------|-----------|-------------|
| Discover workflow | `references/conventions-reference.md`, `references/examples/script-to-animation-summary.md` | `stages/02-mapping/` through `stages/05-validation/` |
| Formalize contracts | `stages/01-discovery/output/`, `references/conventions-reference.md` | `references/examples/`, `stages/03-scaffolding/` through `stages/05-validation/` |
| Generate scaffold | `stages/02-mapping/output/`, `references/conventions-reference.md`, `/_core/templates/*`, `/_core/placeholder-syntax.md` | `stages/01-discovery/`, `references/examples/` |
| Design questionnaire | `stages/01-discovery/output/`, scaffolded workspace from stage 03, `/_core/templates/questionnaire-template.md` | `stages/02-mapping/`, `references/examples/` |
| Validate workspace | Scaffolded workspace from stage 03, `stages/04-questionnaire-design/output/`, `/_core/CONVENTIONS.md` | `stages/01-discovery/`, `stages/02-mapping/`, `references/examples/` |
| Generate scaffold | `stages/02-mapping/output/`, `references/conventions-reference.md`, `../../_core/templates/*`, `../../_core/placeholder-syntax.md` | `stages/01-discovery/`, `references/examples/` |
| Design questionnaire | `stages/01-discovery/output/`, scaffolded workspace from stage 03, `../../_core/templates/questionnaire-template.md` | `stages/02-mapping/`, `references/examples/` |
| Validate workspace | Scaffolded workspace from stage 03, `stages/04-questionnaire-design/output/`, `../../_core/CONVENTIONS.md` | `stages/01-discovery/`, `stages/02-mapping/`, `references/examples/` |

## Stage Handoffs

Expand Down
34 changes: 17 additions & 17 deletions workspaces/workspace-builder/references/conventions-reference.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,43 @@
# MWP Conventions Reference

The canonical MWP conventions live at `/_core/CONVENTIONS.md`. Read that file for the full specification.
The canonical MWP conventions live at `../../../_core/CONVENTIONS.md`. Read that file for the full specification.

This file is a pointer, not a copy. Do not duplicate content from CONVENTIONS.md here.

## Quick Reference

The most important conventions for building a new workspace:

- **Five-layer routing**: CLAUDE.md (Layer 0) -> CONTEXT.md (Layer 1) -> Stage CONTEXT.md (Layer 2) -> Reference material (Layer 3) -> Working artifacts (Layer 4). Layer 3 is persistent context (design systems, voice rules, conventions). Layer 4 is per-run context (previous stage outputs, source material). See "Five-Layer Routing Architecture" in `/_core/CONVENTIONS.md`.
- **Five-layer routing**: CLAUDE.md (Layer 0) -> CONTEXT.md (Layer 1) -> Stage CONTEXT.md (Layer 2) -> Reference material (Layer 3) -> Working artifacts (Layer 4). Layer 3 is persistent context (design systems, voice rules, conventions). Layer 4 is per-run context (previous stage outputs, source material). See "Five-Layer Routing Architecture" in `../../../_core/CONVENTIONS.md`.

- **Stage contracts**: Every stage CONTEXT.md has Inputs, Process, Outputs sections. No exceptions. See "Pattern 1: Stage Contracts" in `/_core/CONVENTIONS.md`.
- **Stage contracts**: Every stage CONTEXT.md has Inputs, Process, Outputs sections. No exceptions. See "Pattern 1: Stage Contracts" in `../../../_core/CONVENTIONS.md`.

- **Stage handoffs**: Output folders connect stages. Stage N writes to output/, Stage N+1 reads from there. See "Pattern 2: Stage Handoffs" in `/_core/CONVENTIONS.md`.
- **Stage handoffs**: Output folders connect stages. Stage N writes to output/, Stage N+1 reads from there. See "Pattern 2: Stage Handoffs" in `../../../_core/CONVENTIONS.md`.

- **One-way references**: If A references B, B must not reference A. See "Pattern 3: One-Way Cross-References" in `/_core/CONVENTIONS.md`.
- **One-way references**: If A references B, B must not reference A. See "Pattern 3: One-Way Cross-References" in `../../../_core/CONVENTIONS.md`.

- **Selective loading**: CONTEXT.md tables specify sections within files, not just filenames. See "Pattern 4: Selective Section Routing" in `/_core/CONVENTIONS.md`.
- **Selective loading**: CONTEXT.md tables specify sections within files, not just filenames. See "Pattern 4: Selective Section Routing" in `../../../_core/CONVENTIONS.md`.

- **One canonical home**: Every piece of information lives in one place. Other files point there. See "Pattern 5: Canonical Sources" in `/_core/CONVENTIONS.md`.
- **One canonical home**: Every piece of information lives in one place. Other files point there. See "Pattern 5: Canonical Sources" in `../../../_core/CONVENTIONS.md`.

- **CONTEXT.md = routing only**: No definitions, rules, or extended content in CONTEXT.md files. See "Pattern 6: CONTEXT.md = Routing, Not Content" in `/_core/CONVENTIONS.md`.
- **CONTEXT.md = routing only**: No definitions, rules, or extended content in CONTEXT.md files. See "Pattern 6: CONTEXT.md = Routing, Not Content" in `../../../_core/CONVENTIONS.md`.

- **Tool prerequisites**: If stages need system-level tools (Node.js, Python, LibreOffice), write setup guides in the relevant stage's references/ folder. See "Pattern 7: Tool Prerequisites" in `/_core/CONVENTIONS.md`.
- **Tool prerequisites**: If stages need system-level tools (Node.js, Python, LibreOffice), write setup guides in the relevant stage's references/ folder. See "Pattern 7: Tool Prerequisites" in `../../../_core/CONVENTIONS.md`.

- **Bundled skills**: Copy relevant Claude Code skills into skills/ folder. Skills provide domain knowledge (APIs, best practices, code examples) and can replace custom reference docs. Discover local skills and search GitHub during Stage 01. See "Pattern 9: Bundled Skills" in `/_core/CONVENTIONS.md`.
- **Bundled skills**: Copy relevant Claude Code skills into skills/ folder. Skills provide domain knowledge (APIs, best practices, code examples) and can replace custom reference docs. Discover local skills and search GitHub during Stage 01. See "Pattern 9: Bundled Skills" in `../../../_core/CONVENTIONS.md`.

- **Specs are contracts**: Specification stages define WHAT and WHEN, not HOW. No component names, frame numbers, or prop definitions in specs. The build stage has creative freedom within the quality floor. See "Pattern 10: Specs Are Contracts" in `/_core/CONVENTIONS.md`.
- **Specs are contracts**: Specification stages define WHAT and WHEN, not HOW. No component names, frame numbers, or prop definitions in specs. The build stage has creative freedom within the quality floor. See "Pattern 10: Specs Are Contracts" in `../../../_core/CONVENTIONS.md`.

- **Checkpoints**: Creative stages should pause for human steering between process steps. Agent completes a unit of work, presents options, human redirects. See "Pattern 11: Checkpoints" in `/_core/CONVENTIONS.md`.
- **Checkpoints**: Creative stages should pause for human steering between process steps. Agent completes a unit of work, presents options, human redirects. See "Pattern 11: Checkpoints" in `../../../_core/CONVENTIONS.md`.

- **Stage audits**: Creative and build stages include a quality checklist the agent runs before writing to output/. Each check has an unambiguous pass condition. See "Pattern 12: Stage Audits" in `/_core/CONVENTIONS.md`.
- **Stage audits**: Creative and build stages include a quality checklist the agent runs before writing to output/. Each check has an unambiguous pass condition. See "Pattern 12: Stage Audits" in `../../../_core/CONVENTIONS.md`.

- **Value validation**: Content-producing stages define value types and lock which ones each piece will deliver before drafting begins. See "Pattern 13: Value Validation" in `/_core/CONVENTIONS.md`.
- **Value validation**: Content-producing stages define value types and lock which ones each piece will deliver before drafting begins. See "Pattern 13: Value Validation" in `../../../_core/CONVENTIONS.md`.

- **Docs over outputs**: Reference docs are the authoritative source for how to build. Agents do not read other output/ files to learn patterns. See "Pattern 14: Docs Over Outputs" in `/_core/CONVENTIONS.md`.
- **Docs over outputs**: Reference docs are the authoritative source for how to build. Agents do not read other output/ files to learn patterns. See "Pattern 14: Docs Over Outputs" in `../../../_core/CONVENTIONS.md`.

- **Shared constants**: Code-producing workspaces define shared constant files (colors, fonts, timing) that all outputs import from. See "Pattern 15: Shared Constants" in `/_core/CONVENTIONS.md`.
- **Shared constants**: Code-producing workspaces define shared constant files (colors, fonts, timing) that all outputs import from. See "Pattern 15: Shared Constants" in `../../../_core/CONVENTIONS.md`.

- **Placeholder syntax**: `{{SCREAMING_SNAKE_CASE}}` for variables. `{{?SECTION}}...{{/SECTION}}` for conditional blocks (whole sections only). See `/_core/placeholder-syntax.md`.
- **Placeholder syntax**: `{{SCREAMING_SNAKE_CASE}}` for variables. `{{?SECTION}}...{{/SECTION}}` for conditional blocks (whole sections only). See `../../../_core/placeholder-syntax.md`.

- **Quality rules**: CONTEXT.md under 80 lines, reference files under 200 lines, no em dashes, lowercase-with-hyphens naming.
2 changes: 1 addition & 1 deletion workspaces/workspace-builder/stages/02-mapping/CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Turn the workflow map into formal stage contracts and verify the dependency grap
| Source | File/Location | Section/Scope | Why |
|--------|--------------|---------------|-----|
| Previous stage | `../01-discovery/output/workflow-map.md` | Full file | The workflow to formalize |
| Core conventions | `/_core/CONVENTIONS.md` | "Pattern 1: Stage Contracts" and "Pattern 3: One-Way Cross-References" | The rules for writing contracts |
| Core conventions | `../../../../_core/CONVENTIONS.md` | "Pattern 1: Stage Contracts" and "Pattern 3: One-Way Cross-References" | The rules for writing contracts |

## Process

Expand Down
8 changes: 4 additions & 4 deletions workspaces/workspace-builder/stages/03-scaffolding/CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ Generate the complete workspace folder structure, CONTEXT.md files, and placehol
|--------|--------------|---------------|-----|
| Previous stage | `../02-mapping/output/stage-contracts.md` | Full file | The contracts to implement as folders and files |
| Discovery output | `../01-discovery/output/workflow-map.md` | "Tool Prerequisites" and "Selected Skills" sections | Tools that need setup guides, skills to bundle |
| Template | `/_core/templates/stage-context-template.md` | Full file | Template for stage CONTEXT.md files (includes Checkpoints and Audit sections) |
| Template | `/_core/templates/workspace-claude-template.md` | Full file | Template for the workspace CLAUDE.md (includes What to Load section) |
| Template | `/_core/templates/workspace-context-template.md` | Full file | Template for the workspace CONTEXT.md |
| Syntax | `/_core/placeholder-syntax.md` | Full file | How to write placeholder variables |
| Template | `../../../../_core/templates/stage-context-template.md` | Full file | Template for stage CONTEXT.md files (includes Checkpoints and Audit sections) |
| Template | `../../../../_core/templates/workspace-claude-template.md` | Full file | Template for the workspace CLAUDE.md (includes What to Load section) |
| Template | `../../../../_core/templates/workspace-context-template.md` | Full file | Template for the workspace CONTEXT.md |
| Syntax | `../../../../_core/placeholder-syntax.md` | Full file | How to write placeholder variables |

## Process

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Build the onboarding questionnaire that hydrates the new workspace's placeholder
|--------|--------------|---------------|-----|
| Discovery output | `../01-discovery/output/workflow-map.md` | "User-Specific Variables" section | Variables that need onboarding questions |
| Scaffolding output | `../03-scaffolding/output/` | All files containing `{{PLACEHOLDER}}` patterns | Know where every placeholder lives |
| Template | `/_core/templates/questionnaire-template.md` | Full file | Format and design rules to follow |
| Syntax | `/_core/placeholder-syntax.md` | Full file | Placeholder and conditional section rules |
| Template | `../../../../_core/templates/questionnaire-template.md` | Full file | Format and design rules to follow |
| Syntax | `../../../../_core/placeholder-syntax.md` | Full file | Placeholder and conditional section rules |

## Process

Expand Down
4 changes: 2 additions & 2 deletions workspaces/workspace-builder/stages/05-validation/CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Verify the generated workspace against MWP conventions and fix any issues before
|--------|--------------|---------------|-----|
| Scaffolding output | `../03-scaffolding/output/` | Entire generated workspace | The workspace to validate |
| Questionnaire output | `../04-questionnaire-design/output/questionnaire.md` | Full file | Verify placeholder coverage |
| Core conventions | `/_core/CONVENTIONS.md` | Full file | The rules to validate against |
| Placeholder syntax | `/_core/placeholder-syntax.md` | Full file | Conditional section rules |
| Core conventions | `../../../../_core/CONVENTIONS.md` | Full file | The rules to validate against |
| Placeholder syntax | `../../../../_core/placeholder-syntax.md` | Full file | Conditional section rules |

## Process

Expand Down