@zigrivers/scaffold 3.0.2 → 3.4.0

package/README.md

@@ -1,35 +1,35 @@
 # Scaffold
 
-A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 10 utility tools, and Claude Code handles the research, planning, and implementation for you.
+A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 10 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
 
 By the end, you'll have a fully planned, standards-documented, implementation-ready project with working code.
 
 ## What is Scaffold?
 
-Scaffold is a composable meta-prompt pipeline built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Anthropic's command-line coding tool. If you have an idea for a software project but don't know where to start — or you want to make sure your project is set up with solid architecture, standards, and tests from day one — Scaffold guides you through every step.
+Scaffold is a composable meta-prompt pipeline built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Gemini, and other supported AI coding tools. If you have an idea for a software project but don't know where to start — or you want to make sure your project is set up with solid architecture, standards, and tests from day one — Scaffold guides you through every step.
 
 Here's how it works:
 
 1. **Initialize** — run `scaffold init` in your project directory. The init wizard detects whether you're starting fresh (greenfield) or working with an existing codebase (brownfield), and lets you pick a methodology preset (deep, mvp, or custom).
 
-2. **Run steps** — each step is a composable meta-prompt (a short intent declaration in `pipeline/`) that gets assembled at runtime into a full 7-section prompt. The assembly engine injects relevant knowledge base entries, project context from prior steps, methodology settings, and depth-appropriate instructions.
+2. **Run steps** — each step is a composable meta-prompt (a short intent declaration in `content/pipeline/`) that gets assembled at runtime into a full 7-section prompt. The assembly engine injects relevant knowledge base entries, project context from prior steps, methodology settings, and depth-appropriate instructions.
 
 3. **Follow the dependency graph** — Scaffold tracks which steps are complete, which are eligible, and which are blocked. Run `scaffold next` to see what's unblocked, or `scaffold status` for the full picture. Each step produces a specific artifact — a planning document, architecture decision, specification, or actual code.
 
 You can run steps two ways:
 
 - **CLI**: `scaffold run create-prd` — the assembly engine builds a full prompt from the meta-prompt, knowledge base entries, and project context. Best for the structured pipeline with dependency tracking.
-- **Slash commands**: `/scaffold:create-prd` in Claude Code — uses pre-rendered, self-contained prompts. Best for quick access to individual commands without the full pipeline ceremony.
+- **Runner skill**: In Claude Code or Gemini, the scaffold-runner skill provides an interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting the AI pick defaults silently.
 
-Either way, Scaffold constructs the prompt and Claude does the work. The CLI tracks pipeline state and dependencies; slash commands are fire-and-forget.
+Either way, Scaffold constructs the prompt and the target AI tool does the work. The CLI tracks pipeline state and dependencies; the runner skill adds interactive decision surfacing on top.
 
 ## Key Concepts
 
-**Meta-prompts** — Each pipeline step is defined as a short `.md` file in `pipeline/` with YAML frontmatter (dependencies, outputs, knowledge entries) and a markdown body describing the step's intent. These are *not* the prompts Claude sees — they're assembled into full prompts at runtime.
+**Meta-prompts** — Each pipeline step is defined as a short `.md` file in `content/pipeline/` with YAML frontmatter (dependencies, outputs, knowledge entries) and a markdown body describing the step's intent. These are *not* the prompts Claude sees — they're assembled into full prompts at runtime.
 
 **Assembly engine** — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
 
-**Knowledge base** — 60 domain expertise entries in `knowledge/` organized in seven categories (core, product, review, validation, finalization, execution, tools) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
+**Knowledge base** — 60 domain expertise entries in `content/knowledge/` organized in seven categories (core, product, review, validation, finalization, execution, tools) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
@@ -85,7 +85,7 @@ Lets Claude control a real browser for visual testing and screenshots.
 Scaffold has two parts that install separately:
 
 - **CLI** (`scaffold`) — the core tool. Install via npm or Homebrew. Use it from your terminal or from Claude Code with `! scaffold run <step>`.
