@jamie-tam/forge 6.0.0

package/skills/build-prototype/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: build-prototype
+description: "Use to scaffold a working POC from a locked wireframe. Produces a runnable Vite + React + TS app at pocs/{name}-prototype/ with seed data, in-memory state, and screens that mirror the wireframe states. The prototype is the verification surface for concept + UX before any production code is written."
+---
+
+# Build Prototype
+
+## Overview
+
+Once a wireframe is locked, the prototype turns it into something the user can run. Real React components, real state transitions, real seed data — but in-memory storage, mocked external calls, no auth, no production hardening. The prototype answers "does this actually work as an interaction model?" and surfaces gotchas that the wireframe couldn't.
+
+**Core principle:** the prototype is the spec. Mocks and in-memory state are tolerated here and ONLY here. The shape this skill produces becomes the shape the production build (Phase 6) inherits.
+
+**Announce at start:** "I'm using the build-prototype skill to scaffold a working POC from the locked wireframe."
+
+## When to Use
+
+- Phase 4 of a prototype-driven flow (after wireframe is locked, before Phase 5 codification)
+- For `/feature` on existing apps: scaffold a `pocs/{feature-name}-prototype/` mini-prototype branch of the existing app's tech stack — same skill, smaller scope
+- Ad-hoc when a wireframe is mature enough to validate via running code
+
+**Do NOT skip when:**
+- The wireframe "looks complete" — wireframe completeness is necessary but not sufficient; running code surfaces interaction-model issues the wireframe can't
+- The team is in a hurry to ship — skipping prototype is what produces "implementation exists but is not wired" in production
+
+## Stack (single, opinionated)
+
+The prototype stack is fixed. No variants.
+
+| Layer | Tool |
+|---|---|
+| Build / dev server | Vite (latest stable) |
+| UI framework | React 18 |
+| Type system | TypeScript strict |
+| Styling | Tailwind v4 |
+| State | Zustand v5 |
+| Icons | lucide-react |
+| Lint + format | Biome |
+| E2E (later) | Playwright |
+
+Backend-heavy products that don't ship a frontend in production STILL get a Vite + React prototype here — the frontend is the verification surface during development (admin panel, request inspector, fixture browser, integration playground). For pure backend products, the prototype's frontend is the dev tooling.
+
+## Inputs
+
+| Source | Required | Purpose |
+|---|---|---|
+| Locked wireframe HTML | yes | Visual + interaction-model spec |
+| Wireframe README | yes | View list, hash routes, design intent |
+| Concept slides | yes | High-level intent + out-of-scope context |
+| Existing prototype (if extending) | optional | Codebase to extend |
+| Manifest at `.forge/work/{type}/{name}/manifest.yaml` | yes | Phase state target |
+
+## Outputs
+
+A working Vite + React app at `pocs/{name}-prototype/`:
+
+```
+pocs/{name}-prototype/
+├── package.json
+├── vite.config.ts
+├── tsconfig.json
+├── tailwind.config.ts
+├── biome.json
+├── index.html
+├── src/
+│   ├── main.tsx          # entry
+│   ├── App.tsx           # router shell
+│   ├── routes/           # one file per top-level route
+│   ├── components/       # reusable UI primitives
+│   ├── features/         # feature-area folders, each owning its screens
+│   ├── store/            # Zustand stores
+│   ├── data/             # seed data (TS const arrays, NOT db)
+│   ├── types/            # shared TS types
+│   └── styles/
+│       └── tokens.css    # design tokens extracted from wireframe
+├── README.md             # what this prototype is, how to run it, what's mocked
+└── .forge/
+    ├── feedback.md       # running list of user iteration feedback
+    └── convergence-log.md # rejected approaches, tried-and-discarded
+```
+
+Run with:
+```bash
+cd pocs/{name}-prototype && npm install && npm run dev
+```
+
+## Process
+
+### Step 0: locate inputs
+
+| Input | How to find |
+|---|---|
+| Repo root | `git rev-parse --show-toplevel` or `${CLAUDE_PROJECT_DIR}` |
+| Manifest | The single in-progress manifest under `.forge/work/*/*/manifest.yaml`. Multiple in flight = ask user. |
+| Wireframe path | Manifest's `artifacts.wireframe.html_path`, or default `pocs/{name}-wireframe/index.html` |
+| Concept deck | Manifest's `artifacts.concept.deck_path`, or default `decks/{name}/slides.md` |
+| Output target | `pocs/{name}-prototype/` (default) or override via manifest's `artifacts.prototype.path` (set by this skill on Step 6 lock) |
+
+If the manifest does not yet have `artifacts.wireframe.locked_at`, surface the gap and stop — this skill runs after wireframe lock.
+
+### Step 1: scaffold the project
+
+Initialize the Vite + React + TS skeleton:
+
+```bash
+cd <repo-root>
+npm create vite@latest pocs/{name}-prototype -- --template react-ts
+cd pocs/{name}-prototype
+npm install
+npm install -D @biomejs/biome tailwindcss@next @tailwindcss/vite
+npm install zustand@^5 lucide-react
+```
+
+Then add forge-standard configs:
+- Replace `tailwind.config.ts` with v4 config that reads the wireframe's design tokens
+- Add `biome.json` with forge defaults (2-space indent, double quotes, semicolons)
+- Update `vite.config.ts` to include the `@tailwindcss/vite` plugin
+- Replace `src/App.tsx` skeleton with the router shell
+- Create `src/styles/tokens.css` extracted from the wireframe's CSS variables
+
+Create the project README listing what's mocked and how to run.
+
+### Step 2: identify partitions
+
+Read the wireframe's view list (from wireframe README + the `VIEWS` registry in the wireframe HTML). Identify natural partitions — independent feature areas that can be built in parallel.
+
+Partition heuristics:
+- **By user role** — agent screens vs supervisor screens (different feature folders, no overlap)
+- **By tab cluster** — distinct top-level tabs in the wireframe (separate route trees)
+- **By system area** — UI screens vs tutorial overlay vs settings panel
+
+If the wireframe is small (≤5 views, single user role) → single partition (no parallel). If the wireframe is medium (6-15 views, role-distinct or area-distinct) → 2-3 partitions. Don't over-partition — each partition's prototype-builder needs enough work to justify its own context.
+
+Document the partition plan in `pocs/{name}-prototype/.forge/partition-plan.md` so subsequent iterations can resume.
+
+### Step 3: dispatch prototype-builder per partition
+
+For each partition, dispatch a `prototype-builder` subagent in parallel. Each instance receives:
+- The wireframe HTML
+- The wireframe README
+- Its assigned partition (specific views to build)
+- File-ownership boundaries (which `src/features/{area}/` is yours; what's shared)
+- The shared scaffold (types, store skeleton, routes registry) — read-only for the subagent
+
+The subagent returns:
+- Files to write under its assigned `src/features/{area}/`
+- Updates to add to shared types (in `src/types/`)
+- Updates to add to the shared store (Zustand slice)
+- Seed data files
+
+The main session merges results: filesystem-level merge for non-overlapping partition output; for shared updates (types, store), apply each subagent's diff in turn.
+
+### Step 4: verify
+
+After all partitions land:
+
+```bash
+cd pocs/{name}-prototype
+npm run dev          # smoke test: dev server starts, no compile errors
+npx biome check .    # lint passes
+```
+
+Use Playwright to verify each wireframe view has a corresponding running screen:
+
+```bash
+npx playwright codegen http://localhost:5173
+```
+
+Click through each route. Each screen should:
+- Render without console errors
+- Have the same visual structure as the wireframe state
+- Have working interactions (clicks navigate, forms accept input, state updates)
+- Use seed data (real-shaped, fake-content)
+
+Capture findings in `pocs/{name}-prototype/.forge/feedback.md` if there's any drift between prototype and wireframe.
+
+### Step 5: side-effect capture during iteration
+
+Phase 4 is also when real gotchas + conventions emerge. During iteration:
+
+- **Gotchas**: every time prototype-builder hits a state-management surprise, library quirk, framework mounting issue, or type-system pothole, write to `aiwiki/gotchas/{date}-{slug}.md` per the gotcha schema. The wiki-lint hook validates on save.
+- **Conventions**: when patterns settle (file naming, import order, state-shape conventions, design-token usage), write to `aiwiki/conventions/{slug}.md`. The `prototype-reviewer` flags new conventions emerging across iteration cycles.
+
+These outputs feed Phase 5 codification. Do not skip them — Phase 5 reads from `aiwiki/gotchas/` and `aiwiki/conventions/` directly.
+
+### Step 6: emit lock signal
+
+When the user emits "satisfied — go to production" (or equivalent), update the manifest:
+- `artifacts.prototype.path: pocs/{name}-prototype/`
+- `artifacts.prototype.locked_at: <ISO-8601 timestamp>`
+
+Presence of `artifacts.prototype.locked_at` is the lock signal that Phase 5 (`harden`) reads. The locked prototype is the input to harden.
+
+## Backend integration during prototype
+
+Backend-heavy products: the prototype frontend connects to a local backend (Vite proxy to a separate dev server) OR uses fully in-memory mocks. Two patterns:
+
+| Pattern | Use when |
+|---|---|
+| Local backend + Vite proxy | Backend can be run locally with seed data; integration concerns are real and worth verifying |
+| Fully in-memory | Backend is complex enough that running it would slow the prototype loop. Stub responses in `src/data/mocks.ts`. |
+
+Document the choice in `pocs/{name}-prototype/README.md` so Phase 5 codification knows what's mocked.
+
+## What build-prototype does NOT do
+
+- Does NOT write production code (mocks and in-memory state are intentional here)
+- Does NOT implement real auth (seed user; real auth is a Phase 6 production-build delta)
+- Does NOT set up CI / deployment (those are Phase 6/7)
+- Does NOT run code review or static analysis gates (those are Phase 6)
+- Does NOT add E2E test infrastructure beyond Playwright codegen for verification (full E2E suite is Phase 6)
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Hardening the prototype (real auth, real DB, error handling for unlikely failures) | Stop. The prototype is the spec; hardening is Phase 6's job. Time spent here is wasted twice. |
+| Skipping seed data and using empty arrays | Empty UIs hide layout bugs. Use realistic-shaped seed data with placeholder content. |
+| One giant feature folder | Partition by feature area. Even a small prototype benefits from `src/features/cases/`, `src/features/users/` etc. |
+| Skipping `pocs/{name}-prototype/.forge/feedback.md` | The feedback file is how iteration converges; without it, the prototype just keeps changing without a plan |
+| Missing Biome config | Forge convention; downstream tooling expects it |
+| Inventing screens not in the wireframe | The wireframe is the spec; if a screen is missing, surface the gap to the user (the wireframe needs an iteration), don't extrapolate |
+| Pre-promoting prototype gotchas to typed pages without `support-gotcha` | Gotchas use the `support-gotcha` skill flow; lint validates the schema. Write them through the proper channel. |
+
+## Red Flags
+
+**Never:**
+- Implement real auth, real DB, real external API calls (Phase 6's job)
+- Skip wireframe verification — every wireframe view must have a corresponding running screen
+- Lock the prototype with known-broken interactions (the lock signal means "this is what production should match")
+- Over-partition (more than 3 partitions for typical work; if you need 4+, the wireframe is too sprawling — push back)
+
+**Always:**
+- Match the wireframe's visual structure (Tailwind classes derived from the design tokens; lucide icons matching the wireframe's icons)
+- Use realistic-shaped seed data — placeholder content but real data shapes
+- Capture gotchas + conventions during iteration (they're Phase 5 inputs)
+- Verify with `npm run dev` + click-through before any iteration cycle ends
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Locked wireframe HTML + README, concept deck, manifest |
+| **Produces** | `pocs/{name}-prototype/` (full Vite + React app), `pocs/{name}-prototype/.forge/feedback.md`, `aiwiki/gotchas/` + `aiwiki/conventions/` (during iteration) |
+| **Updates manifest** | `artifacts.prototype.{path, locked_at}` |
+| **Triggers** | wiki-lint on every `aiwiki/**` write during iteration; phase-close dream after lock |
+
+## Integration
+
+| Caller | When |
+|---|---|
+| Wireframe-lock event in `/feature` and `/greenfield` | Phase 3 → Phase 4 transition |
+| Manual invocation | When a wireframe is mature enough to verify via running code |
+
+| Dispatches | For |
+|---|---|
+| `prototype-builder` subagent (multi-instance) | Per-partition implementation in own context windows |
+
+| Pairs with | For |
+|---|---|
+| `iterate-prototype` skill | Polish loop after initial scaffold; user feedback drives revisions |
+| `prototype-reviewer` agent | Drift check between prototype and wireframe before Phase 5 |
+| `support-gotcha` skill | Capture gotchas surfaced during iteration |
+| `harden` skill | Phase 5 successor — reads the locked prototype as input |

package/skills/build-scaffold/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: build-scaffold
+description: "Use after architecture is approved to generate project directory layout, build tooling, Docker config, and test infrastructure for a new codebase."
+---
+
+# Build Scaffold
+
+## Overview
+
+Set up a new project from scratch with production-ready structure, build tooling, containerization, and test infrastructure.
+
+**Core principle:** A project that builds and tests from the first commit is a project that stays healthy.
+
+**Announce at start:** "I'm using the build-scaffold skill to set up the project structure."
+
+## When to Use
+
+- Greenfield projects (no existing code)
+- `/greenfield` command (scaffold phase)
+- When the user says "start a new project" or "set up from scratch"
+
+**Not for:**
+- Adding features to existing projects (use build-tdd)
+- Restructuring existing projects (use /refactor command)
+
+## Prerequisites
+
+Before scaffolding, the project profile must exist (CLAUDE.md or equivalent specifying tech stack, frameworks, database). Architecture context is also required, sourced from whichever upstream phase applies to the work:
+
+- **Prototype-driven flow** (default `/feature`, `/greenfield`): the codified architecture in `aiwiki/architecture/` and the slice graph in the work manifest, produced by the `harden` skill at Phase 5 (codify).
+- **Non-prototype fallback flow** (libraries, internal tools where wireframe makes no sense): architecture artifacts from `plan-architecture` in `.forge/work/{type}/{name}/architecture/` and key decisions in `aiwiki/decisions/`.
+
+If neither is available, stop and request — do not guess at technology choices.
+
+## Step 0: Codex Delegate Check
+
+Before running any scaffold steps, check if Codex should build the scaffold instead of Claude:
+
+1. Run `codex --version`. If exit code is non-zero, Codex is unavailable — skip this step silently and proceed to Step 1. Never prompt the user about Codex when it isn't installed.
+2. If Codex is available, read `codex.delegate` in `.forge/local.yaml`:
+   - **`always`** or the user explicitly requested Codex as the builder → dispatch Codex with the architecture artifacts, project profile, and this skill's SKILL.md. Codex generates the complete scaffold. Skip to Step 7 (Verify) when Codex returns. Quality gate still applies.
+   - **`ask`** or absent → prompt once per `protocols/codex.md`. Save the answer if the user picks "always" or "never".
+   - **`never`** → proceed with Claude-driven scaffold below.
+
+See the **Codex Integration** section at the end for the exact invocation command and context paths.
+
+## The Scaffold Process
+
+### Step 1: Read Project Profile
+
+Read CLAUDE.md (or the architecture artifacts) for:
+
+```
+- Language / runtime (Node.js, Python, Go, Rust, Java, etc.)
+- Framework (Express, FastAPI, Gin, Actix, Spring, etc.)
+- Database (PostgreSQL, MySQL, MongoDB, SQLite, etc.)
+- Frontend framework (React, Vue, Svelte, etc.) if applicable
+- Package manager (npm, yarn, pnpm, pip, poetry, cargo, etc.)
+- Testing framework (Jest, Vitest, pytest, go test, etc.)
+- CI/CD target (GitHub Actions, GitLab CI, etc.)
+```
+
+**Do not assume defaults.** If the project profile does not specify a choice, ask the user. Every technology decision matters.
+
+### Step 2: Generate Directory Structure
+
+Follow conventions for the detected stack. General pattern:
+
+```
+project-root/
+├── src/                          # Application source code
+│   ├── [domain-grouped dirs]     # Organized by feature/domain, NOT by type
+│   └── index.ts / main.py / main.go  # Entry point
+├── tests/                        # Test files (mirror src/ structure)
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── scripts/                      # Build, deploy, utility scripts
+├── docs/                         # Project documentation
+├── docker/                       # Docker-related files (if complex)
+├── .github/ or .gitlab-ci/       # CI/CD configuration
+└── [config files at root]        # package.json, pyproject.toml, etc.
+```
+
+**Stack-specific structures:**
+
+#### Node.js / TypeScript
+```
+├── src/
+│   ├── modules/                  # Feature modules
+│   │   └── [feature]/
+│   │       ├── [feature].controller.ts
+│   │       ├── [feature].service.ts
+│   │       ├── [feature].repository.ts
+│   │       ├── [feature].types.ts
+│   │       └── [feature].test.ts
+│   ├── common/                   # Shared utilities
+│   │   ├── middleware/
+│   │   ├── errors/
+│   │   └── utils/
+│   ├── config/                   # Configuration loading
+│   └── app.ts                    # Application setup
+├── tests/
+│   ├── integration/
+│   └── e2e/
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts / jest.config.ts
+└── eslint.config.js
+```
+
+#### Python
+```
+├── src/
+│   └── [package_name]/
+│       ├── __init__.py
+│       ├── [module]/
+│       │   ├── __init__.py
+│       │   ├── routes.py
+│       │   ├── service.py
+│       │   ├── models.py
+│       │   └── schemas.py
+│       ├── core/
+│       │   ├── config.py
+│       │   └── dependencies.py
+│       └── main.py
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── conftest.py
+├── pyproject.toml
+└── alembic/ (if using SQLAlchemy)
+```
+
+#### Go
+```
+├── cmd/
+│   └── server/
+│       └── main.go
+├── internal/
+│   ├── [domain]/
+│   │   ├── handler.go
+│   │   ├── service.go
+│   │   ├── repository.go
+│   │   └── models.go
+│   ├── config/
+│   └── middleware/
+├── pkg/                          # Public packages (if any)
+├── go.mod
+├── go.sum
+└── Makefile
+```
+
+**Adapt structure to the specific framework** (e.g., Next.js uses `app/` or `pages/`, Django uses `manage.py` and app directories).
+
+### Step 3: Set Up Build Tooling
+
+Create the appropriate package manifest for the detected stack. Adapt to the specific framework in use (Next.js, Django, FastAPI, etc.).
+
+- **Node.js** (`package.json`): include scripts `dev`, `build`, `start`, `test`, `test:coverage`, `lint`, `lint:fix`, `typecheck`. Pin Node version in `engines`. Commit the lockfile.
+- **Python** (`pyproject.toml`, PEP 621): configure `[tool.pytest.ini_options]`, `[tool.ruff]` (line-length 100), and `[tool.mypy]`. Pin Python version in `.python-version`. If the package manager produces a lockfile (`poetry.lock`, `uv.lock`, `Pipfile.lock`), commit it; plain pip has no standard lockfile.
+- **Go** (`go.mod` + `Makefile`): Makefile targets `build`, `test`, `lint`, `run`. Pin Go version in `go.mod`. Commit `go.sum`.
+
+**Key rule:** every script/target must work immediately after setup. If `npm test` fails on a fresh clone, the scaffold is broken.
+
+### Step 3.5: Install CSS Framework (Frontend Projects Only)
+
+If the project has a frontend and `DESIGN.md` exists at the project root (from the `plan-design-system` skill):
+
+1. **Read `DESIGN.md`** at the project root for design tokens (colors, typography, spacing, component conventions)
+2. **Install the chosen CSS framework** (Tailwind, CSS Modules, styled-components, etc.) as specified in the design tokens
+3. **Configure the framework** — set up Tailwind config with the design token colors, or create CSS custom properties from the tokens
+4. **Apply the base theme** — set the global background, text color, and font family from the design tokens
+5. **Verify the build succeeds** with the CSS framework installed
+
+If no `DESIGN.md` exists (e.g., backend-only project), skip this step.
+
+### Step 4: Docker Setup
+
+Create Docker environment for reproducible development.
+
+**Dockerfile** — multi-stage production build:
+- `builder` stage installs dependencies and runs build
+- `runtime` stage copies build output via `COPY --from=builder`
+- Pin base image to a specific version (NEVER `:latest`)
+- `EXPOSE` the app port, `CMD` runs the start command
+
+**docker-compose.yml** — include every service the approved architecture requires (app, db, cache, queue, etc.). Omit services the architecture doesn't use; if the architecture uses no external services, compose may be omitted or contain only the app.
+- `app`: `build: .`, port from `${APP_PORT}`, env from `.env`, volumes for hot-reload. If a db service is present, add `depends_on: db: condition: service_healthy`
+- `db` (only if the architecture uses a containerized database — skip for SQLite or externally managed databases): pinned image (e.g., `postgres:16-alpine`), named volume for persistence, healthcheck (e.g., `pg_isready`)
+- Top-level `volumes` block for any named volumes declared above
+
+**.dockerignore** — exclude `node_modules/` (or equivalent), `.git/`, `.env*`, `*.log`, `dist/`/`build/`, `coverage/`, `.forge/`.
+
+**Key rules:**
+- Multi-stage builds for production images
+- Healthchecks on every service that others depend on
+- Volumes for hot-reload in development, not production
+- Pinned base image versions — no `latest` tag
+- `.dockerignore` must be present
+
+### Step 5: Environment Configuration
+
+**`.env.example`** — document every environment variable the app reads. Group by purpose (Application, Database, Auth, External Services). Use safe placeholder values; never real secrets. Include a comment per variable explaining what it does. `.env` itself must be gitignored.
+
+**`.gitignore`** — generate stack-idiomatic entries. Always include: `.env*` (except `.env.example`), `*.log`, coverage outputs, build artifacts, `.forge/`, `.worktrees/`, and the stack's dependency/cache dir (`node_modules/`, `__pycache__/`, `vendor/`, `target/`, etc.).
+
+### Step 6: Initial Test Infrastructure
+
+Set up the test runner and write the first test:
+
+**Test runner configuration** — configure the project's test framework (Vitest/Jest for Node, pytest for Python, `go test` for Go, etc.) with:
+- Coverage enabled (v8, c8, coverage.py, `-cover`)
+- Coverage thresholds at **80% on statements, branches, functions, lines** (or the stack equivalent)
+- Test directory matches the structure in Step 2
+
+**Smoke test** — write one trivial test per stack's idiom (e.g., `expect(true).toBe(true)` for Vitest, `assert True` for pytest, a minimal `t.Run` for Go). Its only job is to prove the test runner works. MUST pass before proceeding to any implementation.
+
+### Step 7: Verify Build and Tests
+
+Run the full verification sequence:
+
+```bash
+# 1. Install dependencies
+[package-manager] install
+
+# 2. Build the project
+[build-command]
+
+# 3. Run linter
+[lint-command]
+
+# 4. Run tests
+[test-command]
+
+# 5. Docker build (if Docker is set up)
+docker compose build
+
+# 6. Docker up + health check (optional but recommended)
+docker compose up -d
+docker compose ps  # verify all services healthy
+docker compose down
+```
+
+**All steps must pass.** If any step fails:
+1. Fix the issue immediately
+2. Re-run verification from the beginning
+3. Do not proceed to build-tdd until everything passes
+
+### Step 8: Initial Commit
+
+Once everything passes:
+
+```bash
+git init
+git add .
+git commit -m "feat: initial project scaffold
+
+- Project structure for [stack]
+- Build tooling configured
+- Docker environment set up
+- Test infrastructure verified
+- All tests passing"
+```
+
+## TDD Exemption
+
+Scaffolding is explicitly exempt from the build-tdd "NO production code without a failing test" rule. Scaffold generates boilerplate infrastructure (directory structure, config files, Docker setup, build tooling) that is verified by the post-scaffold checklist below, not by TDD. The initial smoke test written during scaffolding proves the infrastructure works. Once scaffold is complete and handed off to build-tdd, normal TDD discipline applies to all subsequent code.
+
+## Post-Scaffold Checklist
+
+Before handing off to build-tdd, verify:
+
+- [ ] Directory structure follows stack conventions
+- [ ] Package manifest exists with all required scripts
+- [ ] All scripts work (`dev`, `build`, `test`, `lint`)
+- [ ] Docker builds successfully
+- [ ] docker-compose starts all services with health checks
+- [ ] `.env.example` has all required variables
+- [ ] `.gitignore` covers all generated/sensitive files
+- [ ] Test runner configured with coverage thresholds
+- [ ] Smoke test passes
+- [ ] Linter passes with zero warnings
+- [ ] Initial commit made
+
+**Cannot check all boxes? Fix before proceeding. The scaffold is the foundation.**
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skipping Docker setup | Docker-first for reproducibility. Always set up. |
+| Missing .env.example | Every env var must be documented. No guessing. |
+| No test infrastructure | First test must pass before any implementation. |
+| Using `latest` Docker tag | Pin specific versions for reproducibility. |
+| Organizing by file type | Organize by feature/domain. Not controllers/, services/, models/. |
+| Missing .gitignore entries | Generate comprehensive ignore file for the stack. |
+| Scripts that do not work | Every script must work on fresh clone. Verify each one. |
+| No linter configured | Linting catches issues early. Configure from day one. |
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Architecture context (codified `aiwiki/architecture/` + manifest slice graph from `harden`, OR `.forge/work/{type}/{name}/architecture/` from `plan-architecture`) + project profile (CLAUDE.md) |
+| **Produces** | Project directory structure, `package.json` / `pyproject.toml` / `go.mod`, `Dockerfile`, `docker-compose.yml`, `.env.example`, `.gitignore`, test runner config, initial smoke test |
+| **Feeds into** | `build-tdd` at Phase 6 (production-build) |
+| **Updates manifest** | `artifacts.scaffold.locked_at` (scaffold complete) — slice work proceeds against the scaffolded structure |
+
+## Codex Integration
+
+**Mode:** Delegate | **Protocol:** `protocols/codex.md` | **Consent key:** `codex.delegate`
+
+**When:** Step 0, if Codex is installed AND `codex.delegate` is `always` (or the user accepts the `ask` prompt).
+
+**Context to pass:**
+- Path to architecture (either `aiwiki/architecture/` from harden, or `.forge/work/{type}/{name}/architecture/` from plan-architecture)
+- Slice graph from manifest (harden flow) or `tasks.md` (plan-task-decompose flow)
+- Path to this skill: `skills/build-scaffold/SKILL.md`
+
+**What Codex does:**
+- Generate the project scaffold following the architecture spec
+- Follow the methodology defined in this skill's SKILL.md (directory patterns in Step 2, adapt to the detected framework)
+
+**Prompt focus:** "Generate the project scaffold following the architecture artifacts at [paths]. Follow the methodology in skills/build-scaffold/SKILL.md. Output the complete file tree with contents."
+
+**Quality gate:** Scaffold output goes through standard verification (Step 7) — directory structure matches architecture, configuration files are valid, initial tests pass. Claude runs verification regardless of who built.
+
+---
+
+## Integration
+
+**Called by:**
+- `/greenfield` command (after architecture phase)
+
+**Pairs with:**
+- `harden` (prototype-driven flow: reads codified architecture + slice graph from `aiwiki/` and manifest)
+- `plan-architecture` (non-prototype fallback flow: reads `.forge/work/.../architecture/`)
+- `build-tdd` (hands off a working project ready for Phase 6 production-build)
+- `deliver-onboarding` (scaffold creates the foundation that onboarding documents)