gsdd-cli 0.1.0 → 0.3.1

package/distilled/README.md

@@ -1,169 +1,173 @@
-# GSDD (Get Shit Done Distilled)
-
-Lightweight Spec-Driven Development (SDD) for AI-assisted engineering.
-
-Distilled from GSD (Get Shit Done): keep rigor and leverage, drop ceremony.
-
-## What This Is
-
-GSDD is a small set of workflow sources plus a CLI (`gsdd`) that:
-- scaffolds a project planning workspace (`.planning/`)
-- generates portable workflow entrypoints as skills (`.agents/skills/gsdd-*/SKILL.md`)
-- optionally generates tool-specific adapters for runtimes that need extra native surfaces (root `AGENTS.md`, Claude skills + plan-command alias + native agents, OpenCode commands + native agents)
-
-## Quick Start
-
-Run in your project root:
-```bash
-npx gsdd-cli init
-```
-
-Optional adapters:
-```bash
-npx gsdd-cli init --tools claude
-npx gsdd-cli init --tools opencode
-npx gsdd-cli init --tools codex
-npx gsdd-cli init --tools agents
-npx gsdd-cli init --tools all
-```
-
-Notes:
-- `gsdd init` always generates open-standard skills at `.agents/skills/gsdd-*`. This is also the primary Codex CLI surface.
-- `--tools claude` also generates native agents at `.claude/agents/gsdd-*.md` and a compatibility plan command alias at `.claude/commands/gsdd-plan.md`.
-- `--tools opencode` also generates native agents at `.opencode/agents/gsdd-*.md`.
-- `--tools codex` generates `.codex/agents/gsdd-plan-checker.toml`; the portable `.agents/skills/gsdd-plan/` surface remains the Codex entry path.
-- Root `AGENTS.md` is only written when explicitly requested (`--tools agents` or `--tools all`).
-
-## The Workflow
-
-```
-gsdd init           -> bootstrap (create .planning/, copy templates, generate skills/adapters)
-/gsdd:new-project   -> .planning/SPEC.md + .planning/ROADMAP.md  (questioning + codebase audit + research)
-/gsdd:plan N        -> phases/N/PLAN.md      (task breakdown + research)
-/gsdd:execute N     -> code changes          (plan execution with quality gates)
-/gsdd:verify N      -> VERIFICATION.md       (goal-backward validation)
-  ... repeat plan/execute/verify per phase ...
-/gsdd:quick         -> .planning/quick/NNN/  (sub-hour task outside phases)
-/gsdd:pause         -> .planning/.continue-here.md  (session checkpoint)
-/gsdd:resume        -> restore context, route to next action
-/gsdd:progress      -> show status, route to next action
-```
-
-## Current Status (updated 2026-03-20)
-
-| Workflow | Status | Notes |
-|----------|--------|-------|
-| `new-project.md` | [OK] Defined, source-audited | Covers greenfield + brownfield + milestone context |
-| `plan.md` | [OK] Defined, source-audited | Portable workflow defines the planner contract and supports independent plan checking through generated native adapters |
-| `execute.md` | [OK] Source-audited | Mandatory read enforcement, auth-gate routing, deviation-rule examples, and substantive summary quality gate |
-| `verify.md` | [OK] Source-audited | 5 gap closures against hardened verifier role contract: grouped-gap guidance, orphan detection, frontmatter enforcement, verification basis emphasis, requirements coverage chain |
-| `audit-milestone.md` | [OK] Defined, source-audited | Aggregates phase verification, cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
-| `quick.md` | [OK] | Quick-work lane for sub-hour tasks outside the phase cycle (D11) |
-| `pause.md` | [OK] Source-audited | Session checkpoint writer with conversational handoff (D12) |
-| `resume.md` | [OK] Source-audited | Session context restorer with priority-ordered routing (D12) |
-| `progress.md` | [OK] Source-audited | Read-only status reporter with 6 named route branches, recent work, between-milestones detection (D12) |
-| `map-codebase.md` | [OK] Defined, source-audited | Standalone codebase mapping/refresh |
-
-Architecture notes:
-- `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
-- Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
-- Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.
-- Phase verification and milestone integration audit are treated as separate concerns.
-- Canonical role contracts use bounded sections, typed output examples, and checklist-driven completion where those structures materially improve downstream reliability.
-
-## Init Workflow Agent Count (by config)
-
-| Mode | Mappers | Researchers | Synthesizer | Total |
-|------|---------|-------------|-------------|-------|
-| Brownfield, first run, research balanced/deep | 4 | 4 | 1 | 9 |
-| Brownfield, first run, research fast | 4 | 4 | 0 (inline) | 8 |
-| Brownfield, subsequent run, research balanced/deep | 0 (maps exist) | 4 | 1 | 5 |
-| Greenfield, research balanced/deep | 0 | 4 | 1 | 5 |
-| Greenfield, research fast | 0 | 4 | 0 (inline) | 4 |
-| Any, no research | 0-4 | 0 | 0 | 0-4 |
-
-Note: `parallelization: false` keeps the same mapper/researcher set but runs them sequentially.
-
-## What Gets Created (Project Output)
-
-```
-.planning/
-  SPEC.md
-  ROADMAP.md
-  config.json
-  templates/           # copied from distilled/templates/
-  phases/              # phase plans and summaries
-  research/            # optional research outputs
-.agents/skills/
-  gsdd-new-project/SKILL.md
-  gsdd-plan/SKILL.md
-  gsdd-execute/SKILL.md
-  gsdd-verify/SKILL.md
-  gsdd-audit-milestone/SKILL.md
-  gsdd-quick/SKILL.md
-  gsdd-pause/SKILL.md
-  gsdd-resume/SKILL.md
-  gsdd-progress/SKILL.md
-  gsdd-map-codebase/SKILL.md
-.claude/agents/
-  gsdd-plan-checker.md      # native-capable checker agent generated from the active plan-checker contract
-.claude/commands/
-  gsdd-plan.md              # compatibility alias to the Claude skill-primary plan entry
-.claude/skills/
-  gsdd-plan/SKILL.md        # Claude-native skill-primary planner -> checker surface
-.opencode/agents/
-  gsdd-plan-checker.md      # native-capable checker agent generated from the active plan-checker contract
-.opencode/commands/
-  gsdd-plan.md              # OpenCode-native specialized planner -> checker command surface
-.codex/agents/
-  gsdd-plan-checker.toml    # Codex-native checker agent (read-only, high reasoning effort)
-.planning/
-  quick/              # quick task directories and LOG.md
-  .continue-here.md   # session checkpoint (created by pause)
-```
-
-## Files In This Framework
-
-```
-distilled/
-  DESIGN.md                # design decisions and rationale (28 decisions, evidence-backed)
-  SKILL.md                 # primary entry point (plain markdown)
-  workflows/
-    new-project.md
-    map-codebase.md
-    plan.md
-    progress.md
-    execute.md
-    verify.md
-    audit-milestone.md
-    quick.md
-    pause.md
-    resume.md
-  templates/
-    spec.md
-    roadmap.md
-    agents.md              # full AGENTS.md template (for tool adapters)
-    agents.block.md        # bounded block payload for root AGENTS.md insertion
-    delegates/               # delegate instruction files (copied to .planning/templates/delegates/)
-      mapper-tech.md
-      mapper-arch.md
-      mapper-quality.md
-      mapper-concerns.md
-      plan-checker.md
-      researcher-stack.md
-      researcher-features.md
-      researcher-architecture.md
-      researcher-pitfalls.md
-      researcher-synthesizer.md
-    research/
-      stack.md
-      features.md
-      architecture.md
-      pitfalls.md
-      summary.md
-    codebase/
-      stack.md
-      architecture.md
-      conventions.md
-      concerns.md
-```
+# GSDD (Get Shit Done Distilled)
+
+Lightweight Spec-Driven Development (SDD) for AI-assisted engineering.
+
+Distilled from GSD (Get Shit Done): keep rigor and leverage, drop ceremony.
+
+## What This Is
+
+GSDD is a small set of workflow sources plus a CLI (`gsdd`) that:
+- scaffolds a project planning workspace (`.planning/`)
+- generates portable workflow entrypoints as skills (`.agents/skills/gsdd-*/SKILL.md`)
+- optionally generates tool-specific adapters for runtimes that need extra native surfaces (root `AGENTS.md`, Claude skills + plan-command alias + native agents, OpenCode commands + native agents)
+
+## Quick Start
+
+Run in your project root:
+```bash
+npx gsdd-cli init
+```
+
+In a TTY, `gsdd init` now opens a guided install wizard: choose runtimes first, then decide separately whether repo-wide `AGENTS.md` governance is worth installing.
+
+Optional adapters:
+```bash
+npx gsdd-cli init --tools claude
+npx gsdd-cli init --tools opencode
+npx gsdd-cli init --tools codex
+npx gsdd-cli init --tools agents
+npx gsdd-cli init --tools cursor
+npx gsdd-cli init --tools all
+```
+
+Notes:
+- `gsdd init` always generates open-standard skills at `.agents/skills/gsdd-*`. This is also the primary Codex CLI surface.
+- `--tools ...` remains the manual/headless path; legacy runtime aliases such as `cursor`, `copilot`, and `gemini` are still supported for backward compatibility.
+- `--tools claude` also generates native agents at `.claude/agents/gsdd-*.md` and a compatibility plan command alias at `.claude/commands/gsdd-plan.md`.
+- `--tools opencode` also generates native agents at `.opencode/agents/gsdd-*.md`.
+- `--tools codex` generates `.codex/agents/gsdd-plan-checker.toml`; the portable `.agents/skills/gsdd-plan/` surface remains the Codex entry path.
+- Root `AGENTS.md` is only written when explicitly requested (`--tools agents`, `--tools all`, legacy runtime aliases, or the wizard governance opt-in).
+
+## The Workflow
+
+```
+gsdd init           -> bootstrap (create .planning/, copy templates, generate skills/adapters)
+/gsdd:new-project   -> .planning/SPEC.md + .planning/ROADMAP.md  (questioning + codebase audit + research)
+/gsdd:plan N        -> phases/N/PLAN.md      (task breakdown + research)
+/gsdd:execute N     -> code changes          (plan execution with quality gates)
+/gsdd:verify N      -> VERIFICATION.md       (goal-backward validation)
+  ... repeat plan/execute/verify per phase ...
+/gsdd:quick         -> .planning/quick/NNN/  (sub-hour task outside phases)
+/gsdd:pause         -> .planning/.continue-here.md  (session checkpoint)
+/gsdd:resume        -> restore context, route to next action
+/gsdd:progress      -> show status, route to next action
+```
+
+## Current Status (updated 2026-03-20)
+
+| Workflow | Status | Notes |
+|----------|--------|-------|
+| `new-project.md` | [OK] Defined, source-audited | Covers greenfield + brownfield + milestone context |
+| `plan.md` | [OK] Defined, source-audited | Portable workflow defines the planner contract and supports independent plan checking through generated native adapters |
+| `execute.md` | [OK] Source-audited | Mandatory read enforcement, auth-gate routing, deviation-rule examples, and substantive summary quality gate |
+| `verify.md` | [OK] Source-audited | 5 gap closures against hardened verifier role contract: grouped-gap guidance, orphan detection, frontmatter enforcement, verification basis emphasis, requirements coverage chain |
+| `audit-milestone.md` | [OK] Defined, source-audited | Aggregates phase verification, cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
+| `quick.md` | [OK] | Quick-work lane for sub-hour tasks outside the phase cycle (D11) |
+| `pause.md` | [OK] Source-audited | Session checkpoint writer with conversational handoff (D12) |
+| `resume.md` | [OK] Source-audited | Session context restorer with priority-ordered routing (D12) |
+| `progress.md` | [OK] Source-audited | Read-only status reporter with 6 named route branches, recent work, between-milestones detection (D12) |
+| `map-codebase.md` | [OK] Defined, source-audited | Standalone codebase mapping/refresh |
+
+Architecture notes:
+- `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
+- Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
+- Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.
+- Phase verification and milestone integration audit are treated as separate concerns.
+- Canonical role contracts use bounded sections, typed output examples, and checklist-driven completion where those structures materially improve downstream reliability.
+
+## Init Workflow Agent Count (by config)
+
+| Mode | Mappers | Researchers | Synthesizer | Total |
+|------|---------|-------------|-------------|-------|
+| Brownfield, first run, research balanced/deep | 4 | 4 | 1 | 9 |
+| Brownfield, first run, research fast | 4 | 4 | 0 (inline) | 8 |
+| Brownfield, subsequent run, research balanced/deep | 0 (maps exist) | 4 | 1 | 5 |
+| Greenfield, research balanced/deep | 0 | 4 | 1 | 5 |
+| Greenfield, research fast | 0 | 4 | 0 (inline) | 4 |
+| Any, no research | 0-4 | 0 | 0 | 0-4 |
+
+Note: `parallelization: false` keeps the same mapper/researcher set but runs them sequentially.
+
+## What Gets Created (Project Output)
+
+```
+.planning/
+  SPEC.md
+  ROADMAP.md
+  config.json
+  templates/           # copied from distilled/templates/
+  phases/              # phase plans and summaries
+  research/            # optional research outputs
+.agents/skills/
+  gsdd-new-project/SKILL.md
+  gsdd-plan/SKILL.md
+  gsdd-execute/SKILL.md
+  gsdd-verify/SKILL.md
+  gsdd-audit-milestone/SKILL.md
+  gsdd-quick/SKILL.md
+  gsdd-pause/SKILL.md
+  gsdd-resume/SKILL.md
+  gsdd-progress/SKILL.md
+  gsdd-map-codebase/SKILL.md
+.claude/agents/
+  gsdd-plan-checker.md      # native-capable checker agent generated from the active plan-checker contract
+.claude/commands/
+  gsdd-plan.md              # compatibility alias to the Claude skill-primary plan entry
+.claude/skills/
+  gsdd-plan/SKILL.md        # Claude-native skill-primary planner -> checker surface
+.opencode/agents/
+  gsdd-plan-checker.md      # native-capable checker agent generated from the active plan-checker contract
+.opencode/commands/
+  gsdd-plan.md              # OpenCode-native specialized planner -> checker command surface
+.codex/agents/
+  gsdd-plan-checker.toml    # Codex-native checker agent (read-only, high reasoning effort)
+.planning/
+  quick/              # quick task directories and LOG.md
+  .continue-here.md   # session checkpoint (created by pause)
+```
+
+## Files In This Framework
+
+```
+distilled/
+  DESIGN.md                # design decisions and rationale (36 decisions, evidence-backed)
+  SKILL.md                 # primary entry point (plain markdown)
+  workflows/
+    new-project.md
+    map-codebase.md
+    plan.md
+    progress.md
+    execute.md
+    verify.md
+    audit-milestone.md
+    quick.md
+    pause.md
+    resume.md
+  templates/
+    spec.md
+    roadmap.md
+    agents.md              # full AGENTS.md template (for tool adapters)
+    agents.block.md        # bounded block payload for root AGENTS.md insertion
+    delegates/               # delegate instruction files (copied to .planning/templates/delegates/)
+      mapper-tech.md
+      mapper-arch.md
+      mapper-quality.md
+      mapper-concerns.md
+      plan-checker.md
+      researcher-stack.md
+      researcher-features.md
+      researcher-architecture.md
+      researcher-pitfalls.md
+      researcher-synthesizer.md
+    research/
+      stack.md
+      features.md
+      architecture.md
+      pitfalls.md
+      summary.md
+    codebase/
+      stack.md
+      architecture.md
+      conventions.md
+      concerns.md
+```

