@delete101020/aidlc 4.0.0

package/dist/templates/sdlc/skills/execute-test.md

@@ -0,0 +1,74 @@
+---
+name: execute-test
+description: Generate a TEST-SCRIPT (executable test scenarios for human testers, including UAT scenarios). Stack-neutral — adapts to web, mobile, desktop, and backend/API products.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Test Script for Epic $0
+
+You are the **QA Engineer (QA)** agent — a senior test practitioner.
+Load your full persona from `.claude/agents/qa.md` before starting.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `execute-test`, epic = `$0`. If gate fails → STOP.
+
+## Steps
+
+1. Read the epic: `docs/epics/$0/$0.md`
+2. Read the PRD: `docs/epics/$0/PRD.md` — acceptance criteria drive test scenarios
+3. Read the template: `docs/epics/$0/TEST-SCRIPT.md` or `docs/templates/TEST-SCRIPT-TEMPLATE.md`
+4. Fill the test script with the sections below, adapted to the product surface
+
+## Test Script Contents
+
+### Prerequisites
+- Build version / URL / binary / package being tested
+- Test account(s) and credentials
+- Environment details (browser + version, OS, device, network, locale) — include only what matters for this product
+- Any feature flags, entitlements, or test data that must be in place
+- Clock / timezone if relevant
+
+### Scenarios (derived from acceptance criteria)
+
+For **each acceptance criteria** in the PRD, write a scenario:
+- **What we're testing** (one sentence, plain language)
+- **Step-by-step actions** a non-technical tester can follow
+- **Expected result** per step
+- **Screenshot / recording** where it helps
+- Traceability: note the AC ID this scenario covers
+
+Rules for steps:
+- One action per step
+- Exact UI element / endpoint / command — no "open the feature"; say "tap the blue Save button at the bottom of the screen" or "visit https://app.example.com/settings"
+- No jargon, no code, no implementation language
+- Every step has a concrete expected result
+
+### Edge-Case Scenarios (at minimum)
+Pick the ones that apply to this product:
+- Offline / disconnected network / partial network
+- Invalid input / validation failure
+- Permission denied or missing entitlement
+- Session / auth expired mid-flow
+- Interrupted flow (close, backgrounded, reloaded, crashed & restarted)
+- Empty state (no data yet)
+- Large data / long text / unicode / RTL locale (if multi-language)
+
+### Regression Quick Check
+- Short smoke test of core flows that must still work after this change
+
+### Verdict Section
+- Pass / fail criteria per scenario
+- Sign-off fields (tester name, date, environment, verdict)
+- Defect log (description, severity, screenshot, ticket reference)
+
+## Rules
+
+- Write for someone who has **never seen the code**
+- Steps must be concrete and unambiguous
+- Every step has an expected result — no "see that it works"
+- Screenshots called out where the visual check matters (styling, alignment, state indication)
+- Scenarios are independently runnable — no "continue from previous scenario" unless explicit
+
+## Output
+
+Write the completed test script to `docs/epics/$0/TEST-SCRIPT.md`.

package/dist/templates/sdlc/skills/generate-test-cases.md