-- **Plugin** (`/scaffold:`) — optional slash commands for Claude Code. Lets you type `/scaffold:create-prd` instead of `! scaffold run create-prd`.
+- **Plugin** — optional Claude Code plugin that auto-activates the scaffold runner and pipeline reference skills for interactive guidance.
 
 ### Step 1: Install the CLI
 
@@ -108,7 +108,7 @@ Verify: `scaffold version`
 
 ### Step 2: Add the plugin (recommended)
 
-Install the Scaffold plugin inside Claude Code for slash commands AND the interactive runner skill:
+Install the Scaffold plugin inside Claude Code for auto-activated skills:
 
 ```
 /plugin marketplace add zigrivers/scaffold
@@ -116,9 +116,8 @@ Install the Scaffold plugin inside Claude Code for slash commands AND the intera
 ```
 
 This gives you:
-- **Slash commands** (`/scaffold:create-prd`, `/scaffold:tdd`, etc.) — quick access to any pipeline step
 - **Scaffold Runner skill** — intelligent interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting Claude pick defaults silently
-- **Pipeline reference skill** — shows pipeline ordering, dependencies, and completion status
+- **Pipeline reference skill** — shows pipeline ordering, dependencies, and phase structure
 - **Multi-model dispatch skill** — correct invocation patterns for Codex and Gemini CLIs
 
 **Usage** — just tell Claude Code what you want in natural language:
@@ -134,11 +133,9 @@ This gives you:
 
 The plugin is optional — everything it does can also be done with `scaffold run <step>` from the CLI. But you lose the interactive decision surfacing without the Scaffold Runner skill.
 
-> **CLI-only users**: If you prefer not to install the plugin, add skills with one command:
-> ```bash
-> scaffold skill install
-> ```
-> This copies the Scaffold Runner, Pipeline Reference, and Multi-Model Dispatch skills to `.claude/skills/` in your project.
+> **CLI-only users**: If you prefer not to install the plugin, skills are installed automatically — `scaffold init` sets them up, and any subsequent CLI command keeps them current after upgrades. No manual `scaffold skill install` needed.
+
+> **Gemini users**: `scaffold build` keeps a root `GEMINI.md` in sync with the shared runner instructions and generates `.gemini/commands/scaffold/*.toml` wrappers. Plain prompts like `scaffold status` work because Gemini loads `GEMINI.md`.
 
 ## Updating
 
@@ -157,11 +154,9 @@ brew upgrade scaffold
 ### Plugin
 
 ```
-/scaffold:update
+/plugin marketplace update zigrivers-scaffold
 ```
 
-Or: `/plugin marketplace update zigrivers-scaffold`
-
 ### Existing projects
 
 After upgrading the CLI, existing projects still get automatic state migrations. Run `scaffold status` in your project directory — the state manager detects and renames old step keys, removes retired steps, normalizes artifact paths, and persists the changes atomically. No manual editing of `.scaffold/state.json` is needed.
@@ -187,7 +182,7 @@ The canonical execution entrypoints are still `scaffold run <step>` and the inst
 This release is a clean breaking change for generated adapter output. To migrate an existing project:
 
 1. Upgrade Scaffold.
-2. Remove old root-level generated Scaffold output if present: `commands/`, `prompts/`, `codex-prompts/`, and root `AGENTS.md` only if it was Scaffold-generated.
+2. Remove old root-level generated Scaffold output if present: `prompts/`, `codex-prompts/`, `commands/`, and root `AGENTS.md` only if it was Scaffold-generated. Run `scaffold status` — it warns about any legacy output.
 3. Run `scaffold build`.
 4. Review the Scaffold-managed block in `.gitignore`.
 5. Commit `.gitignore` plus the intended committed `.scaffold/` state files (`config.yml`, `state.json`, `decisions.jsonl`, `instructions/`).
@@ -549,11 +544,24 @@ npm install -g @google/gemini-cli
 
 You don't need both — Scaffold works with whichever CLIs are available. Having both gives the strongest review (three independent perspectives). See [Prerequisites](#prerequisites) for auth setup and verification commands.
 
