gsdd-cli 0.1.0 → 0.2.0

package/bin/lib/models.mjs

@@ -16,7 +16,7 @@ export const DEFAULT_GIT_PROTOCOL = {
 };
 
 export const VALID_MODEL_PROFILES = ['quality', 'balanced', 'budget'];
-export const PORTABLE_AGENT_IDS = ['plan-checker'];
+export const PORTABLE_AGENT_IDS = ['plan-checker', 'approach-explorer'];
 export const MODEL_RUNTIME_IDS = ['claude', 'opencode', 'codex'];
 export const MODEL_ID_PATTERN = /^[a-zA-Z0-9._\/:@-]+$/;
 
@@ -30,7 +30,7 @@ export function buildDefaultConfig({ autoAdvance = false } = {}) {
     parallelization: true,
     commitDocs: true,
     modelProfile: 'balanced',
-    workflow: { research: true, planCheck: true, verifier: true },
+    workflow: { research: true, discuss: false, planCheck: true, verifier: true },
     gitProtocol: { ...DEFAULT_GIT_PROTOCOL },
     initVersion: 'v1.1',
   };
@@ -157,9 +157,11 @@ export function cmdModels(...modelArgs) {
 function cmdModelsShow() {
   const cwd = process.cwd();
   const config = loadProjectModelConfig(cwd);
-  const ocOverride = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+  const ocCheckerOverride = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+  const ocExplorerOverride = getRuntimeModelOverride(config, 'opencode', 'approach-explorer');
   const ocDetected = detectOpenCodeConfiguredModel(cwd);
-  const codexOverride = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+  const codexCheckerOverride = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+  const codexExplorerOverride = getRuntimeModelOverride(config, 'codex', 'approach-explorer');
   output({
     modelProfile: normalizeModelProfile(config.modelProfile),
     agentModelProfiles: config.agentModelProfiles || {},
@@ -172,26 +174,41 @@ function cmdModelsShow() {
           agentId: 'plan-checker',
           profileMap: CLAUDE_MODEL_PROFILES,
         }),
+        'approach-explorer': getRuntimeAgentModelState({
+          config,
+          runtime: 'claude',
+          agentId: 'approach-explorer',
+          profileMap: CLAUDE_MODEL_PROFILES,
+        }),
       },
       opencode: {
         'plan-checker': {
-          mode: ocOverride ? 'override' : 'inherit',
-          model: ocOverride,
+          mode: ocCheckerOverride ? 'override' : 'inherit',
+          model: ocCheckerOverride,
+          runtimeDetectedModel: ocDetected,
+        },
+        'approach-explorer': {
+          mode: ocExplorerOverride ? 'override' : 'inherit',
+          model: ocExplorerOverride,
           runtimeDetectedModel: ocDetected,
         },
       },
       codex: {
         'plan-checker': {
-          mode: codexOverride ? 'override' : 'inherit',
-          model: codexOverride,
+          mode: codexCheckerOverride ? 'override' : 'inherit',
+          model: codexCheckerOverride,
+        },
+        'approach-explorer': {
+          mode: codexExplorerOverride ? 'override' : 'inherit',
+          model: codexExplorerOverride,
         },
       },
     },
     detectedRuntimeModels: {
       opencode: ocDetected,
     },
-    hints: !ocOverride ? {
-      opencode: 'OpenCode currently inherits its runtime model unless you set an explicit override. Use gsdd models set --runtime opencode --agent plan-checker --model <provider/model-id> to inject an explicit checker model.',
+    hints: (!ocCheckerOverride || !ocExplorerOverride) ? {
+      opencode: 'OpenCode currently inherits its runtime model unless you set an explicit override. Use gsdd models set --runtime opencode --agent <agent-id> --model <provider/model-id> to inject an explicit agent model.',
     } : undefined,
   });
 }

package/distilled/DESIGN.md