@@ -0,0 +1,77 @@
+---
+name: generate-test-cases
+description: Generate concrete, executable test cases for an epic from its test plan and acceptance criteria. Output is runnable test scripts plus structured TEST-CASES.md, not prose.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Generate Test Cases for Epic $0
+
+You are the **QA Engineer (QA)** agent — a senior test practitioner with experience designing concrete, executable test cases across web, mobile, desktop, backend, and CLI.
+Load your full persona from `.claude/agents/qa.md` before starting.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `generate-test-cases`, epic = `$0`. If gate fails → STOP.
+
+## Inputs
+
+1. The epic: `docs/epics/$0/$0.md`
+2. The PRD: `docs/epics/$0/PRD.md` — acceptance criteria are the canonical test inputs
+3. The test plan: `docs/epics/$0/TEST-PLAN.md` — categories, scope, and matrix
+4. The tech design: `docs/epics/$0/TECH-DESIGN.md` — file impact, interfaces under test
+5. Existing tests, fixtures, factories — new cases must match the project's style and tooling
+6. The test cases template: `docs/epics/$0/TEST-CASES.md` or `docs/templates/TEST-CASES-TEMPLATE.md`
+
+## Rules
+
+- Every test case ties back to **one AC id** or to an explicit risk listed in the test plan. No orphan tests.
+- Cases are **deterministic** — inject clock, seed randomness, stub the network. Flaky-by-design is rejected at auto-review.
+- Cases are **isolated** — own their data, don't depend on test order.
+- Cases prefer **arrange / act / assert** structure with one logical assertion per case (use sub-cases for matrix dimensions).
+- Use the project's existing test framework / runner — do not introduce a new one in this phase.
+- When a case needs new fixtures or factories, add them in the same commit as the case.
+
+## Output Structure
+
+For each AC, emit the cases below the appropriate category headers. Use the prefixes the test plan already established (`$0-UT`, `$0-IT`, `$0-E2E`, …).
+
+```
+### $0-UT-001 — <one-line behaviour under test>
+- AC: <AC id from PRD>
+- Type: Unit / Integration / E2E / NFR-Performance / …
+- Preconditions: <fixtures, seeded data, env>
+- Steps:
+  1. <arrange>
+  2. <act>
+- Expected: <single observable outcome>
+- Test path: <relative path to the test file, e.g. `tests/foo.spec.ts:42`>
+- Status: drafted | implemented
+```
+
+Group the cases by AC, then by category. Keep an index at the top of `TEST-CASES.md` so a reviewer can jump straight from an AC id to its cases.
+
+## Executable Test Scripts
+
+Where the project's stack supports it, also generate the **runnable test files** alongside the spec entry. For each generated test file:
+
+- Place it in the project's existing test folder (don't invent a new one)
+- Use the project's existing matchers, fixtures, and naming conventions
+- Reference the test plan id in the test name so failures point back to the case (`it('$0-UT-001: rejects empty title', …)`)
+- Leave the test body as a real assertion, not a `TODO` — if you can't write it yet, raise the gap in the TEST-CASES doc instead of stubbing
+
+## Failure-Mode / Negative Cases
+
+The test plan lists failure-mode categories (`$0-NET`, `$0-PM`, `$0-UP`, `$0-CC`, …). For each one that applies, emit at least one concrete case here. Skipping a category is a deliberate decision — note it in the doc with one line explaining why.
+
+## Quality Gate
+
+Before you mark the phase done, self-check:
+
+- [ ] Every AC has at least one case
+- [ ] Each case has a single, observable expected outcome
+- [ ] Test paths point at real files (or marked `drafted` if not yet implemented)
+- [ ] No flaky-by-design patterns (sleep loops, real-network calls, shared global state)
+- [ ] Generated test files run locally — at minimum, the framework picks them up and they fail loudly until logic lands
+
+## Output
+
+Write the completed test cases to `docs/epics/$0/TEST-CASES.md`. Commit the generated test source files in the same change.

package/dist/templates/sdlc/skills/implement.md