+### mmr — Multi-Model Review CLI
+
+Scaffold includes `mmr`, a standalone CLI that automates multi-model code review dispatch, monitoring, and reconciliation. Instead of manually running each review channel, `mmr` handles it all:
+
+```bash
+mmr review --pr 47 --focus "auth flow"   # Dispatch to all channels (async)
+mmr status mmr-a1b2c3                     # Poll progress
+mmr results mmr-a1b2c3                    # Reconciled findings + gate
+mmr config test                           # Pre-flight auth check
+```
+
+`mmr` is installed alongside Scaffold, or independently via `npm install -g @zigrivers/mmr`. Run `mmr config init` to auto-detect installed CLIs and generate a `.mmr.yaml` config. See the [mmr design spec](docs/superpowers/specs/2026-04-05-mmr-multi-model-review-design.md) for full details.
+
 ### How It Works
 
 1. **Claude reviews first** — completes its own structured multi-pass review using different review lenses (coverage, consistency, quality, downstream readiness)
 2. **Independent external review** — the document being reviewed is sent to each available CLI. They don't see Claude's findings or each other's output — every review is independent.
-3. **Findings are reconciled** — Scaffold merges all findings by confidence level:
+3. **Findings are reconciled** — Scaffold (or `mmr`) merges all findings by confidence level:
 
 | Scenario | Confidence | Action |
 |----------|-----------|--------|
@@ -614,7 +622,7 @@ You can change methodology mid-pipeline with `scaffold init --methodology <prese
 | `scaffold dashboard` | Open a visual progress dashboard in your browser |
 | `scaffold decisions` | Show all logged decisions |
 | `scaffold knowledge` | Manage project-local knowledge base overrides |
-| `scaffold skill install` | Install scaffold skills into the current project |
+| `scaffold skill install` | Install scaffold skills into the current project (automatic — rarely needed manually) |
 | `scaffold skill list` | Show available skills and installation status |
 | `scaffold skill remove` | Remove scaffold skills from the current project |
 
@@ -703,7 +711,7 @@ These are stateless pipeline steps — they appear in `scaffold next` once Phase
 
 ### Utility Tools
 
-These are orthogonal to the pipeline — usable at any time, not tied to pipeline state. Defined in `tools/` with `category: tool` frontmatter. Run `scaffold list --section tools` for a complete listing (or `--verbose` for argument hints, `--format json` for machine-readable output):
+These are orthogonal to the pipeline — usable at any time, not tied to pipeline state. Defined in `content/tools/` with `category: tool` frontmatter. Run `scaffold list --section tools` for a complete listing (or `--verbose` for argument hints, `--format json` for machine-readable output):
 
 | Command | When to Use |
 |---------|-------------|
@@ -720,14 +728,14 @@ These are orthogonal to the pipeline — usable at any time, not tied to pipelin
 
 Use `scaffold run review-code` before commit or push when you want a local gate on the current delivery candidate. Use `scaffold run review-pr` after a GitHub PR exists.
 
-All of these are also available as slash commands (`/scaffold:release`, `/scaffold:quick-task`, etc.) when the plugin is installed.
+Run any of these via the CLI or ask the scaffold runner skill in Claude Code or Gemini.
 
 ## Releasing Your Project
 
 ### Version bumps (development milestones)
 
 ```
-/scaffold:version-bump
+scaffold run version-bump
 ```
 
 Bumps the version number and updates the changelog, but doesn't create tags, push, or run the formal release ceremony. Think of it as a checkpoint.
@@ -735,10 +743,10 @@ Bumps the version number and updates the changelog, but doesn't create tags, pus
 ### Creating a release
 
 ```