package/distilled/templates/agents.block.md

@@ -6,7 +6,7 @@ Edit the source template in the GSDD framework instead.
 ### What This Project Uses
 - Framework: GSDD (Spec-Driven Development)
 - Planning dir: `.planning/` (specs, roadmaps, plans, research, templates)
-- Lifecycle: `bootstrap (gsdd init) -> new-project -> [plan -> execute -> verify] x N -> audit-milestone` for roadmap work
+- Lifecycle: `bootstrap (gsdd init) -> new-project -> [discuss-approach -> plan -> execute -> verify] x N -> audit-milestone` for roadmap work
 - Supporting workflows: quick (sub-hour tasks), map-codebase (codebase analysis), pause/resume (session management), progress (status query)
 
 ### Rules You MUST Follow
@@ -83,8 +83,10 @@ If you are not confident about a domain/library/pattern:
 
 How you run these workflows depends on your tool:
 
-- **Claude Code / OpenCode:** Use slash commands — `/gsdd-new-project`, `/gsdd-plan`, `/gsdd-execute`, etc.
+- **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands — `/gsdd-new-project`, `/gsdd-plan`, `/gsdd-execute`, etc.
 - **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, `$gsdd-execute`, etc.
-- **All other tools (Cursor, Copilot, Gemini, any AI agent):** Open the SKILL.md file listed above and follow its instructions. This AGENTS.md governance block keeps the agent aligned with GSDD discipline.
+- **Other AI tools:** Open the SKILL.md file listed above and follow its instructions.
+
+If this root `AGENTS.md` block is present in a Cursor, Copilot, or Gemini project, treat it as behavioral governance on top of the runtime's native slash-command discovery. Do not treat this file as the mechanism that makes the workflows discoverable.
 
 Start with the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.

