@sandrinio/vbounce 1.0.0

package/templates/hotfix.md

@@ -0,0 +1,57 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. This is a lightweight alternative to the Epic/Story hierarchy for L1 (Trivial) tasks.
+
+1. **Metadata Table**: Target Release, Status, Actor
+2. **§1 The Fix**: What is broken/changing and why
+3. **§2 Implementation Instructions**: Which file(s) to change and what to do
+4. **§3 Verification**: Simple manual test
+
+Output location: `product_plans/{delivery}/HOTFIX-{Date}-{Name}.md`
+
+Document Hierarchy Position: BYPASS
+This document bypasses the Roadmap → Epic → Story hierarchy. It is for L1 (Trivial) changes only (e.g., typos, CSS tweaks, single-line logic fixes).
+
+Constraints:
+- Must touch 1-2 files maximum.
+- Must NOT introduce new architectural patterns.
+- Must NOT require complex new testing infrastructure.
+- If it violates these constraints, the Team Lead MUST escalate it to an Epic.
+
+Do NOT output these instructions.
+</instructions>
+
+# HOTFIX: {Name}
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Target Release** | `D-{NN}_{release_name}` |
+| **Status** | Draft / Bouncing / Done |
+| **Actor** | {Persona Name / User} |
+| **Complexity Label** | L1 (Trivial) |
+
+---
+
+## 1. The Fix
+> What needs to be changed and why.
+
+- **Current Behavior**: {What is wrong}
+- **Desired Behavior**: {What it should be}
+
+---
+
+## 2. Implementation Instructions
+> Direct commands for the Developer Agent.
+
+- **Files to Modify**: `{filepath}`
+- **Instructions**: {e.g., "Change the padding-left from 10px to 20px" or "Fix the typo in the error message."}
+
+---
+
+## 3. Verification
+> How the Human or QA agent will quickly verify this.
+
+- [ ] {Simple step, e.g., "Open the settings modal and verify the button is aligned."}
+- [ ] Automated tests still pass (`npm test`).
+- [ ] **Post-Fix Action**: Run `./scripts/hotfix_manager.sh ledger "HOTFIX: {Name}" "{Brief Fix Description}"`

package/templates/risk_registry.md

@@ -0,0 +1,89 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+
+1. **Header**: Set Status, link to Roadmap and Delivery Plan
+2. **§1 Active Risks**: Table of open risks with phase, source, likelihood, impact, mitigation
+3. **§2 Risk Analysis Log**: Phase-stamped entries appended on state transitions
+4. **§3 Closed Risks**: Resolved/mitigated risks moved here
+5. **§4 Change Log**: Auto-appended on updates
+
+Risk Levels:
+- Likelihood: Low / Medium / High
+- Impact: Low / Medium / High / Critical
+
+Risk Statuses: Open → Mitigating → Mitigated → Closed / Accepted
+
+Output location: `product_plans/RISK_REGISTRY.md`
+
+Document Hierarchy Position: LEVEL 6 — CROSS-CUTTING
+Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → **Risk Registry** (risks)
+
+This document is fed by ALL levels of the hierarchy:
+- Charter §6 Constraints → initial strategic risks
+- Roadmap §4 Dependencies → integration and external service risks
+- Roadmap §5 Strategic Constraints → capacity, budget, deadline risks
+- Epic §6 Risks & Edge Cases → feature-level risks
+- Delivery Plan sprint transitions → trigger Risk Analysis Log entries (§2)
+- Architect Agent's Deep Audit findings → may surface new risks
+
+The Risk Registry is reviewed by the Team Lead at sprint boundaries and by the Architect Agent during Deep Audit reviews.
+
+Do NOT output these instructions.
+</instructions>
+
+# Risk Registry: {Project Name}
+
+---
+
+> **Last Updated**: {YYYY-MM-DD}
+> **Status**: Active / Archived
+> **Roadmap**: `product_plans/{project}_roadmap.md`
+
+---
+
+## 1. Active Risks
+
+| ID | Risk | Phase | Source | Likelihood | Impact | Mitigation | Owner | Status |
+|----|------|-------|--------|------------|--------|------------|-------|--------|
+| R-001 | {Risk description} | {Verification/Bounce/Review} | {EPIC-XXX or STORY-XXX-YY} | Low/Medium/High | Low/Medium/High/Critical | {Mitigation strategy} | {Owner} | Open |
+
+**Summary**: {X} Active | {Y} Mitigating | {Z} Accepted
+
+---
+
+## 2. Risk Analysis Log
+
+> Phase-stamped entries. Each entry is appended when a document transitions between V-Bounce phases.
+
+### {YYYY-MM-DD} — Phase: {Verification / Bounce / Review} ({Sprint S-XX})
+**Trigger**: {What caused this analysis — e.g., "Sprint 1 stories moved to Ready to Bounce"}
+**Documents Analyzed**: {List of docs reviewed}
+
+**New Risks Identified**:
+- R-{NNN}: {Risk description} — Source: {doc reference}
+
+**Risks Updated**:
+- R-{NNN}: {Status change and reason}
+
+**Risks Resolved**:
+- R-{NNN}: {Resolution description}
+
+**Recommendation**: {Action items if any}
+
+---
+
+## 3. Closed Risks
+
+| ID | Risk | Resolution | Phase Closed | Closed Date |
+|----|------|------------|--------------|-------------|
+| R-{NNN} | {Risk description} | {How it was resolved} | {Phase} | {YYYY-MM-DD} |
+
+---
+
+## 4. Change Log
+
+<!-- Auto-appended when Risk Registry is updated -->
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Initial creation | Architect |