-/scaffold:release
+scaffold run release
 ```
 
-Claude analyzes your commits since the last release, suggests whether this is a major, minor, or patch version bump, and walks you through:
+The AI analyzes your commits since the last release, suggests whether this is a major, minor, or patch version bump, and walks you through:
 1. Running your project's tests
 2. Updating the version number in your project files
 3. Generating a changelog entry
@@ -746,7 +754,7 @@ Claude analyzes your commits since the last release, suggests whether this is a
 
 Depending on the target project, that may include a Git tag, hosted release,
 package publish, deployment, registry update, or another project-specific
-release step. `/scaffold:release` is intentionally generic; it should follow
+release step. `scaffold run release` is intentionally generic; it follows
 the target project's own documented workflow rather than assuming npm or GitHub
 for every project.
 
@@ -762,17 +770,17 @@ Options: `--dry-run` to preview, `minor`/`major`/`patch` to specify the bump, `c
 | **Frontmatter** | The YAML metadata block at the top of meta-prompt files, declaring dependencies, outputs, knowledge entries, and other configuration. |
 | **Knowledge base** | 60 domain expertise entries that get injected into prompts. Can be extended with project-local overrides. |
 | **MCP** | Model Context Protocol. A way for Claude to use external tools like a headless browser. |
-| **Meta-prompt** | A short intent declaration in `pipeline/` that gets assembled into a full prompt at runtime. |
+| **Meta-prompt** | A short intent declaration in `content/pipeline/` that gets assembled into a full prompt at runtime. |
 | **Methodology** | A preset (deep, mvp, custom) controlling which steps run and at what depth. |
 | **Multi-model review** | Independent validation from Codex/Gemini CLIs at depth 4-5, catching blind spots a single model misses. |
 | **PRD** | Product Requirements Document. The foundation for everything Scaffold builds. |
-| **Slash commands** | Commands in Claude Code starting with `/`. For example, `/scaffold:create-prd`. |
+| **Runner skill** | Auto-activated Claude Code/Gemini skill that surfaces decision points before executing pipeline steps. |
 | **Worktrees** | A git feature for multiple working copies. Scaffold uses these for parallel agent execution. |
 
 ## Troubleshooting / FAQ
 
 **I ran a command and nothing happened.**
-Make sure Scaffold is installed — run `scaffold version` or `/scaffold:prompt-pipeline` in Claude Code.
+Make sure Scaffold is installed — run `scaffold version` in your terminal.
 
 **Which steps can I skip?**
 Use `scaffold skip <step> --reason "..."` to skip any step. You can skip multiple steps at once: `scaffold skip design-system add-e2e-testing --reason "backend-only"`. The mvp preset only enables 7 critical steps by default. With the custom preset, you choose exactly which steps to run.
@@ -833,12 +841,12 @@ src/
 ├── cli/middleware/    # Project root detection, output mode resolution
 ├── cli/output/       # Output strategies (interactive, json, auto)
 ├── core/assembly/    # Assembly engine — meta-prompt → full prompt
-├── core/adapters/    # Platform adapters (Claude Code, Codex, Universal)
+├── core/adapters/    # Platform adapters (Claude Code, Gemini, Codex, Universal)
 ├── core/dependency/  # DAG builder, topological sort, eligibility
 ├── core/knowledge/   # Knowledge update assembler
 ├── state/            # State manager, lock manager, decision logger
 ├── config/           # Config loading, migration, schema validation
-├── project/          # Project detector, CLAUDE.md manager, adoption
+├── project/          # Project detector, CLAUDE.md/GEMINI.md managers, adoption
 ├── wizard/           # Init wizard (interactive + --auto)
 ├── validation/       # Config, state, frontmatter validators
 ├── types/            # TypeScript types and enums
@@ -851,19 +859,27 @@ src/
 - **Assembly engine** (`src/core/assembly/engine.ts`) — Pure orchestrator with no I/O. Constructs 7-section prompts from meta-prompt + knowledge + context + methodology + instructions + depth guidance.
 - **State manager** (`src/state/state-manager.ts`) — Atomic writes via tmp + `fs.renameSync()`. Tracks step status, in-progress records, and next-eligible cache. Includes migration system for step renames and retired steps.
 - **Dependency graph** (`src/core/dependency/`) — Kahn's algorithm topological sort with phase-aware ordering and cycle detection.