@@ -9,7 +9,7 @@
 ## Table of Contents
 
 1. [4-File Codebase Standard](#1-4-file-codebase-standard)
-2. [Agent Consolidation: 11 to 9](#2-agent-consolidation-11-to-9)
+2. [Agent Consolidation: 11 to 10](#2-agent-consolidation-11-to-10)
 3. [Two-Layer Architecture: Roles and Delegates](#3-two-layer-architecture-roles-and-delegates)
 4. [Zero-Hop Security Propagation](#4-zero-hop-security-propagation)
 5. [Conditional Synthesizer](#5-conditional-synthesizer)
@@ -36,6 +36,7 @@
 26. [Session Continuity Contract Hardening](#26-session-continuity-contract-hardening)
 27. [Consumer-Ready Surface Completion](#27-consumer-ready-surface-completion)
 28. [Workflow Completion Routing](#28-workflow-completion-routing)
+29. [Approach Exploration](#29-approach-exploration)
 
 ---
 
@@ -64,11 +65,11 @@
 
 ---
 
-## 2. Agent Consolidation: 11 to 9
+## 2. Agent Consolidation: 11 to 10
 
 **GSD:** 11 specialized agent files, each scoped to a single concern.
 
-**GSDD:** 9 canonical roles. 3 mergers and 1 extraction.
+**GSDD:** 10 canonical roles. 2 mergers, 1 extraction, 1 addition (approach-explorer, D29).
 
 **Merger table:**
 
@@ -1001,7 +1002,7 @@ Permission values: ALLOW (role can access), DENY (explicit rejection required),
 
 **GSD:** Orchestrator subagent prompts were embedded inline in workflow files or referenced indirectly through agent role contracts. No explicit thin-wrapper layer. Scope and context were implicit in the orchestrator's prompt shaping.
 
-**GSDD:** Extracted 10 delegates as explicit thin-wrapper files in `distilled/templates/delegates/`. A delegate is a sub-agent instruction wrapper scoped to a specific orchestrator task, carrying a bounded input/output contract. Ten delegates cover 3 canonical roles: mapper × 4 focus-scoped variants, researcher × 4 dimension-scoped variants, synthesizer × 1 (via `researcher-synthesizer.md`), plus one fresh-context adversarial reviewer (`plan-checker.md`, new in D9, no GSD equivalent). Executor, verifier, integration-checker, planner, and roadmapper are invoked directly from orchestrator workflows without thin-wrapper delegates.
+**GSDD:** Extracted 11 delegates as explicit thin-wrapper files in `distilled/templates/delegates/`. A delegate is a sub-agent instruction wrapper scoped to a specific orchestrator task, carrying a bounded input/output contract. Eleven delegates cover 4 canonical roles: mapper × 4 focus-scoped variants, researcher × 4 dimension-scoped variants, synthesizer × 1 (via `researcher-synthesizer.md`), one fresh-context adversarial reviewer (`plan-checker.md`, new in D9, no GSD equivalent), and one interactive approach explorer (`approach-explorer.md`, recovers GSD discuss-phase leverage with research enhancement). Executor, verifier, integration-checker, planner, and roadmapper are invoked directly from orchestrator workflows without thin-wrapper delegates.
 
 **Why "delegates":** In multi-agent orchestration literature (Anthropic multi-agent guidance, OpenAI harness engineering, OpenDev terminal-agents paper arXiv 2603.05344), a delegate is a sub-agent invoked by an orchestrator with:
 1. A single, bounded responsibility (not a general-purpose role)
@@ -1041,7 +1042,7 @@ This is acceptable because:
 2. The clarity gain outweighs the reading cost
 3. Delegate independence enables better testing and quality gates
 
-**10 delegates:**
+**11 delegates:**
 
 | Delegate | Purpose | Wrapped Role |
 |----------|---------|--------------|
@@ -1055,6 +1056,7 @@ This is acceptable because:
 | `researcher-pitfalls.md` | Research domain pitfalls and risks | researcher (dimension: pitfalls) |
 | `researcher-synthesizer.md` | Synthesize research into roadmap implications | synthesizer |
 | `plan-checker.md` | Fresh-context adversarial plan review | planner (adversarial, new in D9) |
+| `approach-explorer.md` | Interactive approach exploration and user alignment | approach-explorer (interactive, recovers GSD discuss-phase) |
 
 **Evidence:**
 
@@ -1124,7 +1126,7 @@ This is acceptable because:
 - G18 guard suite mechanically prevents recurrence: asserts every WORKFLOWS entry appears in `agents.block.md`
 - CHANGELOG and README synced to actual counts (assertions, design decisions, PRs, test suites)
 
-**Why this is high-leverage:** The framework machinery is mechanically sound (800+ assertions, 10 workflows, 9 roles, 3 native adapters, 23 design decisions). But an incomplete AGENTS.md map is functionally broken governance -- agents succeed or fail based on the harness, not the LLM.
+**Why this is high-leverage:** The framework machinery is mechanically sound (800+ assertions, 10 workflows, 10 roles, 3 native adapters, 23 design decisions). But an incomplete AGENTS.md map is functionally broken governance -- agents succeed or fail based on the harness, not the LLM.
 
 **Evidence:**
 
@@ -1139,7 +1141,7 @@ This is acceptable because:
 
 ## 25. Consumer First-Run Experience
 
-**Problem:** GSDD's internal architecture is complete (24 design decisions, 800+ tests, 10 workflows, 9 roles), but consumer-facing surfaces don't honestly guide first-time users. Two independent audits identified this as the single largest barrier to adoption.
+**Problem:** GSDD's internal architecture is complete (24 design decisions, 800+ tests, 10 workflows, 10 roles), but consumer-facing surfaces don't honestly guide first-time users. Two independent audits identified this as the single largest barrier to adoption.
 
 **Decision:** Make all consumer-facing surfaces (README, agents.block.md, post-init CLI output) honestly distinguish between native-capable and governance-only platforms, and provide platform-specific invocation guidance at every consumer touchpoint.
 
@@ -1275,6 +1277,77 @@ GSDD's `<completion>` pattern is vendor-agnostic (GSD's `/clear` is Claude-speci
 
 ---
 
+## 29. Approach Exploration
+
+**GSD baseline:** Three separate workflows handle pre-planning user alignment:
+
+| GSD workflow | Purpose | Output |
+|---|---|---|
+| `discuss-phase.md` (541 lines) | Gray area identification, 4-question batched loops per area, deferred ideas capture | `CONTEXT.md` |
+| `list-phase-assumptions.md` (179 lines) | 5-dimension assumption surfacing (technical approach, implementation order, scope boundaries, risks, dependencies) | Conversational only (no file output) |
+| `discovery-phase.md` | 3-level research (Quick/Standard/Deep) with domain exploration | `DISCOVERY.md` |
+
+Combined, these three workflows provided genuine leverage: the planner could not silently converge on a single approach without user input. GSD's initial GSDD distillation dropped all three, removing this alignment step entirely. The planner was left to infer approaches without user validation.
+
+**Problem:** Without approach exploration, the planner explores no alternatives, surfaces no assumptions, and captures no user decisions. The user's first chance to disagree with approach choices is after implementation — too late for efficient correction.
+
+**GSDD decision:** Recover the discuss-phase leverage as a single role (`agents/approach-explorer.md`) embedded in the plan workflow, with a hybrid interaction architecture:
+
+1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed ~1000-token structured summary. Only summaries enter the conversation context, not raw file reads.
+
+2. **Native agent optimization:** Runtimes with interactive subagent support (Claude Code with `AskUserQuestion`, Codex interactive agents, OpenCode `mode: agent`) can run the full exploration as a native agent. Falls back to the inline primary path if unavailable.
+
+Both paths produce identical output: `{padded_phase}-APPROACH.md` in the phase directory.
+
+**Key enhancements over GSD:**
+
+| Enhancement | GSD pattern | GSDD pattern | Why |
+|---|---|---|---|
+| Gray area classification | All areas treated identically | Taste / technical / hybrid classification | Taste decisions need no research; technical ones do. Asking "what color?" the same way as "JWT vs sessions?" wastes context and user time |
+| Questioning style | Rigid 4-question batched loop | Adaptive convergence (2-6 questions depending on complexity) | Fixed batch sizes don't match decision complexity. Some areas resolve in 2 questions, others need 6 |
+| Pre-question research | No research before asking | Research subagent per technical area returns structured summary before asking | Users make better decisions when presented with researched options and trade-offs |
+| Quality gate | None | Self-check before writing APPROACH.md (concrete decisions, no vague language, source backing, scope compliance) | Prevents weak outputs that force re-asking during planning |
+| Intermediate persistence | No persistence until final output | Confirmed decisions written to disk incrementally | Protects against context limits in long conversations |
+| Context loading | "Read everything" | JIT extraction guidance (e.g., "From SPEC.md read ONLY locked decisions") | Prevents context pollution with irrelevant content |
+| Plan-checker integration | None | New `approach_alignment` dimension in plan-checker | Verifies plans honor approach decisions, not just requirements |
+| Delegation option | Not available | "Agent's Discretion" — user can explicitly delegate choices to the agent | Reduces user fatigue on areas where they have no strong preference |
+
+**Role contract design:** Ground-up rewrite applying prompt engineering best practices:
+
+- XML semantic structure (`<role>`, `<algorithm>`, `<examples>`, `<anti_patterns>`, `<quality_guarantees>`) matching the planner role pattern
+- 3 few-shot conversation examples (taste decision, technical decision with research, hybrid with delegation)
+- Vendor-neutral throughout — no tool-specific references in the role contract
+- Anti-patterns placed early for high attention weight
+
+**Architecture rationale — why hybrid:**
+
+The approach explorer needs two capabilities with opposite context requirements:
+- **Conversation** needs the main context (for user interaction)
+- **Research** generates thousands of tokens of raw content the conversation doesn't need
+
+Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`<research_subagent_prompt>` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: ~1000 tokens orchestration + ~4000 tokens research summaries (4 areas × ~1000) + ~4000 tokens conversation + ~500 tokens APPROACH.md = ~9500 tokens. The 1000-token budget (matching Anthropic CE's recommended floor) gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent.
+
+**Evidence:**
+
+1. Anthropic "Building effective agents" (2025): sub-agents perform deep technical work, returning condensed summaries to the orchestrator — "find the smallest set of high-signal tokens"
+2. Anthropic prompting best practices (2025): XML tags for semantic structure, role preamble, few-shot examples, adaptive thinking
+3. LangChain "Context Engineering for Agents" (2025): Write/Select/Compress/Isolate patterns — "isolate: split context across separate processes", "compress: summarize at agent-agent boundaries"
+4. Agent Skills specification (agentskills.io): progressive disclosure, SKILL.md format with metadata-first structure
+5. OpenAI meta-prompting (2025): LLM-as-judge evaluation, specification-based output quality verification
+6. GSD source: `get-shit-done/workflows/discuss-phase.md` (gray area identification, AskUserQuestion interaction, deferred ideas)
+7. GSD source: `get-shit-done/workflows/list-phase-assumptions.md` (5-dimension assumption surfacing with confidence levels)
+8. GSD source: `get-shit-done/workflows/discovery-phase.md` (3-level research workflow)
+
+**Trade-offs:**
+
+- Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; context stays lean via research isolation
+- Cost: adds one interactive step before planning (~5-15 minutes of user time per phase); hybrid architecture is more complex than a single monolithic workflow
+- Mitigation: `workflow.discuss: true|false` toggle in `.planning/config.json` allows skipping with explicit `reduced_alignment` reporting; taste areas skip research entirely. Default is `false` (opt-in) to stay consistent with GSDD's stripped-down identity; users enable it explicitly
+
+**GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`<approach_exploration>` section), `agents/planner.md` (`<approach_decisions>` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering)
+
+---
+
 ## Maintenance
 
 This document is updated when:

package/distilled/README.md

@@ -1,169 +1,169 @@
-# 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
+```
+
+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 (29 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