package/templates/roadmap.md

@@ -0,0 +1,176 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
+
+1. **Header**: Set Status, Last Updated, link to Charter
+2. **§1 Strategic Context**: Vision (from Charter), primary goal, target users, success metrics
+3. **§2 Release Plan**: Group epics into named releases with exit criteria — NOT sprint-level tracking
+4. **§3 Technical Architecture Decisions**: Key choices with rationale and status (this is the ADR log)
+5. **§4 Dependencies & Integration Map**: External services, cross-epic dependencies, blocking relationships
+6. **§5 Strategic Constraints**: Budget, capacity, hard deadlines, regulatory requirements
+7. **§6 Open Questions**: Unresolved items that affect strategic direction
+8. **§7 Delivery Log**: Release notes for completed deliveries (appended by Team Lead on delivery archive)
+9. **§8 Change Log**: Auto-appended on updates
+
+Output location: `product_plans/{project}_roadmap.md`
+
+Role of this document:
+- This is the STRATEGIC layer between Charter (why) and Delivery Plan (operational execution).
+- It answers: "What are we shipping, in what order, and what architectural bets are we making?"
+- It does NOT track sprint-level progress — that belongs in the Delivery Plan.
+- It does NOT track individual story status — that belongs in the Delivery Plan.
+- It DOES define release milestones, architectural decisions, and strategic constraints.
+
+Document Hierarchy Position: LEVEL 2 — STRATEGIC
+Charter (why) → **Roadmap** (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
+
+Do NOT output these instructions.
+</instructions>
+
+# Product Roadmap: {Project Name}
+
+---
+
+> **Last Updated**: {YYYY-MM-DD}
+> **Status**: Planning / Active / MVP Complete / Shipped
+> **Charter**: `product_plans/{project}_charter.md`
+> **Risk Registry**: `product_plans/RISK_REGISTRY.md`
+
+---
+
+## 1. Strategic Context
+
+| Key | Value |
+|-----|-------|
+| **Vision** | {One sentence from Charter §1.1} |
+| **Primary Goal** | {Main objective for this project window} |
+| **Tech Stack** | {e.g., Next.js, FastAPI, Supabase} |
+| **Target Users** | {Primary user persona from Charter} |
+
+### Success Metrics
+> Pulled from Charter §1.3. These define when the project is "done."
+
+- {Metric 1: e.g., "User signup conversion > 60%"}
+- {Metric 2: e.g., "Page load < 2s on 3G"}
+
+---
+
+## 2. Release Plan
+
+> Group epics into named releases with clear exit criteria. Each release is a shippable milestone.
+> Releases are NOT sprints — a release may span multiple sprints.
+> Sprint-level tracking belongs in the Delivery Plan.
+
+### Release 1: {Release Name} (e.g., "Foundation")
+**Target**: {YYYY-MM-DD or Quarter}
+**Exit Criteria**: {What must be true for this release to ship — e.g., "Users can sign up, log in, and see dashboard"}
+
+| Epic | Priority | Status | Notes |
+|------|----------|--------|-------|
+| EPIC-001: {Name} | P0 | Draft / Ready / In Progress / Done | {Dependencies or blockers} |
+| EPIC-002: {Name} | P1 | Draft | |
+
+### Release 2: {Release Name} (e.g., "Core Features")
+**Target**: {YYYY-MM-DD or Quarter}
+**Exit Criteria**: {e.g., "Full CRUD on all entities, third-party integration live"}
+
+| Epic | Priority | Status | Notes |
+|------|----------|--------|-------|
+| EPIC-003: {Name} | P0 | Draft | |
+
+### Release 3: {Release Name} (e.g., "Polish & Scale")
+**Target**: {YYYY-MM-DD or Quarter}
+**Exit Criteria**: {e.g., "Performance targets met, monitoring in place"}
+
+| Epic | Priority | Status | Notes |
+|------|----------|--------|-------|
+| {Future Epics} | | | |
+
+---
+
+## 3. Technical Architecture Decisions
+
+> Architecture Decision Records (ADRs). Agents reference these when hitting ambiguity.
+> Each decision is immutable once "Decided" — create a new row to override.
+
+| ID | Decision | Choice | Rationale | Status | Date |
+|----|----------|--------|-----------|--------|------|
+| ADR-001 | Auth Provider | {e.g., Supabase Auth} | {Why — cost, speed, integration} | Decided / Proposed / Superseded | {YYYY-MM-DD} |
+| ADR-002 | Database | {e.g., PostgreSQL via Supabase} | {Why} | Decided | |
+| ADR-003 | Hosting | {e.g., Vercel + Railway} | {Why} | Proposed | |
+| ADR-004 | State Management | {e.g., Zustand} | {Why} | Decided | |
+
+---
+
+## 4. Dependencies & Integration Map
+
+> External services, cross-epic dependencies, and anything that blocks progress if unavailable.
+
+### External Dependencies
+| Service | Purpose | Status | Risk if Unavailable |
+|---------|---------|--------|---------------------|
+| {e.g., Stripe API} | Payment processing | Available / Pending Access / TBD | {e.g., "Cannot ship Release 2"} |
+| {e.g., SendGrid} | Transactional email | Available | Low — fallback exists |
+
+### Cross-Epic Dependencies
+| Epic | Depends On | Relationship | Status |
+|------|------------|--------------|--------|
+| EPIC-003 | EPIC-001 | Requires auth system | Blocked / Ready |
+| EPIC-004 | EPIC-002 | Shares data model | In Progress |
+
+---
+
+## 5. Strategic Constraints
+
+> Hard boundaries that shape prioritization and scope. These override feature requests.
+
+| Constraint | Type | Impact | Mitigation |
+|------------|------|--------|------------|
+| {e.g., Launch by Q2 2026} | Deadline | Caps scope to Release 1 + 2 | Cut P2 epics if behind |
+| {e.g., Solo developer} | Capacity | Max 2 epics per sprint | Lean on AI agents for L1-L2 stories |
+| {e.g., GDPR compliance} | Regulatory | Must audit data flows before launch | Include in Release 1 exit criteria |
+| {e.g., $0 infrastructure budget} | Budget | Free-tier only | Supabase free tier + Vercel hobby |
+
+---
+
+## 6. Open Questions
+
+> Unresolved items that affect strategic direction. Operational questions go in the Delivery Plan.
+
+| Question | Options | Impact | Owner | Status |
+|----------|---------|--------|-------|--------|
+| {e.g., "Build mobile app or PWA?"} | A: Native, B: PWA | Affects Release 3 scope | {name} | Open / Decided |
+| {e.g., "Self-host or managed DB?"} | A: Supabase, B: PlanetScale | ADR-002 | {name} | Decided |
+
+---
+
+## 7. Delivery Log
+
+> Appended by Team Lead when a delivery (release) is archived.
+> Each entry is the release notes — a summary of sprint reports from that delivery.
+
+### D-{NN}: {Release Name}
+**Delivered**: {YYYY-MM-DD}
+**Release Tag**: v{VERSION}
+**Delivery Folder**: `product_plans/archive/D-{NN}_{release_name}/`
+
+**Release Notes**:
+> {Summary of what was shipped — compiled from sprint reports. Key features, important fixes, architectural changes.}
+
+**Metrics**:
+| Metric | Value |
+|--------|-------|
+| Stories Delivered | {X} |
+| Stories Escalated | {Y} |
+| Total Sprints | {N} |
+| Average Bounce Ratio | {X}% |
+| Average Correction Tax | {X}% |
+
+---
+
+## 8. Change Log
+
+<!-- Auto-appended when Roadmap is updated -->
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Initial creation from Charter | Architect |

package/templates/sprint_report.md

@@ -0,0 +1,151 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-6.
+
+1. **Header**: Sprint ID, Goal, Dates, Status, Delivery
+2. **§1 What Was Delivered**: User-facing summary — what's accessible/usable vs what's internal/backend
+3. **§2 Story Results**: Table of all stories with final status and per-story metrics
+4. **§3 Execution Metrics**: AI performance metrics — tokens, duration, bounces, correction tax
+5. **§4 Lessons Learned**: Flagged from agent reports, pending user approval to record
+6. **§5 Retrospective**: What went well, what didn't, and what to change — covers both project and delivery process
+
+This template is used by the Team Lead at Sprint Consolidation (Step 7).
+Written to `.bounce/sprint-report.md`, then archived to `.bounce/archive/S-{XX}/`.
+
+When the delivery completes, sprint reports are summarized into the Roadmap §7 Delivery Log
+as Release Notes.
+
+The §1 section is critical — the user wants to know what they can see, touch, and use NOW
+versus what was built under the hood. Write it from the user's perspective, not the developer's.
+
+Do NOT output these instructions.
+</instructions>
+
+# Sprint Report: S-{XX}
+
+---
+
+> **Sprint Goal**: {One-sentence North Star}
+> **Dates**: {MM/DD - MM/DD}
+> **Status**: Achieved / Partially Achieved / Failed
+> **Delivery**: D-{NN}_{release_name}
+> **Delivery Plan**: `product_plans/{delivery}/DELIVERY_PLAN.md`
+
+---
+
+## 1. What Was Delivered
+
+### User-Facing (Accessible Now)
+> Features, screens, or workflows the user can see, interact with, or test right now.
+
+- {e.g., "Login page with email/password authentication — accessible at /login"}
+- {e.g., "Dashboard with project overview cards — accessible at /dashboard"}
+- {e.g., "Settings page with profile editing — accessible at /settings"}
+
+### Internal / Backend (Not Directly Visible)
+> Infrastructure, APIs, database changes, or plumbing that supports future features.
+
+- {e.g., "User roles and permissions system — API endpoints ready, no UI yet"}
+- {e.g., "Database migration for notifications table — schema deployed"}
+- {e.g., "Rate limiting middleware on all API routes"}
+
+### Not Completed
+> Stories that were planned but didn't make it (escalated, deferred, or partially done).
+
+- {e.g., "STORY-001-03: Email notifications — Escalated (template integration failed 3x)"}
+
+### Product Docs Affected
+> Any product documentation files modified, created, or identified for updates. Handed off to Scribe agent.
+
+- {e.g., "product_documentation/api_reference.md — Added rate limiting details"}
+
+---
+
+## 2. Story Results
+
+| Story | Epic | Label | Final State | Bounces (QA) | Bounces (Arch) | Correction Tax |
+|-------|------|-------|-------------|--------------|----------------|----------------|
+| STORY-{ID}: {name} | EPIC-{ID} | L{N} | Done / Escalated / Parking Lot | {N} | {N} | {X}% |
+
+### Story Highlights
+- **{STORY-ID}**: {1-sentence summary of what was built and any notable decisions}
+
+### Escalated Stories (if any)
+- **{STORY-ID}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
+
+---
+
+## 3. Execution Metrics
+
+### AI Performance
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| **Total Tokens Used** | {N} | input + output across all agents |
+| **Output Tokens** | {N} | tokens generated by agents |
+| **Input Tokens** | {N} | context fed to agents |
+| **Total Execution Duration** | {X}h {Y}m | wall-clock time from sprint start to completion |
+| **Agent Sessions** | {N} | total subagent spawns (Dev + QA + Arch + DevOps + Scribe) |
+| **Estimated Cost** | ${X.XX} | based on model pricing at time of execution |
+
+### V-Bounce Quality
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| **Stories Planned** | {X} | |
+| **Stories Delivered** | {Y} | |
+| **Stories Escalated** | {Z} | |
+| **Total QA Bounces** | {N} | across all stories |
+| **Total Architect Bounces** | {N} | across all stories |
+| **Bounce Ratio** | {X}% | (total bounces / total stories) |
+| **Average Correction Tax** | {X}% | (0% = autonomous, 100% = human rewrote everything) |
+| **First-Pass Success Rate** | {X}% | stories that passed QA on first try |
+| **Merge Conflicts** | {N} simple, {N} complex | |
+
+### Per-Story Breakdown
+
+| Story | Tokens | Duration | Agent Sessions | Bounces | Cost |
+|-------|--------|----------|----------------|---------|------|
+| STORY-{ID} | {N} | {Xh Ym} | {N} | {N} | ${X.XX} |
+
+---
+
+## 4. Lessons Learned
+
+> Flagged by agents during the sprint. Each needs user approval before recording to LESSONS.md.
+
+| Source | Lesson | Approved? |
+|--------|--------|-----------|
+| STORY-{ID} Dev Report | {What happened and proposed rule} | Pending / Yes / No |
+
+---
+
+## 5. Retrospective
+
+### What Went Well
+> Practices, patterns, or decisions that worked and should be repeated.
+
+- {e.g., "Splitting EPIC-001 into small L2 stories kept bounces low — 80% first-pass success"}
+- {e.g., "Reading _manifest.json upfront saved Dev from duplicating existing API docs"}
+
+### What Didn't Go Well
+> Problems encountered, root causes, and impact on the sprint.
+
+- {e.g., "STORY-001-03 escalated because the spec was ambiguous — 3 QA bounces wasted"}
+- {e.g., "Merge conflict on STORY-002-01 required a fix story — cost an extra half-day"}
+
+### Process Improvements
+> Changes to the V-Bounce delivery process itself — not just this project, but how we work.
+
+- {e.g., "Story specs for L3+ stories should require Architect pre-review before bouncing"}
+- {e.g., "QA found the same import ordering issue in 3 stories — add linting rule to Dev setup, not just LESSONS.md"}
+- {e.g., "L3 stories consumed 4x the tokens of L2s — add a complexity budget to sprint planning"}
+- {e.g., "First-pass success rate was 40% — require Ambiguity 🟢 on all stories, not just Context Pack checks"}
+- {e.g., "Sprint Integration Audit (Step 6) found no issues in 3 consecutive sprints — consider making it conditional for small sprints"}
+
+---
+
+## 6. Change Log
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Sprint Report generated | Team Lead |

package/templates/story.md

@@ -0,0 +1,150 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+
+1. **Metadata Table**: Parent Epic, Status, Ambiguity, Actor, Complexity, Complexity Label
+2. **§1 The Spec**: User Story (As a... I want... So that...) + Detailed Requirements
+3. **§2 The Truth**: Gherkin acceptance criteria + manual verification steps
+4. **§3 Implementation Guide**: Files to modify, technical logic, API contract
+5. **§4 Definition of Done**: Checklist (compiles, tests pass, linting, docs)
+
+Ambiguity Score:
+- 🔴 High: Requirements unclear
+- 🟡 Medium: Logic clear, files TBD
+- 🟢 Low: Ready for coding
+
+Output location: `product_plans/{delivery}/EPIC-{NNN}_{epic_name}/STORY-{EpicID}-{StoryID}.md`
+(Stories live inside their parent Epic folder — a Story never exists without an Epic.)
+
+Document Hierarchy Position: LEVEL 4 (Charter → Roadmap → Epic → **Story**)
+
+Upstream sources:
+- §1 The Spec inherits from parent Epic §2 Scope Boundaries
+- §3 Implementation Guide references Epic §4 Technical Context and Roadmap §3 ADRs
+- Acceptance criteria (§2) refine Epic §7 Acceptance Criteria into per-story scenarios
+- Complexity Label aligns with Delivery Plan story label definitions (L1-L4)
+
+Downstream consumers:
+- Developer Agent reads §1 The Spec and §3 Implementation Guide (with react-best-practices skill)
+- QA Agent reads §2 The Truth to validate implementation (with vibe-code-review skill)
+- Architect Agent reads full story context for Safe Zone compliance audit
+- Delivery Plan §3 Active Sprint tracks story V-Bounce state
+- Delivery Plan §5 Context Pack Status tracks per-story readiness using this template's sections
+
+Agent handoff sections:
+- §1 The Spec → Human contract (PM/BA writes, Dev reads)
+- §2 The Truth → QA contract (BA writes, QA Agent executes)
+- §3 Implementation Guide → AI-to-AI instructions (Architect writes, Dev Agent executes)
+
+Do NOT output these instructions.
+</instructions>
+
+# STORY-{EpicID}-{StoryID}: {Story Name}
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Parent Epic** | [EPIC-{ID}: {Name}](link) |
+| **Status** | Draft / Refinement / Probing/Spiking / Ready to Bounce / Bouncing / QA Passed / Architect Passed / Sprint Review / Done / Escalated / Parking Lot |
+| **Ambiguity** | 🔴 High / 🟡 Medium / 🟢 Low |
+| **Context Source** | Epic §{section} / Codebase / User Input |
+| **Actor** | {Persona Name} |
+| **Complexity** | Small (1 file) / Medium (2-3 files) / Large (Refactor needed) |
+| **Complexity Label** | L1 / L2 / L3 / L4 (default: L2) |
+
+### Complexity Labels (Sprint Planning)
+
+- **L1**: Trivial — Single file, <1hr vibe time, known pattern
+- **L2**: Standard — 2-3 files, known pattern, ~2-4hr vibe time *(default)*
+- **L3**: Complex — Cross-cutting, spike may be needed, ~1-2 days
+- **L4**: Uncertain — Requires Probing/Spiking before Bounce, >2 days
+
+This story is labeled: **{L1/L2/L3/L4}**
+
+---
+
+## 1. The Spec (The Contract)
+> Human-Readable Requirements. The "What".
+> Target Audience: PM, BA, Stakeholders, Developer Agent.
+
+### 1.1 User Story
+> As a **{Persona}**,
+> I want to **{Action}**,
+> So that **{Benefit}**.
+
+### 1.2 Detailed Requirements
+- **Requirement 1**: {Specific behavior, e.g., "The button must be disabled until..."}
+- **Requirement 2**: {Specific data, e.g., "The field accepts only valid UUIDs."}
+- **Requirement 3**: {UI state, e.g., "Show a spinner while loading."}
+
+---
+
+## 2. The Truth (Executable Tests)
+> The QA Agent uses this to verify the work. If these don't pass, the Bounce failed.
+> Target Audience: QA Agent (with vibe-code-review skill).
+
+### 2.1 Acceptance Criteria (Gherkin/Pseudocode)
+```gherkin
+Feature: {Story Name}
+
+  Scenario: {Happy Path}
+    Given {precondition}
+    When {user action}
+    Then {system response}
+    And {database state change}
+
+  Scenario: {Edge Case / Error}
+    Given {precondition}
+    When {invalid action}
+    Then {error message}
+```
+
+### 2.2 Verification Steps (Manual/Mob)
+- [ ] Verify visual alignment with Design System.
+- [ ] Check mobile responsiveness.
+
+---
+
+## 3. The Implementation Guide (AI-to-AI)
+> Instructions for the Developer Agent. The "How".
+> Target Audience: Developer Agent (with react-best-practices + lesson skills).
+
+### 3.1 Context & Files
+| Item | Value |
+|------|-------|
+| **Primary File** | `{filepath/to/main/component.ts}` |
+| **Related Files** | `{filepath/to/api/service.ts}`, `{filepath/to/types.ts}` |
+| **New Files Needed** | Yes/No — `{Name of file}` |
+| **ADR References** | ADR-{NNN} from Roadmap §3 |
+
+### 3.2 Technical Logic
+- {Describe the logic flow, e.g., "Use the existing useAuth hook to check permissions."}
+- {Describe state management, e.g., "Store the result in the global Zustand store."}
+
+### 3.3 API Contract (If applicable)
+```json
+// Expected Request
+POST /api/resource
+{
+  "id": "string",
+  "value": number
+}
+
+// Expected Response
+200 OK
+{
+  "id": "string",
+  "status": "created"
+}
+```
+
+---
+
+## 4. Definition of Done (The Gate)
+- [ ] Code compiles without errors.
+- [ ] New Unit Tests are written and passing.
+- [ ] All Acceptance Criteria (§2.1) pass.
+- [ ] Linting rules passed.
+- [ ] LESSONS.md consulted before implementation.
+- [ ] No violations of Roadmap ADRs.
+- [ ] Documentation (API/Tech Stack) updated.