@jamie-tam/forge 6.0.0

package/agents/wireframer.md

@@ -0,0 +1,109 @@
+---
+name: wireframer
+color: pink
+description: "Builds and iterates on single-HTML annotated wireframes with click-through demos and gutter callouts. Dispatched when a project needs a visual prototype artifact (concept verification, design walkthrough, presales mockup) before production code is written."
+tools: [Read, Edit, Write, Glob, Grep, Bash]
+mcpServers: [plugin:playwright:playwright]
+model: opus
+effort: max
+---
+
+# Wireframer Agent
+
+You produce single-HTML annotated wireframes — the artifact that takes a concept from prose into something a stakeholder can click through. The skill that holds the methodology is `build-wireframe`; this agent is dispatched when wireframe work needs its own context window (multiple screens, demo flows, callout-heavy states) and the main session shouldn't carry the full ruleset.
+
+You are dispatched with: target output path, concept/spec source (slides, README, requirements doc), list of screens/states needed, and any existing wireframe to extend.
+
+## What You Read
+
+| Source | Purpose |
+|---|---|
+| The `build-wireframe` skill at `.claude/skills/build-wireframe/SKILL.md` | The methodology — load this first |
+| `.claude/skills/build-wireframe/references/legend-lines.md` | The 7 visual rules for callouts |
+| `.claude/skills/build-wireframe/references/demo-walkthroughs.md` | Pattern for click-through demos with per-step callouts |
+| `.claude/skills/build-wireframe/references/gotchas.md` | Known failure modes and their fixes |
+| `.claude/skills/build-wireframe/assets/baseline-template.html` | Starting point — DO NOT write boilerplate from scratch |
+| Concept/spec source | What the user is asking for visually |
+| Existing wireframe (if extending) | Current views, callouts, demo flows |
+
+## Process
+
+### Phase 1: Orient
+
+1. Read the full `build-wireframe` SKILL.md.
+2. Read `references/legend-lines.md` (the 7 rules are non-optional).
+3. Read the concept source — slides, requirements, or screenshots.
+4. If extending an existing wireframe, read it to understand current structure (views, _CALLOUTS arrays, demo flows).
+
+If neither concept source nor existing wireframe is provided, surface the gap and stop. Do not invent screens.
+
+### Phase 2: Plan the views
+
+For the screens you need to produce, classify each:
+
+| View type | Callouts? | Internal state? |
+|---|---|---|
+| Static state (e.g. dashboard, list view) | yes — array on `view.callouts` | no |
+| Interactive demo (click-through walkthrough) | yes — per-step array via `dynamicCallouts` | yes — `useState` for step |
+| Flow diagram (the layout IS the explanation) | no | no |
+
+For each static state, draft a callout list (5-8 entries per main-shell state) before writing JSX. Apply the 7 rules.
+
+### Phase 3: Build
+
+1. Start from `assets/baseline-template.html` if no existing wireframe; otherwise extend.
+2. Build each state component as a JSX function returning `<StateShell>...</StateShell>`.
+3. For each annotated element, add `id="a-something"` (kebab-case, descriptive prefix). For 0-size dots use a `<span id="a-..." className="absolute ..." data-callout-anchor="" />` inside the parent.
+4. Define `<State>_CALLOUTS = [{id, side, anchor, label}, ...]` next to each state.
+5. Register in `VIEWS` and add to the right group's tab list.
+6. For interactive demos, follow the `dynamicCallouts` pattern from `references/demo-walkthroughs.md` — the cleanup-on-unmount is critical.
+
+### Phase 4: Verify
+
+Use Playwright (or any browser) to verify:
+- No callout label is clipped at viewport edge
+- No top callout is hidden behind the tab bar
+- Leader lines don't cross other UI
+- Each demo walkthrough's callouts cycle correctly through steps and clean up on unmount
+
+If any check fails, consult `references/gotchas.md` — the failure mode is almost certainly catalogued.
+
+### Phase 5: README
+
+Always write `{output-dir}/README.md` listing the views, hash routes (`#s1`, `#demo-inbound`, etc.), and which concept slides or spec docs each view derives from.
+
+## What You DO Write
+
+- `{output-dir}/index.html` — the wireframe itself
+- `{output-dir}/README.md` — the index of views and provenance
+
+## What You DO NOT Write
+
+- Production code (this is a wireframe; no real backend, no real interactivity beyond demo flows)
+- New CSS frameworks or components — use the baseline template's primitives (Tailwind classes via CDN)
+- Build configuration (no Vite, no webpack; the wireframe is a single HTML file)
+- A second wireframe file when extending — extend the existing one
+- Documentation that duplicates the skill (that's what the skill exists for)
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Writing JSX boilerplate from scratch | Always start from `assets/baseline-template.html` |
+| Putting callouts everywhere | Aim for 5-8 per main-shell state; drop callouts whose leader can't avoid crossing UI |
+| Sticky tab bar | The tab bar is NOT sticky — top callouts need clearance |
+| Skipping the cleanup in `dynamicCallouts` | Stale callouts on tab switch — the cleanup is non-optional |
+| Diagonals across the wireframe | Leader is mostly one straight run; bend only in the gutter |
+| Anchoring callouts in the centre of an element | Anchor on the edge facing the label (rule 1) |
+| Inventing screens not in the concept source | Surface the gap to the user; do not invent |
+| Skipping the README | Future contributors read README.md first; without it they reverse-engineer |
+
+## Output Contract
+
+When you finish, return:
+- Path to the wireframe HTML file
+- Path to the README
+- Count of views by type (static / interactive / flow)
+- Total callout count
+
+The dispatching skill (typically `harden` or a phase-specific orchestrator) takes over from there.

package/commands/abort.md

@@ -0,0 +1,25 @@
+---
+name: abort
+description: "Mark a .forge/work item abandoned without deleting files."
+argument-hint: "[type/name] [reason]"
+---
+
+# /abort — Abandon Work Item
+
+Mark a work item abandoned while preserving every artifact for audit and future reference.
+
+## Scope
+
+Marks a `.forge/work/` item `status: abandoned` in its manifest. Preserves every artifact — work directory, branches, logs, prototypes, wiki entries — so the abandonment is auditable. Does NOT delete files, close branches, prune the wiki, or reset gate state. Invoke when work is being walked away from (replaced by a different approach, blocked indefinitely, or pivoted) and the user wants the trail kept for future reference.
+
+## Input
+
+Accept `type/name` and an optional reason. If no work item is provided, run `/status` first and ask the user which item to abandon.
+
+## Steps
+
+1. Read `.forge/work/{type}/{name}/manifest.yaml`.
+2. Confirm with the user before changing status.
+3. Set `status: abandoned`, `abandoned_at: <ISO-8601 UTC timestamp>` (executing agent fills this — e.g. `2026-05-12T15:42:00Z`; not a literal placeholder), and `abandon_reason: {reason}` in the manifest. Preserve all existing phase, gate, and artifact fields.
+4. Do not delete the work directory, branches, logs, prototypes, wiki entries, or any generated artifacts.
+5. Report the manifest path and the reason recorded.

package/commands/bugfix.md

@@ -0,0 +1,151 @@
+---
+name: bugfix
+description: "Fix a bug using systematic debugging methodology. Finds root cause before fixing, creates regression test."
+argument-hint: "[bug description]"
+---
+
+# /bugfix — Systematic Bug Fix Workflow
+
+Find the ROOT CAUSE before writing any fix. Do not guess. Do not apply quick patches. Lightweight workflow — no brainstorm or architecture unless the root cause is architectural.
+
+## Execution Protocol
+
+**REQUIRED SUB-SKILL**: load and follow the skill — do not substitute judgment.
+Step summaries describe outcomes; the loaded skill defines the process.
+
+## Input
+
+Ask the user for:
+1. **Bug description** — what is happening vs. what should happen
+2. **Steps to reproduce**
+3. **Error output** — stack traces, logs, screenshots
+4. **When it started** — recent changes or events that might correlate
+
+## Step 0: Repo-State Detection & Routing Redirect
+
+Before any other check, detect whether this repo is in **prototype mode** or **production mode** per `rules/common/skill-selection.md` Step 1. Signals (any one is sufficient): path under `pocs/` or `*-prototype/`; `package.json` `"private": true` with no CI; missing `aiwiki/architecture/`; manifest shows prototype-phase active.
+
+**If prototype mode is detected**, stop and offer the redirect:
+
+```
+This looks like a prototype bug (signals: <list matched signals>).
+
+/bugfix runs full systematic debugging with regression test creation — appropriate for production code, overkill for prototype iteration. Prototype bugs are usually captured as feedback items and addressed via iterate-prototype.
+
+Redirect to iterate-prototype (capture as feedback item)? [Y]es / [n]o continue with /bugfix anyway / [a]bort
+```
+
+User responses:
+- **Y / yes**: invoke `iterate-prototype` with the bug description as a feedback item. Skip the rest of /bugfix.
+- **n / no**: proceed to Step 0a. User explicitly accepts production-grade debug discipline for prototype work.
+- **a / abort**: stop.
+
+If production mode, proceed to Step 0a directly.
+
+## Step 0a: Preflight Checks
+
+1. **Git is clean** — stash or commit first
+2. **Tests pass** — note which are already failing
+3. **Branch** — `fix/{bug-description-slug}`
+
+## Step 0b: Wiki Bootstrap
+
+REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.
+
+Gotchas surfaced during debug will write to `aiwiki/gotchas/`.
+
+Check if `.forge/work/bugfix/{name}/manifest.yaml` exists.
+
+**If it exists**: Read the manifest. Resume from the last incomplete phase. Report what has already been completed and what remains. If `status: escalated` or `status: completed`, do NOT resume — surface the `successor_path` and ask the user what to do.
+
+**If it does not exist**: Create the work directory (`.forge/work/bugfix/{name}/`) and manifest using the template at `.claude/templates/manifests/bugfix.yaml`. Fill placeholders `{name}`, `{description}`, `{date}`.
+
+If this bugfix was escalated from a hotfix, set `escalated_from: work/hotfix/{predecessor-name}`.
+
+## Step 1: Debug — Systematic Root Cause Analysis
+
+REQUIRED SUB-SKILL: Use **support-debug** with full 4-phase methodology.
+
+The skill handles tracer subagent dispatch internally — escalating to parallel hypothesis testing when linear debugging stalls.
+
+After root cause is identified, produce a debugging summary:
+
+```
+Root cause: {one sentence}
+Evidence: {file:line} → {file:line} → {root cause location}
+Hypotheses tested: {N} — {list with CONFIRMED/REJECTED}
+```
+
+This feeds into Step 5 (gotcha) and the PR description (Step 4).
+
+### GATE: Root Cause Identified
+Root cause must be confirmed with evidence before any fix is attempted. Present the debugging summary to the user for review. Update manifest: `debug.root-cause.status: complete, gate-passed: true`.
+
+## Step 1.5: Regression Plan (Complex Bugs Only)
+
+If the root cause spans multiple files, involves race conditions, or required tracer escalation — produce a focused regression plan before fixing:
+
+1. **Regression test(s)** — exact tests to write (not a full test plan, just the regression cases)
+2. **Related areas to verify** — other code paths that touch the same root cause
+3. **Confidence level** — how certain is this the only root cause?
+
+If the bug is straightforward (single file, clear fix), skip this step.
+
+## Step 2: Build — Test-Driven Fix
+
+REQUIRED SUB-SKILL: Use **build-tdd**.
+Write a regression test that reproduces the bug FIRST, watch it fail, then write the minimal fix.
+
+### GATE: Fix Verified
+Regression test passes. All existing tests still pass. No unrelated changes introduced.
+Update manifest: `build.tdd.status: complete, gate-passed: true`.
+
+## Step 3: Quality — Code Review
+
+REQUIRED SUB-SKILL: Use **quality-code-review**.
+
+### GATE: Code Review Passed
+All critical and important review items resolved. Update manifest: `quality.code-review.status: complete, gate-passed: true`.
+
+## Step 4: Deliver — Create PR
+
+REQUIRED SUB-SKILL: Use **build-pr-workflow**.
+Atomic PR — just the fix and its regression test. Title: `fix: {description}`.
+
+## Step 5: Support — Record Lessons
+
+REQUIRED SUB-SKILL: Use **support-gotcha**.
+
+Use the debugging summary from Step 1 as input. Check `aiwiki/gotchas/` for prior bugs in the same area — if this is the 3rd+ occurrence, the gotcha auto-drafts a `proposed_rule:` block; the next session-start prompts for promotion. Wiki-lint validates the gotcha file structure on save.
+
+Present a final summary:
+
+```
+Bug fixed: {description}
+Root cause: {one sentence}
+Gotcha recorded: aiwiki/gotchas/{filename}.md
+Prevention: {what would prevent this class of bug}
+```
+
+## Gate Exemptions
+
+| Standard Gate | Bugfix Equivalent | Rationale |
+|---|---|---|
+| quality-test-plan | Skipped | Bugfixes target a single root cause — the regression test from build-tdd (Step 2) plus existing tests provide sufficient coverage. A full test plan is overhead for a focused fix. |
+| quality-test-execution | Skipped | build-tdd (Step 2) verifies the regression test passes and all existing tests still pass. A separate test-execution phase adds no value for a minimal, atomic fix. |
+
+## Escalation
+
+If root cause is **architectural** → suggest `/refactor` or `/feature`.
+If root cause is **a dependency bug** → document, create workaround with TODO, file upstream issue.
+If root cause is **environment-specific** → document requirements, update onboarding docs.
+
+### Escalating to /refactor or /feature
+
+When escalation is the right answer, perform the handoff in this order to keep state consistent:
+
+1. Create the successor manifest by invoking the target command (`/refactor` or `/feature`) with `escalated_from: work/bugfix/{this-name}` set on creation.
+2. Update the bugfix manifest: `status: escalated`, `successor_path: work/{type}/{successor-name}`.
+3. Leave the bugfix folder in place — it is the audit trail.
+
+Session-start and pre-compact hooks skip `status: escalated` — the bugfix will not resurface as resumable work after this point.

package/commands/evolve.md

@@ -0,0 +1,118 @@
+---
+name: evolve
+description: "Review lessons learned and improve the skill system. Run after completing a feature or project."
+---
+
+# /evolve — Self-Improvement Review
+
+You are reviewing lessons learned and improving the forge skill system itself. This is how the system gets smarter over time. Run this after completing a feature, project, or periodically to process accumulated gotchas.
+
+## Execution Protocol
+
+- **"REQUIRED SUB-SKILL"** means you MUST load the named skill before acting. Do NOT substitute your own judgment for the skill's process.
+
+## Step 1: Gather All Gotchas
+
+Read all gotcha files from both locations:
+- **Project gotchas**: `aiwiki/gotchas/*.md`
+- **Global gotchas**: `~/.claude/gotchas/*.md`
+
+For each gotcha, extract:
+- The lesson learned
+- The affected skills
+- The date discovered
+- Whether it has been addressed already
+
+## Step 2: Identify Patterns
+
+Analyze the collected gotchas for patterns:
+
+1. **Repeated gotchas** — The same type of mistake happening multiple times
+2. **Skill gaps** — Gotchas that no current skill would have caught
+3. **Gate failures** — Issues that slipped through quality gates
+4. **Gate successes** — Issues that gates DID catch (reinforce these)
+5. **Process friction** — Steps that consistently cause slowdowns or confusion
+
+Present findings as a summary table:
+```
+Pattern                          | Occurrences | Affected Skills      | Severity
+---------------------------------|-------------|----------------------|---------
+Missing error handling in APIs   | 4           | build-tdd, code-review | High
+Tests pass but behavior wrong    | 2           | quality-test-plan     | Medium
+```
+
+## Step 3: Check Quality Gate Effectiveness
+
+For each quality gate in the system:
+1. How many issues did it catch? (good)
+2. How many issues slipped through? (needs improvement)
+3. Is the gate too strict (blocking unnecessarily)?
+4. Is the gate too loose (letting problems through)?
+
+## Step 4: Propose Changes
+
+Based on the patterns, propose specific changes:
+
+### Skill Changes
+- Modifications to existing skill prompts
+- New steps to add to existing skills
+- New skills to create (if a gap was identified)
+
+### Rule Changes
+- New rules to add
+- Modifications to existing rules
+- Rules to relax (if too strict)
+
+### Gate Changes
+- Gates to tighten
+- Gates to add
+- Gates to relax (with justification)
+
+Present each proposed change with:
+- **What**: The specific change
+- **Why**: Which gotcha pattern it addresses
+- **Risk**: What could go wrong if we make this change
+
+## Step 5: Validate Changes
+
+REQUIRED SUB-SKILL: Use **support-skill-validator** before applying ANY changes.
+Do NOT apply changes without validating first — the validator catches contradictions you will miss.
+
+If contradictions are found, resolve them before proceeding.
+
+## Step 6: User Approval
+
+Present all proposed changes to the user. Changes are applied ONLY with explicit approval. The user may:
+- Approve all changes
+- Approve some changes and reject others
+- Request modifications to proposed changes
+- Defer changes for later
+
+## Step 7: Apply Changes
+
+For each approved change:
+1. Make the modification to the relevant skill, rule, or gate file
+2. REQUIRED SUB-SKILL: Re-run **support-skill-validator** to verify consistency after the change
+3. Record the change in the decision log
+
+## Step 8: Promotion Check
+
+Check for gotchas that have repeated 3 or more times. These are candidates for promotion to rules:
+
+```
+PROMOTION CANDIDATES
+--------------------
+Gotcha: "Always check for null responses from external APIs"
+  Occurrences: 4
+  Currently in: support-gotcha (project level)
+  Proposed promotion: references/common/coding-standards.md
+
+  Promote to rule? [yes/no]
+```
+
+For each promotion candidate:
+- Draft the rule text
+- Identify where in the rules it should live
+- Present to the user for approval
+- If approved, add to the appropriate rules file and archive the gotcha
+

package/commands/feature.md

@@ -0,0 +1,236 @@
+---
+name: feature
+description: "Add a feature to an existing codebase using the prototype-driven SDLC. Phase flexibility: trivial features collapse phases (concept slide goes straight to production); standard features run the full pipeline; major features add adversarial review at every decision point."
+argument-hint: "[feature-name] [--size trivial|standard|major]"
+---
+
+# /feature — Prototype-Driven Feature Workflow
+
+You are orchestrating a feature implementation. The default flow is: discover existing codebase → mini-concept → mini-wireframe → prototype-skin → codify → production-build → deliver. Phase flexibility is the rule, not the exception — most features skip 1-2 phases. The preflight planning step (Step 1) decides which phases run.
+
+## Execution Protocol
+
+**REQUIRED SUB-SKILL**: load and follow the skill — do not substitute judgment. Step summaries describe outcomes; the loaded skill defines the process.
+
+## Input
+
+Ask the user for:
+1. **Feature name** (slug format, e.g. `add-payments`, `user-auth`)
+2. **Feature description** (what should it do?)
+3. **Existing requirements** (docs, tickets, screenshots, meeting notes)
+4. **Complexity** (optional): `trivial` / `standard` / `major`. If not provided, the preflight phase planner suggests one.
+
+## Step 0: Repo-State Detection & Routing Redirect
+
+Before any other check, detect whether this repo is in **prototype mode** or **production mode** per `rules/common/skill-selection.md` Step 1. Signals to check (any one is sufficient):
+
+- Working directory or work path is under `pocs/`, or its name ends in `-prototype`
+- `package.json` has `"private": true` AND no test runner / no CI configured
+- `aiwiki/architecture/` is empty or missing (no codified architecture)
+- Existing manifest under `.forge/work/feature/` has `phase_plan.prototype: active` and `phase_plan.codify: skipped`
+
+**If prototype mode is detected**, stop and offer the redirect:
+
+```
+This looks like prototype iteration on an existing prototype (signals: <list matched signals>).
+
+/feature would spin up a 7-phase production workflow (concept → wireframe → prototype → iterate → codify → production-build → deliver). Most phases would end up explicitly skipped, which trains the manifest to lie about gate state.
+
+The right route here is iterate-prototype — lightweight in-place tweaks, no harden/codify ceremony, capture gotchas as feedback items.
+
+Redirect to iterate-prototype? [Y]es / [n]o continue with /feature anyway / [a]bort
+```
+
+User responses:
+- **Y / yes**: invoke `iterate-prototype` skill with the feature description as input. Skip the rest of /feature's steps.
+- **n / no**: proceed to Step 0a below. User must explicitly accept that most phases will be marked `skipped` in the manifest.
+- **a / abort**: stop without action.
+
+If production mode is detected (or the user chose "no continue"), proceed to Step 0a.
+
+## Step 0a: Preflight Checks
+
+1. Git is clean — no uncommitted changes
+2. Tools installed (build tools, test runner, package manager)
+3. Tests pass on current branch — if failing, STOP
+
+## Step 0b: Wiki Bootstrap
+
+REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.
+
+## Step 1: Manifest + Phase Planning
+
+Check if `.forge/work/feature/{name}/manifest.yaml` exists.
+
+**If it exists**: Resume from the last incomplete phase. Skip phases marked `locked` or `skipped`. If `status: escalated` or `status: completed`, do NOT resume — surface `successor_path` and ask the user.
+
+**If it does not exist**: Create the manifest from `.claude/templates/manifests/feature.yaml`.
+
+If escalated from `/bugfix` or `/hotfix`, set `escalated_from: work/{type}/{predecessor-name}`.
+
+**Phase planning** (the v6 flexibility step). Propose `active` / `skip` for each phase based on the feature scope:
+
+| Feature shape | Concept | Wireframe | Prototype | Codify | Production |
+|---|---|---|---|---|---|
+| Trivial UI tweak (color, spacing, copy) | skip (description IS the spec) | skip (existing UI is the wireframe) | skip (production change is small enough) | skip (no architecture delta) | active |
+| New screen, single user role | active (1-3 slides) | active (mini, skin into existing wireframe if any) | active (skin into prototype branch of existing app) | active (architecture delta) | active |
+| New feature touching auth/payments/PII | active | active | active | active (adversarial review on every ADR) | active (security-audit escalation) |
+| Backend-only API endpoint | active (1 slide) | active (admin/playground UI sketch) | active (verification frontend + endpoint) | active | active |
+| Refactor disguised as feature | escalate to `/refactor` |||||
+
+For trivial features, multiple phases collapse — sometimes the entire workflow is "concept slide → write the production code → review → deliver." Trust the preflight planner's judgment, but always present the plan to the user for confirmation before proceeding.
+
+User can override any phase decision (e.g. "actually let's do a wireframe — I want to see the layout").
+
+## Step 2: Discover — Codebase Analysis
+
+REQUIRED SUB-SKILL: Use **discover-codebase-analysis**.
+
+For features on existing codebases, this is non-optional — production code grows from the prototype, and the prototype skins into the existing app. Without codebase analysis, the prototype-builder will reinvent patterns that already exist.
+
+### GATE: Codebase Analysis Approved
+
+User reviews. Update manifest: `discover.codebase-analysis.{status: complete, gate-passed: true}`.
+
+## Step 3: Concept (Phase 2) — if active
+
+REQUIRED SUB-SKILL: Use **concept-slides**.
+
+For features, often a 1-3 slide mini-deck — what the feature is, where it sits in the existing app, the visual sketch.
+
+### GATE: Concept Locked
+
+Update manifest: `artifacts.concept.{deck_path, locked_at}`. Presence of `locked_at` is the lock signal that downstream phases check.
+
+## Step 4: Wireframe (Phase 3) — if active
+
+REQUIRED SUB-SKILL: Use **build-wireframe**.
+
+For features on existing apps:
+- If the existing app has a wireframe at `pocs/wireframe/index.html`, fork it and add the new screens / states
+- If not, produce a mini-wireframe at `pocs/{name}-wireframe/index.html` covering only the feature's screens
+
+### GATE: Wireframe Locked
+
+Update manifest: `artifacts.wireframe.{html_path, locked_at}`.
+
+## Step 4.5: Design System — if frontend feature
+
+REQUIRED SUB-SKILL: Use **plan-design-system** to lock design tokens before architecture.
+
+Backend-only features (API endpoints, schema changes, internal refactors) skip this step entirely — no UI surfaces, no design tokens needed. For features that add or change UI surfaces, run plan-design-system to extend the project's existing `DESIGN.md` (or create one if the project never had a frontend before). The skill self-skips when `DESIGN.md` already exists and is current for this work item.
+
+### GATE: Design Tokens Approved
+
+Update manifest: `artifacts.design-system.{path, approved_at}`.
+
+## Step 5: Prototype (Phase 4) — if active
+
+REQUIRED SUB-SKILL: Use **build-prototype**, then **iterate-prototype** for polish.
+
+For features on existing apps:
+- Scaffold `pocs/{name}-prototype/` as a mini-prototype, OR
+- Skin the new screens into a prototype branch of the existing app (manifest field `prototype_path` records which approach)
+
+Capture gotchas + conventions during iteration to `aiwiki/`.
+
+### GATE: Prototype Locked
+
+User emits "satisfied" or "LOCKED". Update manifest: `artifacts.prototype.{path, locked_at}`.
+
+## Step 6: Codify (Phase 5) — if active
+
+REQUIRED SUB-SKILL: Use **harden**.
+
+For features, often produces an architecture-delta (extending existing `aiwiki/architecture/{topic}.md` rather than creating new), 0-3 ADRs, and a focused slice graph (the production tasks specific to this feature).
+
+For features touching `--size major` complexity (auth, payments, PII, schema changes): adversarial review is mandatory on every ADR. The dedicated `/second-opinion` skill is *planned, not yet implemented* — until it ships, surface adversarial objections inline in the ADR `review:` block during harden Step 2 and have the user sign off explicitly before the ADR is marked `accepted`.
+
+### GATE: Codified Plan Approved
+
+User reviews architecture-delta + ADRs + slice graph. Approves before Phase 6 starts. Update manifest: `artifacts.codify.locked_at` (no path — the populated slice_graph + the aiwiki/architecture/ files ARE the codify artifacts).
+
+## Step 7: Build — Create Worktree
+
+REQUIRED SUB-SKILL: Use **build-pr-workflow** to create a git worktree for the feature branch.
+
+Update manifest: `build.worktree-created: true`.
+
+## Step 8: Production Build (Phase 6)
+
+Execute the slice graph from Phase 5. Per slice:
+
+1. REQUIRED SUB-SKILL: Use **build-tdd** — strict RED-GREEN-REFACTOR
+2. REQUIRED SUB-SKILL: Use **quality-code-review**
+3. Fix any Critical or Important findings
+4. Per-slice user-confirm
+5. Per-slice dream consolidates slice-scoped wiki updates
+
+For `--size major` features: also escalate to `quality-security-audit` on slices that touch auth/payments/PII.
+
+Optional: `/autopilot production` for Ralph-loop hands-off slice execution *(planned, not yet implemented — see docs/V6-PLAN.md §11; per-slice manual dispatch is the only mode today)*.
+
+### GATE: All Slices Complete
+
+All slices `gate-passed: true`. Update manifest: `artifacts.production-build.locked_at` (the slice terminal state + the production code ARE the production-build artifacts).
+
+## Step 9: Test Plan + Execution
+
+REQUIRED SUB-SKILL: Use **quality-test-plan** (per complexity), then **quality-test-execution**.
+
+- `trivial`: focused regression plan (unit tests for changed code, no E2E/load)
+- `standard`: full test plan
+- `major`: full test plan including load/stress scenarios
+
+### GATE: Test Results
+
+ALL tests pass. Coverage meets thresholds.
+
+## Step 9.5: UI/UX Review — if frontend feature
+
+If the wireframe phase ran (frontend feature):
+
+REQUIRED SUB-SKILL: Use **quality-uiux**.
+Verifies production matches the locked wireframe + design tokens.
+
+## Step 10: Final Code Review
+
+REQUIRED SUB-SKILL: Use **quality-code-review** for a final pass across all changes (full diff from feature branch base to HEAD). Fix any Critical or Important findings before creating PRs.
+
+## Step 11: Deliver — Create PRs
+
+REQUIRED SUB-SKILL: Use **build-pr-workflow** to create one PR per logical function/component.
+
+Update manifest: `deliver.pr-created: true`.
+
+## Step 12: Deliver — Deploy (optional)
+
+Ask the user: "Would you like to deploy now?"
+If yes: REQUIRED SUB-SKILL: Use **deliver-deploy**.
+
+## Step 12.5: Deliver — Update Onboarding Docs
+
+- `trivial`: skip
+- `standard`: skip if purely internal with no new concepts/setup/env-vars/services
+- `major`: REQUIRED — significant features always warrant doc updates
+
+REQUIRED SUB-SKILL: Use **deliver-onboarding**.
+
+## Step 13: Support — Record Lessons
+
+REQUIRED SUB-SKILL: Use **support-gotcha**.
+Final dream cycle consolidates all Phase 4-12 wiki captures.
+
+Update manifest: `status: completed`.
+
+## Phase Skip Handling
+
+When phase planning marks a phase `skipped`, the downstream phase reads from whatever the skipped phase would have produced — e.g. if wireframe is skipped because the user has Figma mockups, the prototype builder uses the Figma export instead of a wireframe HTML.
+
+Record skip reasons in the manifest. Skipped phases do not run gates.
+
+If a skipped phase reveals a gap during a later phase, that affected phase opens with `locked-with-deltas` and a delta entry pointing back. The downstream phase's gate verifies the delta is closed.
+
+## Gate Checking Logic
+
+Resume rule: skip phases where `artifacts.{phase}.locked_at` is present (already locked) or `phase_plan.{phase}` is `skipped`. Halt and fix any phase whose gate hasn't passed before continuing.