-- **Platform adapters** (`src/core/adapters/`) — 3-step lifecycle (initialize → generateStepWrapper → finalize) producing hidden adapter artifacts under `.scaffold/generated/claude-code/`, `.scaffold/generated/codex/`, and `.scaffold/generated/universal/`.
+- **Platform adapters** (`src/core/adapters/`) — 3-step lifecycle (initialize → generateStepWrapper → finalize) producing `.scaffold/generated/claude-code/commands/`, `.scaffold/generated/codex/AGENTS.md`, `.scaffold/generated/universal/prompts/README.md`, and Gemini project-local files under `.agents/skills/`, `GEMINI.md`, and `.gemini/commands/scaffold/`.
 - **Project detector** (`src/project/detector.ts`) — Scans for file system signals to classify projects as greenfield, brownfield, or v1-migration.
 - **Check command** (`src/cli/commands/check.ts`) — Applicability detection for conditional steps (platform detection, GitHub remote detection, CLI availability).
 
 ### Content layout
 
+All build inputs live under `content/`:
+
+```
+content/
+├── pipeline/         # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
+├── tools/            # 10 tool meta-prompts (stateless, category: tool)
+├── knowledge/        # 61 domain expertise entries (core, product, review, validation, finalization, execution, tools)
+├── methodology/      # 3 YAML presets (deep, mvp, custom)
+└── skills/           # 3 skill templates with {{markers}} for multi-platform resolution
+```
+
+Generated output (gitignored):
 ```
-pipeline/             # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
-tools/                # 9 tool meta-prompts (stateless, category: tool)
-knowledge/            # 61 domain expertise entries (core, product, review, validation, finalization, execution, tools)
-methodology/          # 3 YAML presets (deep, mvp, custom)
-commands/             # 72 Claude Code slash commands (60 pipeline + 9 tools + 3 supplemental)
-skills/               # 3 Claude Code skills (pipeline reference, runner, multi-model dispatch)
+skills/               # Resolved skills (built from content/skills/ templates)
+dist/                 # Compiled TypeScript output
 ```
 
 ### Testing
@@ -877,12 +893,12 @@ skills/               # 3 Claude Code skills (pipeline reference, runner, multi-
 
 ### Contributing
 
-1. Meta-prompt content lives in `pipeline/` — edit the relevant `.md` file
-2. If you changed adapter behavior, run `scaffold build` in a test project and inspect the generated artifacts under `.scaffold/generated/`.
+1. Meta-prompt content lives in `content/pipeline/` — edit the relevant `.md` file
+2. If you changed adapter behavior, run `scaffold build` in a test project and inspect the generated artifacts under `.scaffold/generated/` plus the Gemini project-local outputs (`.agents/skills/`, `GEMINI.md`, `.gemini/commands/scaffold/`).
 3. Run `make check-all` (lint + type-check + test + evals) before submitting
-4. Knowledge entries live in `knowledge/` — follow the existing frontmatter schema
-5. ADRs documenting architectural decisions are in `docs/v2/adrs/`
-6. Run `make hooks` to install git hooks (ShellCheck, frontmatter validation, stale command detection)
+4. Knowledge entries live in `content/knowledge/` — follow the existing frontmatter schema
+5. ADRs documenting architectural decisions are in `docs/architecture/adrs/`
+6. Run `make hooks` to install git hooks (ShellCheck, frontmatter validation)
 
 ## License
 

package/content/knowledge/core/test-skeleton-generation.md