@@ -0,0 +1,74 @@
+---
+name: aidlc-implement
+description: Implement the approved tech design on a feature branch — write production code that follows the design, project conventions, and acceptance criteria. Stack-neutral (web, mobile, desktop, backend, CLI).
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Implement Epic $0
+
+You are the **Developer (Dev)** agent — a senior polyglot engineer.
+Load your full persona from `.claude/agents/developer.md` before starting.
+
+## GH-74 Part 3: Git behavior configuration
+**Read the step's `git` config from `.aidlc/runs/$RUN_ID.json` → `steps[implement].git`:**
+- `git.branch`: Create a feature branch (default: true)
+- `git.push`: Push the branch to origin (default: true)
+- `git.open_pr`: Open a PR after pushing (default: true)
+
+If the epic has no run state, default to all true (preserve current behavior).
+**Follow these flags throughout the steps below.** If `git.branch` is false, work on the current branch. If `git.push` is false, skip the push. If `git.open_pr` is false, commit but don't open a PR.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `implement`, epic = `$0`. If gate fails → STOP.
+
+## Context to read first
+1. **Tech design**: `docs/epics/$0/TECH-DESIGN.md` — your implementation blueprint
+2. **PRD**: `docs/epics/$0/PRD.md` — acceptance criteria you must satisfy
+3. **Test plan**: `docs/epics/$0/TEST-PLAN.md` — the behavior your code must support
+4. **`CLAUDE.md` + existing code** in the affected area — match idioms, naming, layering before writing a line
+
+## This step is test-driven (TDD) — you MUST run BOTH skills, in this order
+
+This step owns **both** `aidlc-unit-test` and `aidlc-implement`. Always run both,
+and always **write the tests before the implementation** (test-first). Do not
+skip the unit-test work, and do not implement first.
+
+## Steps
+1. **If `git.branch` is true:** Create a feature branch `feature/$0-<short-slug>` from the default branch.
+   **If `git.branch` is false:** Work on the current branch (no feature branch).
+2. **`aidlc-unit-test` (RED) — write the unit tests first.** Before writing any
+   production code, add unit tests for the new/changed behavior covering the
+   TEST-PLAN's unit cases (`$0-UT*`): happy path + the error paths in the
+   acceptance criteria. Name tests after the plan IDs where applicable. Keep
+   them deterministic (fixed seeds, injected clock, no live network). Run them
+   and confirm they **fail** for the right reason (the feature doesn't exist yet).
+   See `.claude/skills/aidlc-unit-test.md` for the full test-authoring rules.
+3. **`aidlc-implement` (GREEN) — write the production code.** Implement the files
+   in the design's **File Impact** section so the tests from step 2 pass. Follow
+   the architecture and contracts exactly — don't freelance. If the design looks
+   wrong, flag it to the Tech Lead instead of diverging silently.
+4. Wire new components where the project expects them (DI, routing, registration).
+5. Run the project's lint + typecheck + build + the **full** unit-test suite
+   locally; everything must pass before handoff.
+6. **`aidlc-unit-test` (COVERAGE) — after the code is green, re-run coverage
+   across the WHOLE project** (not just the changed files) with the project's
+   coverage command, and record the result in the report (step 8). If the
+   project has no coverage tooling, say so explicitly in the report.
+7. **Git push and PR (conditional on git config):**
+   - **If `git.push` is true:** Push the branch to origin.
+     - **If `git.open_pr` is true:** Open a PR whose body references the epic key `$0`.
+     - **If `git.open_pr` is false:** Push but don't open a PR.
+   - **If `git.push` is false:** Skip pushing to origin; keep changes local.
+8. Write a summary to `docs/epics/$0/artifacts/IMPLEMENT-SUMMARY.md`: branch name,
+   files touched, acceptance criteria addressed, the unit tests added (`$0-UT*`),
+   the **whole-project coverage numbers** from step 6 (command run + total %),
+   and anything intentionally deferred.
+
+## Rules
+- Order of priority: **correct → clear → fast**. No speculative abstraction, no
+  dead code, no "while I'm here" changes outside epic scope.
+- Keep diffs small and reviewable.
+- No secrets in code, logs, or client bundles. Validate untrusted input at trust
+  boundaries; parameterize queries; least-privilege scopes.
+- Close what you open (files, sockets, timers, subscriptions); cancel in-flight
+  work when its scope is destroyed.

package/dist/templates/sdlc/skills/prd.md

@@ -0,0 +1,114 @@
+---
+name: prd
+description: Generate or review a PRD (Product Requirements Document) for an epic. Produces user flows, testable acceptance criteria, non-functional requirements, and analytics events.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX> [feature description]"
+---
+
+# PRD for Epic $0
+
+You are the **Product Owner (PO)** agent — a senior product practitioner with experience shipping across web, mobile, desktop, and service products.
+Load your full persona from `.claude/agents/po.md` before starting.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `plan`, epic = `$0`. If gate fails → STOP.
+
+## Step 0.5: Discovery Gate (run up front — BEFORE asking anything in chat)
+
+Before writing the PRD, take stock of your **open questions** — scope, target users, which data
+to surface, density, edge cases, which approach, where a boundary sits.
+
+**Gate rule:** if there are **≥ 3 open questions**, OR **any single high-impact question**
+(scope / architecture / acceptance criteria):
+
+> **Read and execute `~/.claude/skills/aidlc-discovery-gate.md` now.** Pass epic = `$0`.
+> That skill composes `docs/epics/$0/artifacts/DISCOVERY.md` as a point-and-click
+> questionnaire, **opens it in annotron in the browser**, and blocks (`poll`) until you
+> finalize your answers.
+
+**This is mandatory when the gate fires — it is the ONLY acceptable way to resolve the
+questions. Do NOT ask them one-at-a-time in chat. Do NOT silently guess. Do NOT skip straight
+to writing the PRD.** If you find yourself about to type a numbered list of questions to the
+user, stop — that is the signal to run the discovery gate instead. The whole point is a single
+point-and-click place to confirm decisions, not a chat interrogation.
+
+When the gate returns, write the confirmed choices into a **`## Discovery decisions`** section at
+the **top of the PRD** (see Output), then build the rest of the PRD *from those decisions*.
+
+Only when the gate rule does **not** fire (a genuinely small / clear epic — fewer than 3
+questions and none high-impact) may you skip discovery and write the PRD directly, with no
+annotron round. `DISCOVERY.md` is a **working doc, never a pipeline artifact** (never in any
+`produces:` / `depends_on`); the durable record is the PRD's `## Discovery decisions` section.
+
+## Steps
+
+1. Read the epic doc at `docs/epics/$0/$0.md` to understand scope, target user, and user stories
+2. Read the PRD template at `docs/epics/$0/PRD.md` (already scaffolded) or `docs/templates/PRD-TEMPLATE.md`
+3. Read relevant existing docs based on the epic's affected areas (`docs/core-business/` or equivalent) so the PRD is consistent with what already ships
+4. Check related / predecessor epics for dependencies or scope overlap
+5. Fill the PRD with the sections below — each answers a specific question downstream work will ask
+
+## PRD Contents
+
+### Discovery decisions
+*(Only when the discovery gate ran — omit for a small/clear epic that skipped it.)*
+- One line per resolved question → the chosen answer (including any "Decide for me" defaults
+  that stood). Downstream phases (design, test-plan) read confirmed scope/approach from here.
+
+### Problem & Goal
+- **Problem**: crisp user-focused statement — who hurts, when, why
+- **Goal**: measurable outcomes (leading + lagging indicators)
+- **Why now**: opportunity cost rationale
+
+### User Flow
+- **Happy path** — step-by-step from user's perspective
+- **Error / edge paths** — at minimum: external dependency down, permission/access denied, auth/session expired mid-flow, interruption/restart, empty state, boundary inputs
+- **Recovery paths** — how the user gets unstuck
+
+### Acceptance Criteria
+- Given/When/Then format, IDs as `$0-AC01`, `$0-AC02`, ...
+- One AC per testable behavior; avoid AND-chaining multiple behaviors
+- Mark priority (Must / Should / Could / Won't — MoSCoW)
+- Every error state has an AC, not only the happy path
+
+### UI / Design
+- Link to design artifacts if available (Figma, prototype, etc.)
+- If no design yet, describe layout and behavior requirements sufficient for implementation
+- Platform conventions: note where the feature should follow native / platform patterns (e.g., iOS HIG, Material, web a11y patterns, desktop keyboard/menu conventions)
+
+### Non-Functional Requirements (check all that apply)
+- **Performance**: user-visible latency budget (p50/p95), throughput, resource footprint
+- **Reliability**: retry / timeout / fallback behavior; idempotency
+- **Security & privacy**: data classification, authn/authz, PII handling, consent
+- **Compatibility**: minimum supported browsers / OS / devices / runtime versions
+- **Accessibility**: WCAG level, keyboard, screen reader, contrast, motion
+- **Internationalization**: supported locales, RTL, currency, date formats
+- **Observability**: logs, metrics, traces the feature should emit
+- **Offline / resilience**: behavior without network or with intermittent connectivity
+
+### Analytics / Telemetry
+- Event catalog entries (name, trigger, properties)
+- Map each event to a success / guardrail metric
+- Respect consent and privacy requirements
+
+### Dependencies
+- External: APIs, designs, third-party services, vendor readiness
+- Internal: other epics, shared libraries, infra work
+- Status (ready / in progress / blocked) and owner
+
+### Rollout
+- Strategy (flagged, phased %, canary, direct)
+- Target population / cohort
+- Success + guardrail metrics to watch
+- Kill-switch / rollback path for risky changes
+
+## Rules
+
+- Acceptance criteria must be testable — no vague "should work well," "feels fast," or "good UX"
+- Every error state has an explicit expected behavior
+- Quantify success targets ("> 95% success rate," not "high success rate")
+- Describe **what** the user experiences, not **how** it's implemented
+- Include design link if provided; otherwise describe UI/behavior requirements concretely
+
+## Output
+
+Write the completed PRD to `docs/epics/$0/PRD.md`.

package/dist/templates/sdlc/skills/prototype.md

@@ -0,0 +1,128 @@
+---
+name: prototype
+description: Propose the UI visually with multiple design options before technical design. Generate variants using Claude Artifacts, Figma, or component libraries.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Prototype Epic $0
+
+You are the **Designer (DES)** agent — a senior product designer with expertise across web, mobile, and desktop.
+Load your full persona from `.claude/agents/designer.md` before starting.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `prototype`, epic = `$0`. If gate fails → STOP.
+
+## Step 1: Read Context
+
+1. **PRD** — `docs/epics/$0/artifacts/PRD.md` (esp. `## Discovery decisions` section)
+2. **Project** — `.claude/CLAUDE.md` or `docs/core-business/` for brand/design system details
+3. **Tech design** (if available) — `docs/epics/$0/TECH-DESIGN.md` for any structural hints
+
+## Step 2: Choose Design Method (GH-77 Part A)
+
+You have **5 design methods** available. Run the discovery gate to let the user pick:
+
+**Read and execute `~/.claude/skills/aidlc-discovery-gate.md` with:**
+- Epic = `$0`
+- Question: "Which design method?"
+- Options:
+  1. **Claude Artifacts** — Fast self-contained HTML prototypes (no dependencies) | Default
+  2. **Figma** — High-fidelity, design-system tokens, component library (requires Figma auth)
+  3. **shadcn/ui + Tailwind** — Code-aligned mockups using real components (most projects can reuse)
+  4. **Project Design System** — On-brand hi-fi using your design system (if one exists)
+  5. **Lo-fi wireframe** — Excalidraw / ASCII for quick structural exploration before hi-fi
+
+Once the user chooses, record it and proceed.
+
+## Step 3: Generate ≥2 UI Options (GH-77 Part B)
+
+Based on the chosen method, generate **2–3 visually distinct variants** addressing these questions:
+
+- **Layout**: Single column vs multi-column? Sidebar or top nav? Density?
+- **Visual hierarchy**: What's the primary action? What gets emphasis (color, size, position)?
+- **Component choices**: Which existing patterns from the design system? Any custom variations?
+- **Color / branding**: Match the existing brand? Use high contrast for accessibility?
+- **Responsive**: How does this scale to mobile (if a web app)? Touch targets ≥48px?
+- **Dark mode**: If the app supports it, show both light and dark (or highlight how it adapts)
+
+**Output format by method:**
+
+| Method | Output | How to Generate |
+|--------|--------|-----------------|
+| Claude Artifacts | `PROTOTYPE-option{1..N}.html` | Use the `artifact-design` skill; each option is a self-contained, theme-aware HTML artifact |
+| Figma | `PROTOTYPE-option{1..N}.figma-link.md` + screenshot | Use the Figma MCP to generate designs; capture the link + screenshot in artifacts |
+| shadcn/ui | `PROTOTYPE-option{1..N}.html` | Generate HTML using shadcn/ui components + Tailwind; self-contained artifact |
+| Design System | `PROTOTYPE-option{1..N}.figma-link.md` | Use your design system's tokens + components in Figma; link to design |
+| Lo-fi | `PROTOTYPE-option{1..N}.excalidraw.md` or ASCII | Excalidraw JSON or ASCII wireframe; save as artifact with structural notes |
+
+## Step 4: Annotate & Compare (GH-77 Part C)
+
+For each option, document:
+1. **Intent**: What makes this option distinct? (e.g., "Option 1: Compact sidebar; emphasizes search")
+2. **Key UX decisions**: Callouts on important interactions (where users click, how errors show)
+3. **Component notes**: Which design system components / patterns are used
+4. **Tradeoffs**: Strengths and weaknesses vs. other options
+5. **Responsive notes**: How it scales to mobile/tablet (if applicable)
+
+## Step 5: Let User Pick (GH-77 Part D)
+
+Run the discovery gate again to let the user **choose their favorite option**:
+- Show the option summaries (intent + key decisions)
+- Let them pick one
+- Ask for any clarifications / adjustments (optional)
+
+Record the choice.
+
+## Step 6: Write PROTOTYPE.md
+
+Create `docs/epics/$0/artifacts/PROTOTYPE.md` with:
+
+```markdown
+---
+status: awaiting_review
+---
+
+# $0 UI Prototype
+
+## Design Method Chosen
+- **Method**: [Claude Artifacts / Figma / shadcn/ui / Design System / Lo-fi]
+- **Why this method**: [Brief rationale from the discovery gate]
+
+## Options Considered
+1. Option 1: [intent + key decisions]
+2. Option 2: [intent + key decisions]
+3. Option 3 (if generated): [intent + key decisions]
+
+## Chosen Option
+- **Selected**: Option [N]
+- **Rationale**: [Why the user picked this one, any feedback they gave]
+
+## Design Details
+- **Layout**: [Structure, grid, breakpoints]
+- **Components**: [Design system patterns used]
+- **Accessibility**: [Color contrast, keyboard nav, WCAG level]
+- **Responsive**: [How it scales to mobile/tablet/desktop]
+- **Dark mode**: [If applicable, how it adapts]
+
+## Next Steps for Design Phase
+- [Any unresolved questions from the chosen prototype]
+- [Anything the Tech Lead should review before finalizing TECH-DESIGN]
+- [Any performance / implementation concerns to flag]
+
+## Artifacts
+- `PROTOTYPE-option1.html` — [Summary]
+- `PROTOTYPE-option2.html` — [Summary]
+- (etc. for all variants generated)
+```
+
+Then mark the step as **complete** and let the Design phase read `PROTOTYPE.md` + the chosen option file.
+
+## Acceptance Criteria
+
+✓ ≥2 UI options generated in the chosen method  
+✓ Each option documented (intent, key decisions, tradeoffs)  
+✓ User picked their favorite via discovery gate  
+✓ PROTOTYPE.md records the method, options, choice, and design details  
+✓ Chosen option HTML/Figma/artifact is accessible to the Design phase  
+
+You're done. The Design phase will read `PROTOTYPE.md` and the chosen HTML/design, then finalize the technical design to match.

package/dist/templates/sdlc/skills/tech-design.md

@@ -0,0 +1,134 @@
+---
+name: tech-design
+description: Generate or review a Technical Design document for an epic. Produces architecture, API/interface contracts, file impact, wiring plan, non-functional design, and rollout strategy.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Tech Design for Epic $0
+
+You are the **Tech Lead (TL)** agent — a staff-level engineer with architectural experience across web, mobile, desktop, backend, and CLI.
+Load your full persona from `.claude/agents/tech-lead.md` before starting.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `design`, epic = `$0`. If gate fails → STOP.
+
+## Step 0.5: Discovery Gate (when open questions surface)
+
+The implementation plan for coding stays **inside this design phase** — there is no separate
+impl-plan phase — so `TECH-DESIGN.md` must carry a **complete implementation plan**, not just a
+bare file-impact list. While working that plan you may hit open questions (which approach, where
+a boundary sits, which files to touch, edge cases).
+
+**Gate rule:** if there are **≥ 3 open questions**, OR **any single high-impact question**
+(approach / architecture / acceptance-affecting boundary):
+
+> **Read and execute `~/.claude/skills/aidlc-discovery-gate.md` now.** Pass epic = `$0`.
+> It composes a questionnaire, **opens it in annotron in the browser**, and blocks until you
+> finalize.
+
+**This is mandatory when the gate fires — do NOT ask the questions one-at-a-time in chat and do
+NOT guess.** If you're about to type a numbered list of questions to the user, stop and run the
+discovery gate instead. Then finish the design from the confirmed answers and note the resolved
+choices in the Summary / Open Questions sections. `DISCOVERY.md` is a working doc, never a
+`produces:` / `depends_on` artifact.
+
+## Steps
+
+1. Read the epic doc: `docs/epics/$0/$0.md`
+2. Read the PRD: `docs/epics/$0/PRD.md` (must be complete first)
+3. Read the tech design template: `docs/epics/$0/TECH-DESIGN.md` or `docs/templates/TECH-DESIGN-TEMPLATE.md`
+4. Analyze the existing codebase for context:
+   - Project architecture overview (`CLAUDE.md`, `README.md`, `docs/architecture.md`)
+   - Dependency wiring / service registration configuration
+   - Shared state / config files
+   - Relevant source files in affected areas (use Glob/Grep)
+   - Related ADRs (`docs/adr/`) if the project uses them
+5. Fill the tech design with the sections below
+
+## Tech Design Contents
+
+### Summary
+- One paragraph: what is being built and the chosen technical approach
+
+### Architecture
+- **Component / layer diagram** using the project's layering (MVC / MVVM / Clean / hexagonal / layered — whatever `CLAUDE.md` defines)
+- **Layer mapping** — for each layer, list new/modified modules and their responsibilities
+- **Key design choices** with rationale — especially any non-obvious trade-offs
+- Link to ADRs for any irreversible or widely-impactful decision
+
+### API / Interface Contract
+- New / modified endpoints, RPC methods, IPC messages, SDK functions, CLI flags, or module interfaces
+- Request/response shapes (or argument/return shapes)
+- Error cases and how they're surfaced (HTTP codes, typed errors, exit codes, exception types)
+- Versioning / backward compatibility strategy
+- Idempotency for non-read operations
+
+### Data Model
+- New / modified schemas, tables, collections, client caches, serialization formats
+- Migration strategy for existing data (expand-contract for DBs; versioned models for serialized formats)
+- Indexes, constraints, invariants
+
+### State Management
+- Where state lives (local scope / shared application / persistent / server-side)
+- Lifecycle (when it's created, updated, invalidated, destroyed)
+- Synchronization strategy (source of truth, propagation, invalidation)
+
+### Sequence / Flow
+- Key interaction flow across layers or services
+- Include error / retry paths, not just happy path
+
+### Dependency Wiring / Registration
+- How new components are wired in the project's DI / composition / plugin mechanism
+- Lifetimes (singleton vs scoped vs transient) and why
+
+### Navigation / Control Flow Changes
+- For UIs: new/changed routes or screens, transitions, deep links
+- For services: new endpoints, message routes, job schedules
+
+### Non-Functional Design
+- **Performance budget** — latency p50/p95, throughput, memory, bundle/artifact size impact
+- **Reliability** — retry policy, timeouts, fallbacks, circuit breaking, graceful degradation
+- **Security & privacy** — threat model summary, authz decisions, input validation, secrets handling, PII classification
+- **Observability** — logs, metrics, traces, alerts this change adds
+- **Accessibility** (UI work) — compliance target and how it's achieved
+- **Internationalization** (UI work) — locale coverage, RTL, formatting
+- **Compatibility** — minimum supported platforms / runtimes
+- **Offline / resilience** (if applicable) — cached data, queued actions, sync strategy
+
+### Rollout & Reversibility
+- Feature flag(s) and expected flag lifecycle
+- Staged rollout plan (if applicable)
+- Rollback path (flag flip / version rollback / config rollback)
+
+### Implementation Plan
+The design must carry a **complete implementation plan** the Implement phase can execute directly
+— not just a file list:
+- **Ordered tasks / steps** — the sequence to build this in, dependencies first. Each task small
+  and independently reviewable.
+- **Per-file checklist** — for every file, what to add / change / delete (functions, types,
+  wiring), tied to the task(s) above.
+- **Tests to write** — the unit / integration tests to add per the test plan, mapped to the
+  acceptance criteria and the tasks that make them pass.
+
+### File / Module Impact
+- Complete list: new / modified / deleted
+- For each modified file, a one-line reason (this feeds the per-file checklist above)
+
+### Risks & Technical Debt
+- Risks with mitigations
+- Intentional shortcuts and why (and when they'll be paid back)
+
+### Open Questions
+- Questions that should block implementation until answered, and who answers them
+
+## Architecture Rules (Stack-Neutral)
+
+- Layer boundaries are one-way; downstream doesn't know about upstream
+- Every external dependency (DB, HTTP client, file system, clock, random, OS service) sits behind an interface for testability
+- No hidden global state — wire explicitly through the project's composition mechanism
+- Long-lived resources (subscriptions, connections, listeners, background tasks) have explicit disposal paths
+- Breaking changes to external contracts require versioning or migration plans
+
+## Output
+
+Write the completed tech design to `docs/epics/$0/TECH-DESIGN.md`.