Skip to content

docs: fix references to things that do not exist #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Avicennasis wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix references to things that do not exist #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ workspaces/workspace-builder/stages/*/output/*
# Node dependencies
node_modules/

# Python bytecode
__pycache__/
*.pyc

# OS files
.DS_Store
Thumbs.db
Expand Down
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,14 +72,14 @@ workspace/
CONTEXT.md
references/
output/
_config/ # Layer 3: brand, voice, design system
brand-vault/ # Layer 3: brand, voice, design system (name varies)
shared/ # Layer 3: cross-stage resources
skills/ # Layer 3: bundled domain knowledge
setup/
questionnaire.md # One-time onboarding
```

The numbering encodes execution order. The folder boundaries enforce separation of concerns. The `output/` directories are the Layer 4 handoff points: the output of stage 01 becomes available as input to stage 02. If a human edits a file in `01-research/output/` before running stage 02, the agent picks up the edited version. The `references/` directories and `_config/` folder hold Layer 3 material -- stable knowledge that persists across runs.
The numbering encodes execution order. The folder boundaries enforce separation of concerns. The `output/` directories are the Layer 4 handoff points: the output of stage 01 becomes available as input to stage 02. If a human edits a file in `01-research/output/` before running stage 02, the agent picks up the edited version. The `references/` directories and the workspace-level config folder (`brand-vault/`, `design-system/`) hold Layer 3 material -- stable knowledge that persists across runs.

Layer 2 is the control point. Each stage contract includes an Inputs table that specifies exactly which files from Layers 3 and 4 to load, and which sections of those files are relevant. Without this scoping, an agent would either load everything or guess. The Inputs table makes the selection explicit, editable, and auditable.

Expand Down
2 changes: 2 additions & 0 deletions workspaces/workspace-builder/references/conventions-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ The most important conventions for building a new workspace:

- **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`.

- **Questionnaire design**: Onboarding questionnaires configure the production system, not a specific run. Flat, all at once, system-level only. Derive fields where possible instead of asking. See "Pattern 8: Questionnaire Design" 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`.
Expand Down