@@ -0,0 +1,313 @@
+---
+name: test-skeleton-generation
+description: Patterns for translating acceptance criteria into framework-specific test skeleton files
+topics: [testing, test-generation, acceptance-criteria, tdd, test-skeletons]
+---
+
+# Test Skeleton Generation
+
+This knowledge covers the translation of user story acceptance criteria (Given/When/Then format) into framework-specific test skeleton files. Skeletons are pending/skipped test stubs — they document expected behavior and provide a TDD starting point, but contain no implementation logic.
+
+This is distinct from testing strategy (`testing-strategy`), which covers overall test architecture, and user stories (`user-stories`), which covers story authoring. This knowledge bridges the two: given well-written ACs and a chosen test framework, produce a complete set of traceable test skeletons.
+
+## Summary
+
+- **Purpose**: Translate user story acceptance criteria (Given/When/Then) into pending test cases in the project's test framework, one test per AC.
+- **Output format**: One test file per story (or per epic), with each AC as a pending/skipped test case that documents the expected behavior without implementing it.
+- **Framework mapping**: `describe` = story, `it`/`test` = AC criterion. For frameworks without pending support, use `it.skip` or `@pytest.mark.skip` with the AC text as the test name.
+- **Layer assignment**: Each test skeleton is tagged with its execution layer (unit, integration, e2e) based on what the AC tests — data validation = unit, API flow = integration, user workflow = e2e.
+- **ID tracing**: Every test name includes the story ID and criterion ID (e.g., `US-3.2: Given a logged-in user...`) so implementation agents can trace tests back to requirements.
+- **Story-tests-map**: A traceability matrix (`docs/story-tests-map.md`) maps every story to its test files, every AC to its test case, and assigns execution layers.
+
+## Deep Guidance
+
+### Scope Boundary
+
+**In scope:**
+- Translating GWT acceptance criteria into pending test stubs
+- Assigning test execution layers (unit, integration, e2e)
+- Creating the story-tests-map traceability matrix
+- Framework-specific skeleton patterns (vitest, pytest, bats, Go, etc.)
+- Test file naming and directory conventions
+
+**Out of scope:**
+- Implementing test logic (skeletons are stubs only)
+- Choosing the test framework (read `docs/tech-stack.md`)
+- Writing acceptance criteria (that's the user stories step)
+- Test infrastructure setup (that's the TDD standards step)
+
+---
+
+### Translation Rules
+
+**Given/When/Then to Test Structure:**
+
+The GWT format maps directly to the Arrange/Act/Assert pattern used in every test framework:
+
+```
+Given [precondition]     ->  test setup / arrange
+When [action]            ->  act / trigger
+Then [expected outcome]  ->  assert / verify
+And [additional outcome] ->  additional assertion
+```
+
+Multiple `Given` clauses become multiple setup steps. Multiple `Then` clauses become multiple assertions in the same test. `And` following a `Given` is another precondition; `And` following a `Then` is another assertion.
+
+**Compound ACs:**
+
+When an AC has multiple `When` clauses, each `When` is a separate test case. The common `Given` preconditions are shared setup (a `beforeEach` or fixture), and each `When/Then` pair becomes its own test.
+
+---
+
+### Framework-Specific Patterns
+
+#### vitest / jest (TypeScript/JavaScript)
+
+```typescript
+import { describe, it } from 'vitest';
+
+describe('US-3: User can reset their password', () => {
+  it.skip('AC-3.1: Given a registered user, when they request a password reset, then a reset email is sent', () => {
+    // Arrange: registered user exists
+    // Act: request password reset
+    // Assert: reset email sent
+  });
+
+  it.skip('AC-3.2: Given a valid reset token, when the user submits a new password, then the password is updated', () => {
+    // Arrange: valid reset token exists
+    // Act: submit new password
+    // Assert: password updated in database
+  });
+
+  it.skip('AC-3.3: Given an expired reset token, when the user submits a new password, then an error is shown', () => {
+    // Arrange: expired reset token
+    // Act: submit new password
+    // Assert: error message displayed, password unchanged
+  });
+});
+```
+
+#### pytest (Python)
+
+```python
+import pytest
+
+class TestUS3UserCanResetPassword:
+    """US-3: User can reset their password"""
+
+    @pytest.mark.skip(reason="skeleton")
+    def test_ac_3_1_given_registered_user_when_request_reset_then_email_sent(self):
+        """AC-3.1: Given a registered user, when they request a password reset, then a reset email is sent"""
+        # Arrange: registered user exists
+        # Act: request password reset
+        # Assert: reset email sent
+        pass
+
+    @pytest.mark.skip(reason="skeleton")
+    def test_ac_3_2_given_valid_token_when_submit_password_then_updated(self):
+        """AC-3.2: Given a valid reset token, when the user submits a new password, then the password is updated"""
+        # Arrange: valid reset token exists
+        # Act: submit new password
+        # Assert: password updated in database
+        pass
+```
+
+#### bats (Bash)
+
+```bash
+# US-3: User can reset their password
+
+@test "AC-3.1: Given a registered user, when they request a password reset, then a reset email is sent" {
+  skip "skeleton"
+  # Arrange: registered user exists
+  # Act: request password reset
+  # Assert: reset email sent
+}
+
+@test "AC-3.2: Given a valid reset token, when the user submits a new password, then the password is updated" {
+  skip "skeleton"
+  # Arrange: valid reset token exists
+  # Act: submit new password
+  # Assert: password updated in database
+}
+```
+
+#### Go testing
+
+```go
+func TestUS3_UserCanResetPassword(t *testing.T) {
+    t.Run("AC-3.1: Given a registered user, when they request a password reset, then a reset email is sent", func(t *testing.T) {
+        t.Skip("skeleton")
+        // Arrange: registered user exists
+        // Act: request password reset
+        // Assert: reset email sent
+    })
+
+    t.Run("AC-3.2: Given a valid reset token, when the user submits a new password, then the password is updated", func(t *testing.T) {
+        t.Skip("skeleton")
+        // Arrange: valid reset token exists
+        // Act: submit new password
+        // Assert: password updated in database
+    })
+}
+```
+
+### Framework-Specific Summary Table
+
+| Framework | Story Group | Test Case | Pending Marker |
+|-----------|------------|-----------|----------------|
+| vitest/jest | `describe('US-3: Story title')` | `it('AC-3.1: Given X when Y then Z')` | `it.skip(...)` or `it.todo(...)` |
+| pytest | `class TestUS3StoryTitle:` | `def test_ac_3_1_given_x_when_y_then_z(self):` | `@pytest.mark.skip(reason='skeleton')` |
+| bats | comment block with story ID | `@test "AC-3.1: Given X when Y then Z"` | `skip "skeleton"` |
+| Go testing | `func TestUS3_StoryTitle(t *testing.T)` | `t.Run("AC-3.1: Given X when Y then Z", ...)` | `t.Skip("skeleton")` |
+| RSpec | `describe 'US-3: Story title'` | `it 'AC-3.1: ...'` | `xit 'AC-3.1: ...'` or `pending` |
+| JUnit 5 | `@Nested class US3_StoryTitle` | `@Test @Disabled("skeleton")` | `@Disabled("skeleton")` |
+
+---
+
+### Layer Assignment Heuristic
+
+Each test skeleton is tagged with its execution layer. This determines where the test runs in CI and what infrastructure it requires.
+
+| AC Pattern | Layer | Example |
+|------------|-------|---------|
+| Validates input/output of a single function | Unit | "Then the email format is validated" |
+| Tests interaction between components | Integration | "Then the order is saved to the database" |
+| Tests a user-visible workflow end-to-end | E2E | "Then the user sees a confirmation page" |
+| Tests error handling at a boundary | Integration | "Then a 400 error is returned with details" |
+| Tests a non-functional requirement | Varies | Perf = benchmark, security = integration |
+
+#### Layer Decision Rules
+
+When the layer is ambiguous, apply these rules in order:
+
+1. **Does the AC mention a UI element or user-visible state?** → E2E
+2. **Does the AC cross a service or component boundary?** → Integration
+3. **Does the AC test a single function's behavior with known inputs/outputs?** → Unit
+4. **Does the AC test data persistence or retrieval?** → Integration
+5. **Does the AC test an external service interaction?** → Integration (with mocks)
+
+#### Layer Tags in Test Files
+
+Add layer tags as comments or test metadata so CI can filter by layer:
+
+```typescript
+// @layer: integration
+describe('US-3: User can reset their password', () => { ... });
+```
+
+```python
+@pytest.mark.integration
+class TestUS3UserCanResetPassword:
+    ...
+```
+
+---
+
+### Test File Naming and Organization
+
+#### File Naming Convention
+
+Test files follow the pattern: `{story-id}-{slug}.test.{ext}`
+
+Examples:
+- `us-1-user-registration.test.ts`
+- `us-2-password-reset.test.ts`
+- `us-3-profile-management.test.ts`
+
+The story ID prefix ensures files sort in story order. The slug provides human-readable context.
+
+#### Directory Structure
+
+Test skeletons go in the acceptance test directory defined in `docs/project-structure.md`. If no convention exists, default to:
+
+```
+tests/
+  acceptance/
+    us-1-user-registration.test.ts
+    us-2-password-reset.test.ts
+    us-3-profile-management.test.ts
+```
+
+For projects that split tests by layer:
+
+```
+tests/
+  unit/
+    us-1-user-registration.unit.test.ts
+  integration/
+    us-1-user-registration.integration.test.ts
+  e2e/
+    us-1-user-registration.e2e.test.ts
+```
+
+---
+
+### Story-Tests-Map Format
+
+The `docs/story-tests-map.md` output maps every story to its test files. This is the primary traceability artifact.
+
+```markdown
+# Story-Tests Map
+
+## Coverage Summary
+
+| Metric | Value |
+|--------|-------|
+| Total stories | 12 |
+| Stories with tests | 12 |
+| Total ACs | 47 |
+| ACs with test cases | 47 |
+| Coverage | 100% |
+
+## Traceability Matrix
+
+| Story ID | Story Title | Test File | Layer | AC Count |
+|----------|------------|-----------|-------|----------|
+| US-1 | User registration | tests/acceptance/us-1-registration.test.ts | integration | 4 |
+| US-2 | Password reset | tests/acceptance/us-2-password-reset.test.ts | e2e | 3 |
+| US-3 | Profile management | tests/acceptance/us-3-profile.test.ts | unit | 5 |
+```
+
+The map must be updated whenever stories are added, removed, or have ACs changed. In update mode, new rows are appended and the coverage summary is recalculated.
+
+---
+
+### Handling Edge Cases
+
+#### Stories Without GWT Format
+
+If acceptance criteria are not in Given/When/Then format, convert them:
+- "Users can search by keyword" → "Given a user on the search page, when they enter a keyword and submit, then matching results are displayed"
+- Preserve the original AC text as a comment in the test case
+
+#### Stories With Many ACs
+
+Stories with more than 10 ACs may indicate the story is too large. Flag this in the story-tests-map but generate all skeletons regardless — the story decomposition is a separate concern.
+
+#### Shared Preconditions
+
+When multiple ACs share the same `Given` precondition, use the framework's shared setup:
+- vitest/jest: `beforeEach` or `beforeAll`
+- pytest: `@pytest.fixture`
+- bats: `setup()`
+- Go: helper function called at the start of each subtest
+
+#### Negative Test Cases
+
+For deep methodology, generate negative test cases for each happy-path AC:
+- "Given X, when Y, then Z" → also generate "Given NOT X, when Y, then error"
+- Negative cases get their own AC IDs: `AC-3.1-NEG`
+
+---
+
+### Anti-Patterns
+
+- Don't implement test logic — skeletons are pending/skipped stubs only
+- Don't combine multiple ACs into one test — one AC = one test case
+- Don't omit the story/criterion ID from test names — traceability is the point
+- Don't guess the test framework — read `docs/tech-stack.md` and `docs/tdd-standards.md`
+- Don't create test files outside the project's test directory convention
+- Don't add assertion logic to skeletons — that's the implementation agent's job
+- Don't generate skeletons for non-functional requirements unless they have explicit ACs
+- Don't skip the story-tests-map — it's the verification artifact that proves coverage

package/{knowledge → content/knowledge}/execution/enhancement-workflow.md

@@ -42,7 +42,7 @@ Read these documents in order before proposing any changes:
 1. **Product vision** (`docs/vision.md` or equivalent) — understand the project's purpose and direction
 2. **PRD** (`docs/prd.md`) — understand existing requirements and constraints
 3. **User stories** (`docs/user-stories.md`) — understand who uses the system and how
-4. **Architecture** (`docs/architecture.md` or ADRs) — understand the technical structure
+4. **Architecture** (`docs/system-architecture.md` or ADRs) — understand the technical structure
 5. **Coding standards** (`docs/coding-standards.md`) — understand conventions you must follow
 6. **TDD standards** (`docs/tdd-standards.md`) — understand testing expectations
 7. **Project structure** (`docs/project-structure.md`) — understand where code lives