package/distilled/templates/approach.md

@@ -0,0 +1,232 @@
+# Phase Approach Template
+
+Template for `.planning/phases/XX-name/{phase_num}-APPROACH.md` — captures implementation decisions and validated assumptions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Planner uses this to know WHAT choices are locked vs flexible. Plan-checker verifies plans honor these decisions.
+
+**Key principle:** The top-level structure (`<domain>`, `<decisions>`, `<assumptions>`, `<deferred>`) is fixed. Section names WITHIN `<decisions>` emerge from what was actually discussed for THIS phase — a CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `planner` — Reads decisions to constrain implementation choices. Locked decisions must be implemented. Agent's Discretion items allow planner flexibility.
+- `plan-checker` — Reads decisions to verify plans implement chosen approaches (approach_alignment dimension). Flags plans that contradict explicit user choices.
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] - Approach
+
+**Explored:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Gray Area 1 that was discussed]
+**Chosen approach:** [name]
+**Alternatives considered:** [Option B], [Option C]
+**Why this one:** [reasoning from research + user preference]
+- [Specific decision from questioning]
+- [Another decision if applicable]
+
+### [Gray Area 2 that was discussed]
+**Chosen approach:** [name]
+**Alternatives considered:** [Option B]
+**Why this one:** [reasoning]
+- [Specific decision]
+
+### Agent's Discretion
+[Areas where user explicitly said "you decide" — the agent has flexibility here during planning/implementation]
+
+</decisions>
+
+<assumptions>
+## Validated Assumptions
+
+### Confirmed
+- [confident] [assumption confirmed by user]
+
+### Accepted (not challenged)
+- [assuming] [assumption user didn't challenge — planner should still honor but note it]
+
+### Corrected
+- [corrected] [original assumption] → [user's correction]
+
+</assumptions>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Approach explored: [date]*
+```
+
+## Good Examples
+
+**Example 1: Visual feature (Dashboard)**
+
+```markdown
+# Phase 3: Interactive Dashboard - Approach
+
+**Explored:** 2026-03-22
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Build an interactive dashboard with configurable widgets. Users can view metrics and rearrange layout. Widget creation and custom data sources are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Chart rendering
+**Chosen approach:** Recharts
+**Alternatives considered:** D3 + custom components, Chart.js
+**Why this one:** React-native, SSR-friendly, good defaults. Matches existing React patterns. D3 would give more control but requires more code for standard charts.
+- Bar charts and line charts for metrics — no pie charts in v1
+- Charts should be interactive (hover tooltips) but not editable
+- Responsive: charts resize with widget container
+
+### Widget layout
+**Chosen approach:** react-grid-layout
+**Alternatives considered:** CSS Grid + custom drag, @dnd-kit grid
+**Why this one:** Purpose-built for dashboard grids. Layout serialization to JSON for persistence. Mature production usage.
+- Drag-to-reorder enabled
+- Resize handles on bottom-right corner
+- 12-column grid, responsive breakpoints
+- Layout persisted to localStorage (not server)
+
+### Agent's Discretion
+- Loading skeleton design
+- Exact spacing and typography within widgets
+- Error state handling for failed data fetches
+
+</decisions>
+
+<assumptions>
+## Validated Assumptions
+
+### Confirmed
+- [confident] Using existing Tailwind patterns from Phase 1-2
+
+### Accepted (not challenged)
+- [assuming] Dashboard data comes from static JSON for v1 (no real API)
+
+### Corrected
+- [corrected] Dashboard is read-only → Widgets DO need drag reorder
+
+</assumptions>
+
+<deferred>
+## Deferred Ideas
+
+- Real-time data updates — future phase
+- Custom widget creation — add to backlog
+- Dashboard sharing/export — out of scope for v1
+
+</deferred>
+
+---
+
+*Phase: 03-dashboard*
+*Approach explored: 2026-03-22*
+```
+
+**Example 2: API feature (Authentication)**
+
+```markdown
+# Phase 1: Authentication - Approach
+
+**Explored:** 2026-03-22
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can register and log in with email/password. Session management via JWT. OAuth and MFA are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Session handling
+**Chosen approach:** HTTP-only cookies with JWT
+**Alternatives considered:** localStorage JWT, session-based (server-side)
+**Why this one:** HTTP-only cookies prevent XSS token theft. JWT avoids server-side session storage. Standard pattern for Next.js apps.
+- Access token: 15-minute expiry
+- Refresh token: 7-day expiry, rotation on use
+- Logout clears both tokens
+
+### Error responses
+**Chosen approach:** Structured JSON errors
+**Alternatives considered:** Plain text errors, RFC 7807 Problem Details
+**Why this one:** Consistent with existing API patterns. RFC 7807 is overkill for this project size.
+- Always include: status code, error code, user-facing message
+- Never include: stack traces, internal IDs
+- Rate limit errors: include retry-after header
+
+### Agent's Discretion
+- Password hashing library (bcrypt vs argon2)
+- Exact JWT payload structure
+- Email validation regex vs library
+
+</decisions>
+
+<assumptions>
+## Validated Assumptions
+
+### Confirmed
+- [confident] Email/password only for v1 (no OAuth)
+
+### Accepted (not challenged)
+- [assuming] No email verification required for v1
+
+### Corrected
+- [corrected] Single-device sessions → Allow multi-device (don't invalidate other sessions on login)
+
+</assumptions>
+
+<deferred>
+## Deferred Ideas
+
+- OAuth providers (Google, GitHub) — Phase 4
+- MFA/2FA — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 01-authentication*
+*Approach explored: 2026-03-22*
+```
+
+## Guidelines
+
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What choices are locked for the planner? Where does the planner have discretion?"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-APPROACH.md`
+- Planner reads decisions to constrain implementation tasks
+- Plan-checker verifies approach_alignment: plans must implement chosen approaches
+- Downstream agents should NOT need to ask the user again about captured decisions

package/distilled/templates/delegates/approach-explorer.md

@@ -0,0 +1,25 @@
+**Role contract:** Read `.planning/templates/roles/approach-explorer.md` before starting. Follow its algorithm, scope, anti-patterns, and quality standards.
+
+You are the approach explorer delegate for the plan workflow.
+
+**Your job:** Identify gray areas in the target phase, research viable approaches for technical decisions, conduct an adaptive conversation with the user to capture locked decisions, and write APPROACH.md to the phase directory.
+
+Read only the explicit inputs provided by the orchestrator:
+- target phase goal and requirement IDs from `.planning/ROADMAP.md`
+- locked decisions and deferred items from `.planning/SPEC.md`
+- phase research file (if exists)
+- relevant codebase files (existing patterns and conventions)
+- approach template at `.planning/templates/approach.md`
+
+## Gray Area Classification
+
+Classify each gray area before acting on it:
+- **Taste:** Ask directly, no research needed
+- **Technical:** Research 2-3 approaches first, then present with trade-offs
+- **Hybrid:** Research the technical part, ask about taste
+
+## Output
+
+Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template.
+
+Return structured summary: gray areas explored, decisions captured, assumptions validated/corrected, deferred ideas, path to APPROACH.md.