gsdd-cli 0.1.0 → 0.3.1

package/README.md

@@ -32,7 +32,7 @@ GSDD is a distilled fork of GSD. It preserves the high-leverage parts of long-ho
 - **Milestone audit** — cross-phase integration, requirements coverage, E2E flows
 - **Session management** — pause work with checkpoint, resume with context restoration and routing
 
-What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). GSDD has 10 workflows and 9 roles.
+What it strips: GSD's broader operator surface (32 workflows, 11 agents, discovery modes, sprint ceremony, a settings flow, and additional operator ergonomics). GSDD has 10 workflows and 10 roles.
 
 **Target user:** Developer or small team that wants a spec-driven long-horizon kernel, not full operator comfort.
 
@@ -48,17 +48,27 @@ This creates:
 
 1. `.planning/` — durable workspace with templates, role contracts, and config
 2. `.agents/skills/gsdd-*` — portable workflow entrypoints
-3. Tool-specific adapters if detected (Claude skills/commands/agents, OpenCode commands/agents, Codex agents)
+3. Tool-specific adapters you choose in the install wizard (Claude skills/commands/agents, OpenCode commands/agents, Codex agents, optional governance)
 
 Then run the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.
 
+In a terminal, `gsdd init` now opens a guided install wizard:
+
+- Step 1: select the runtimes/vendors you want to support
+- Step 2: decide separately whether repo-wide `AGENTS.md` governance is worth installing
+- Step 3: configure planning defaults in the same guided flow
+
+Portable `.agents/skills/gsdd-*` skills are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline.
+
 ### Quickstart (after init)
 
 Your tool determines how you invoke workflows:
 
-- **Claude Code / OpenCode:** Use slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
+- **Claude Code / OpenCode / Cursor / Copilot / Gemini:** Use slash commands directly — `/gsdd-new-project`, `/gsdd-plan`, etc.
 - **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, etc.
-- **Cursor / Copilot / Gemini / Others:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions. The root `AGENTS.md` governance block keeps the agent on track.
+- **Other AI tools:** Open `.agents/skills/gsdd-<workflow>/SKILL.md` and follow the instructions.
+
+If you generate the root `AGENTS.md` block, it adds GSDD behavioral governance. For Cursor, Copilot, and Gemini, that governance is optional discipline on top of native skill discovery — not the mechanism that makes workflows discoverable.
 
 First workflow to run: **new-project** — it asks about your goals, audits the codebase (if brownfield), and produces `.planning/SPEC.md` + `.planning/ROADMAP.md`.
 
@@ -67,11 +77,12 @@ First workflow to run: **new-project** — it asks about your goals, audits the
 GSDD generates adapters for whichever tools you use:
 
 ```bash
-npx gsdd-cli init                    # Auto-detect installed tools
+npx gsdd-cli init                    # Guided install wizard (detected runtimes preselected)
 npx gsdd-cli init --tools claude     # Claude Code: .claude/skills + commands + agents
 npx gsdd-cli init --tools opencode   # OpenCode: .opencode/commands + agents
 npx gsdd-cli init --tools codex      # Codex CLI: portable gsdd-plan skill + .codex/agents checker
 npx gsdd-cli init --tools agents     # Root AGENTS.md fallback
+npx gsdd-cli init --tools cursor     # Backward-compatible AGENTS.md governance alias
 npx gsdd-cli init --tools all        # All of the above
 ```
 
@@ -81,7 +92,8 @@ npx gsdd-cli init --tools all        # All of the above
 | **Claude Code** | Native | `.claude/skills/`, `.claude/commands/`, `.claude/agents/` — slash commands work immediately |
 | **OpenCode** | Native | `.opencode/commands/`, `.opencode/agents/` — slash commands work immediately |
 | **Codex CLI** | Native | `.codex/agents/gsdd-plan-checker.toml` — skill reference `$gsdd-plan` works immediately |
-| **Cursor / Copilot / Gemini** | Governance | Root `AGENTS.md` block — governs agent behavior; invoke workflows by opening `.agents/skills/gsdd-*/SKILL.md` directly |
+| **Cursor / Copilot / Gemini** | Skills-native runtime + optional governance | Native slash-command discovery from `.agents/skills/`; optional root `AGENTS.md` block adds behavioral governance |
+| **Other AI tools** | Open standard fallback | Open `.agents/skills/gsdd-*/SKILL.md` directly |
 
 ### Updating
 
@@ -102,10 +114,13 @@ npx gsdd-cli init --auto --tools claude --brief path/to/PRD.md
 
 `--auto` skips interactive prompts, uses smart defaults (`autoAdvance: true` in config). `--brief` copies a project document to `.planning/PROJECT_BRIEF.md` for `new-project` to consume.
 
+If you already know exactly what to generate, `--tools ...` remains the manual path. The wizard is the primary onboarding UX; flags remain the advanced/headless contract.
+
 ### Team Use
 
 - **Shared state:** Set `commitDocs: true` (default) — `.planning/` is tracked in git. Everyone sees the same spec, roadmap, and phase plans.
 - **Onboarding:** After cloning, run `npx gsdd-cli init` to generate tool-specific adapters. `.planning/` is already tracked — no re-initialization needed.
+- **Governance is explicit:** The wizard asks separately whether to install repo-wide `AGENTS.md` rules, and explains why you may care before writing to the repo root.
 - **Session handoff:** Use `gsdd-pause` / `gsdd-resume` to hand off work. The checkpoint (`.planning/.continue-here.md`) captures context for the next person.
 - **Adapter isolation:** Each developer runs `gsdd init --tools <their-tool>`. Adapter files don't conflict across tools.
 
@@ -192,7 +207,8 @@ When all phases are done, run `gsdd-audit-milestone` to verify:
 
 - `Claude Code / OpenCode`: `/gsdd-quick`
 - `Codex CLI`: `$gsdd-quick`
-- `Cursor / Copilot / Gemini / Others`: open `.agents/skills/gsdd-quick/SKILL.md`
+- `Cursor / Copilot / Gemini`: `/gsdd-quick`
+- `Other AI tools`: open `.agents/skills/gsdd-quick/SKILL.md`
 
 For sub-hour tasks that don't need the full phase cycle:
 
@@ -231,7 +247,8 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | Claude Code | `/gsdd-plan` (slash command, works immediately after init) |
 | OpenCode | `/gsdd-plan` (slash command, works immediately after init) |
 | Codex CLI | `$gsdd-plan` (skill reference, works immediately after init) |
-| Cursor / Copilot / Gemini | Open `.agents/skills/gsdd-plan/SKILL.md` and paste or reference its content. The `AGENTS.md` governance block steers agent behavior. |
+| Cursor / Copilot / Gemini | `/gsdd-plan` (skills-native slash command). If the root `AGENTS.md` block is present, it adds governance, not workflow discovery. |
+| Other AI tools | Open `.agents/skills/gsdd-plan/SKILL.md` and paste or reference its content. |
 
 ## CLI Commands
 
@@ -250,9 +267,9 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 
 ## Architecture
 
-### Roles (9 canonical)
+### Roles (10 canonical)
 
-GSDD consolidates GSD's agent surface into 9 roles with durable contracts:
+GSDD consolidates GSD's agent surface into 10 roles with durable contracts:
 
 | Role | Responsibility |
 |------|---------------|
@@ -271,7 +288,7 @@ GSDD consolidates GSD's agent surface into 9 roles with durable contracts:
 - **Role contracts** (`agents/*.md`) — durable, contain the full behavioral specification
 - **Delegates** (`distilled/templates/delegates/*.md`) — thin wrappers that reference roles and provide task-specific context
 
-10 delegates: 4 mapper, 4 researcher, 1 synthesizer, 1 plan-checker. Workflows use `<delegate>` blocks to dispatch work. For detailed GSD-to-GSDD role distillation rationale, see [`agents/DISTILLATION.md`](agents/DISTILLATION.md).
+11 delegates: 4 mapper, 4 researcher, 1 synthesizer, 1 plan-checker, 1 approach-explorer. Workflows use `<delegate>` blocks to dispatch work. For detailed GSD-to-GSDD role distillation rationale, see [`agents/DISTILLATION.md`](agents/DISTILLATION.md).
 
 ### Adapter Architecture
 
@@ -279,14 +296,15 @@ GSDD generates vendor-specific files from vendor-agnostic markdown — it does n
 
 | Adapter | Kind | Strategy |
 |---------|------|----------|
-| **Claude Code** | `native_capable` | Skill-primary plan surface (stays in main context to spawn checker subagent), thin command alias, native `gsdd-plan-checker` agent |
-| **OpenCode** | `native_capable` | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
-| **Codex CLI** | `native_capable` | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
-| **Cursor / Copilot / Gemini** | `governance_only` | Root `AGENTS.md` block governs agent behavior; invoke workflows by opening `.agents/skills/gsdd-*/SKILL.md` directly |
+| **Claude Code** | `native_capable` adapter + skills-native runtime | Skill-primary plan surface (stays in main context to spawn checker subagent), thin command alias, native `gsdd-plan-checker` agent |
+| **OpenCode** | `native_capable` adapter + skills-native runtime | Specialized `/gsdd-plan` command (`subtask: false`), hidden `gsdd-plan-checker` subagent (`mode: subagent`) |
+| **Codex CLI** | `native_capable` adapter + skills-native runtime | Portable skill as entry surface, `.codex/agents/gsdd-plan-checker.toml` (read-only, high reasoning effort) |
+| **Cursor / Copilot / Gemini** | skills-native runtime + `governance_only` adapter | Runtime discovers `.agents/skills/` natively; optional root `AGENTS.md` block adds behavioral governance only |
+| **agents** (`--tools agents`) | `governance_only` adapter | Root `AGENTS.md` block for tools that benefit from governance or need open-standard fallback guidance |
 
 All adapters render the plan-checker from a single source (`distilled/templates/delegates/plan-checker.md`). Each adapter shapes the output to its platform's native mechanics, and the portable skill remains the shared workflow source.
 
-Cursor, Copilot, and Gemini CLI generate the same root `AGENTS.md` governance block as `--tools agents`. They do not have native adapter surfaces — invoke workflows by opening `.agents/skills/gsdd-*/SKILL.md` directly.
+Cursor, Copilot, and Gemini CLI generate the same root `AGENTS.md` governance block as `--tools agents`, but that file is governance only. Those runtimes already discover `.agents/skills/` natively and surface the workflows as slash commands.
 
 Model IDs pass through a two-layer injection guard: a regex whitelist (`/^[a-zA-Z0-9._\/:@-]+$/`) at the CLI boundary, plus format-specific escaping (TOML string escaping, triple-quote break prevention) at the adapter layer.
 
@@ -410,11 +428,11 @@ For detailed troubleshooting and recovery procedures, see the [User Guide](docs/
 
 ## Design Decisions
 
-GSDD makes 28 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
+GSDD makes 36 documented design decisions relative to GSD, each with evidence from source files and external research. See [`distilled/DESIGN.md`](distilled/DESIGN.md) for the full rationale.
 
 Key choices:
 - **4-file codebase standard** — drop state that rots (STRUCTURE, INTEGRATIONS, TESTING), keep rules that don't
-- **Agent consolidation** — 9 roles from GSD's 11, with explicit reduced-assurance mode when independent checking isn't available
+- **Agent consolidation** — 10 roles from GSD's 11, with explicit reduced-assurance mode when independent checking isn't available
 - **Adapter generation over conversion** — generate vendor-specific files from vendor-agnostic markdown instead of converting from Claude-first
 - **Advisory git** — repo conventions over framework defaults
 - **Context isolation** — summaries up, documents to disk
@@ -436,8 +454,8 @@ Structural contracts that prevent drift between roles, delegates, workflows, and
 
 | Suite | What it guards |
 |-------|---------------|
-| **I1** | Delegate-role reference integrity — 10 delegates resolve to existing role contracts |
-| **I2** | Role section structure — 9 roles have role def, scope, output format, success criteria |
+| **I1** | Delegate-role reference integrity — 11 delegates resolve to existing role contracts |
+| **I2** | Role section structure — 10 roles have role def, scope, output format, success criteria |
 | **I3** | Delegate thinness — no leaked role-contract sections in delegates |
 | **I3-gate** | New-project approval gates — required human checkpoints present |
 | **I4** | Workflow references — 10 workflows, all delegate/role refs resolve |

package/agents/DISTILLATION.md

@@ -1,6 +1,6 @@
 # GSDD Role Distillation Ledger
 
-Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with keep/strip/why rationale. This ledger documents why each role exists in its current form and what GSD content was distilled or merged.
+Evidence map from each of the 10 canonical GSDD roles to their GSD sources, with keep/strip/why rationale. This ledger documents why each role exists in its current form and what GSD content was distilled or merged.
 
 ---
 
@@ -54,7 +54,7 @@ Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with
 - Explicit "Scope" table showing scope × trigger × focus × output location
 - Clear statement: "Same algorithm, different scope. The scope is a context input, not a different role."
 
-**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 while preserving all leverage. This is the clean merger mentioned in D2.
+**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 (later 10 with approach-explorer in D29) while preserving all leverage. This is the clean merger mentioned in D2.
 
 ---
 
@@ -264,6 +264,50 @@ Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with
 
 ---
 
+## 10. Approach-Explorer
+
+**Canonical role:** `agents/approach-explorer.md`
+
+**GSD sources:** `workflows/discuss-phase.md` + `workflows/list-phase-assumptions.md` + `workflows/discovery-phase.md` (merged into new role)
+
+**Merger type:** New role from 2 GSD sources (discuss-phase + list-phase-assumptions) with thematic input from discovery-phase
+
+**Kept from GSD:**
+- Gray area identification with 5 domain types (SEE/CALL/RUN/READ/ORGANIZED) from discuss-phase
+- Scope guardrail: phase boundary is fixed, deferred ideas captured not acted on
+- 5-dimension assumption surfacing (technical approach, implementation order, scope boundaries, risks, dependencies) with confidence levels from list-phase-assumptions
+- Deferred ideas capture from discuss-phase
+- Adaptive area-by-area deep questioning from discuss-phase (GSD used 4-question batches; GSDD uses adaptive convergence)
+
+Note: `discovery-phase.md` contributed the concept of pre-planning research but the mechanism is entirely different — GSD used 3-level depth workflows (Quick/Standard/Deep) as a separate invocation; GSDD uses per-gray-area research subagents embedded in the plan workflow. This is thematic inspiration, not a structural merger.
+
+**Stripped from GSD:**
+- `gsd-tools.cjs` dependencies and STATE.md updates
+- Vendor-specific commit steps, path conventions, and "Claude" references
+- CONTEXT.md output format (replaced with structured APPROACH.md)
+- Separate workflow invocation (absorbed into plan workflow as inline + research subagent hybrid)
+- Rigid 4-question batched loop (replaced with adaptive questioning until decision converges)
+
+**Gained in GSDD:**
+- XML semantic structure matching planner pattern (`<role>`, `<algorithm>`, `<examples>`, etc.)
+- 3 few-shot conversation examples (taste decision, technical decision, hybrid + delegation)
+- Gray area classification: taste (ask directly), technical (research first), hybrid (both)
+- Pre-question research per gray area via isolated research subagents returning compressed summaries
+- Self-check quality gate before writing APPROACH.md
+- Intermediate decision persistence (protect against context limits)
+- JIT context loading with extraction guidance (read ONLY locked decisions from SPEC, ONLY phase goal from ROADMAP)
+- Structured approach comparison with trade-offs
+- File persistence to `{padded_phase}-APPROACH.md` using dedicated template
+- Plan-checker integration via new `approach_alignment` verification dimension
+- Config toggle (`workflow.discuss: true|false`) for optional skip
+- Downstream consumer contract: planner reads locked decisions, plan-checker verifies alignment
+- "Agent's Discretion" explicit marking for areas where user delegates choice (vendor-neutral)
+- Hybrid architecture: conversation inline (main context) + research in subagents. Native agent kept as optimization.
+
+**Rationale:** GSDD's initial distillation dropped GSD's discuss-phase and list-phase-assumptions entirely, removing genuine leverage: the planner converges on a single approach without user input, explores no alternatives, and surfaces no assumptions. The approach explorer recovers this phase-level user alignment by combining GSD's discuss-phase interaction pattern with comparative research. Ground-up rewrite (D29) applied 5 external resources on context engineering, meta-prompting, and agent skill design to produce a prompt-engineered role contract with proper XML structure, examples, adaptive conversation, and hybrid research isolation.
+
+---
+
 ## Summary: Merger Table (from D2)
 
 | Canonical role | Absorbs from GSD | Merger criteria |
@@ -277,8 +321,9 @@ Evidence map from each of the 9 canonical GSDD roles to their GSD sources, with
 | `verifier.md` | `gsd-verifier.md` | Kept-as-is; cross-phase audit extracted to integration-checker |
 | `integration-checker.md` | `gsd-integration-checker.md` | Extracted as standalone; recovered in PR #12, hardened in PR #15 |
 | `debugger.md` | `gsd-debugger.md` | Kept-as-is; no changes |
+| `approach-explorer.md` | `discuss-phase.md` + `list-phase-assumptions.md` + `discovery-phase.md` | New role from 3 GSD workflow sources |
 
-**Result:** 11 GSD roles → 9 GSDD canonical roles (2 mergers: researcher, planner). 1 extraction: integration-checker moved from embedded to standalone. Total leverage preserved, role count reduced.
+**Result:** 11 GSD roles → 10 GSDD canonical roles (2 mergers: researcher, planner). 1 extraction: integration-checker moved from embedded to standalone. 1 addition: approach-explorer recovers discuss-phase leverage with research enhancement. Total leverage preserved and extended.
 
 ---
 
@@ -304,3 +349,71 @@ This ledger is updated when:
 3. New evidence surfaces that changes the distillation rationale (update with citation)
 
 Do not add speculative content. Every entry must reference actual source files and PRs that contain evidence.
+
+---
+
+## Role Contract Design Principles
+
+Cross-source best practices applied to GSDD role contracts, audited against 6 external resources. These principles govern how role contracts should be written and revised. Ranked by impact.
+
+### Architecture-Level (highest leverage)
+
+| Principle | What It Means | Source | GSDD Implementation |
+|-----------|--------------|--------|---------------------|
+| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic CE: "sub-agents perform deep technical work, returning condensed summaries" | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
+| **JIT context loading** | Never say "read everything." Specify what to extract from each file | Anthropic CE: "maintain lightweight identifiers and use these references to dynamically load data into context at runtime" | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
+| **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic CE: "Agent regularly writes notes persisted to memory outside of the context window" | Approach explorer writes decisions to disk as they're confirmed during conversation |
+| **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | Anthropic CE: "agents can assemble understanding layer by layer" | Gray areas presented individually; research loaded per area on demand |
+
+### Prompt Structure (medium leverage)
+
+| Principle | What It Means | Source | GSDD Implementation |
+|-----------|--------------|--------|---------------------|
+| **XML semantic structure** | Use XML tags to separate role, instructions, examples, inputs, outputs, anti-patterns | Anthropic Claude: "XML tags help Claude parse complex prompts unambiguously" | All roles use `<role>`, most use `<quality_guarantees>`, `<anti_patterns>`. Approach-explorer adds `<algorithm>`, `<examples>`, `<scope_guardrail>` |
+| **Anti-patterns early** | Place "don't do this" instructions near the top, after role definition | Anthropic CE: critical information at the beginning gets more attention. NeoLab: early placement for high attention weight | `<anti_patterns>` placed immediately after `<role>` in all roles that have them |
+| **Few-shot examples** | Show the pattern of interaction, not just output format | Anthropic Claude: "3-5 examples for best results." Examples in `<example>` tags | Approach-explorer: 3 examples. Other roles use inline format examples within algorithm sections |
+| **Self-check before output** | Run an explicit checklist before producing the final artifact | OpenAI: "verification loops." Anthropic Claude: "Ask Claude to self-check" | Approach-explorer step 7; planner `<plan_self_check>`; executor completion verification |
+| **Scope boundaries with heuristics** | Don't just list in/out of scope — give the agent a judgment rule | Novel, validated in approach-explorer | "Does this clarify implementation within the phase, or does it add a capability that could be its own phase?" |
+
+### Language & Tone (lower leverage, still matters)
+
+| Principle | What It Means | Source | GSDD Implementation |
+|-----------|--------------|--------|---------------------|
+| **Authority language: intentional leverage** | Anthropic Claude 4.6 warns "CRITICAL:" can overtrigger on newer models. NeoLab persuasion research found imperative language doubled compliance (33%→72%). GSDD decision: **keep CRITICAL: for mandatory initial-read** — this is a genuine compliance-critical instruction where skipping it causes cascading failures. Use normal language for non-critical instructions. | Anthropic Claude 4.6 vs. NeoLab persuasion research (direct conflict). GSDD sides with NeoLab for this specific use case | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
+| **Tell what to do, not just what not to do** | Anti-patterns alone are insufficient; pair with positive instructions | Anthropic Claude: "Tell Claude what to do instead of what not to do" | Every role has both `<anti_patterns>` AND positive algorithm/process sections |
+| **Context for instructions** | Explain WHY a rule exists so the agent can generalize | Anthropic Claude: "Providing context or motivation behind your instructions helps Claude better understand your goals" | Research quality rules explain WHY: "Training data is a hypothesis. Verify before asserting." |
+
+### Novel Patterns (not from any source)
+
+These patterns emerged from GSDD's specific needs and were validated through implementation:
+
+| Pattern | What It Does | Where Used |
+|---------|-------------|------------|
+| **Taste/Technical/Hybrid classification** | Adapts research depth to decision type; taste needs no research, technical does | Approach-explorer step 2 |
+| **Research quality rules** | "One viable option is valid" / "Don't manufacture trade-offs" | Approach-explorer step 3 |
+| **5-dimension assumption surfacing** | Forces transparency about inferences vs. confirmed facts, with confidence levels | Approach-explorer step 6 |
+| **Agent's Discretion delegation** | User can explicitly say "you decide" — reduces fatigue on low-stakes choices | Approach-explorer step 4, planner `<approach_decisions>` |
+| **Domain classification table** | SEE/CALL/RUN/READ/ORGANIZED determines gray area focus per phase type | Approach-explorer step 2 |
+| **Degrees of freedom mapping** | Taste=high freedom, technical=low freedom (research-constrained). Maps to NeoLab's concept | Approach-explorer classification system |
+
+### Source Ranking
+
+Sources are ranked by soundness for agent prompt design. Higher-ranked sources take precedence when sources disagree.
+
+1. **Anthropic — Effective Context Engineering for AI Agents** — Architecture-level patterns with real production evidence (Claude Code, Pokémon). Most authoritative for context window management, sub-agent design, and information flow.
+2. **Anthropic — Claude Prompting Best Practices (Claude 4.6)** — Model-specific, up-to-date. Critical for behavioral warnings (overtriggering, subagent overuse). Supersedes general guidance for Claude-targeted agents.
+3. **OpenAI — Prompt Guidance (GPT-5.4)** — Deepest general-purpose reference. Novel concepts: completeness contracts, verification loops, tool persistence rules, empty result recovery. Model-specific but patterns transfer.
+4. **NeoLab Context Engineering Kit** — Good synthesis. "Degrees of Freedom" concept is useful. Persuasion research contradicts Anthropic on authority language (trust Anthropic for Claude).
+5. **OpenAI Cookbook — Meta-Prompting** — Narrow scope: LLM-as-judge evaluation, iterative prompt refinement. Useful technique, not a framework.
+6. **JBurlison/MetaPrompts** — Structural skeleton (agent/skill/prompt/instruction hierarchy). Minimal actual guidance on prompt quality.
+
+### Key Discrepancy Resolution
+
+When sources conflict, these resolutions apply:
+
+| Conflict | Resolution | Why |
+|----------|------------|-----|
+| Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | NeoLab's doubled-compliance research applies to instructions where skipping causes cascading failures. Anthropic's overtriggering concern applies to general guidance, not load-bearing context gates |
+| Example count (2 vs. 3-5) | Target 3+ for conversational agents; inline format examples are sufficient for structured output agents | Anthropic's 3-5 recommendation is general; interactive roles benefit more than output-only roles |
+| Subagent return size (200 vs. 1000-2000 tokens) | Use 300-500 tokens | Anthropic's 1000-2000 is upper bound; 200 was too tight for structured approach summaries with trade-offs |
+| "Don't invent alternatives" vs. "try fallback strategies" | Keep "don't invent" for approach research; use fallbacks for information retrieval | These solve different problems: manufacturing fake options is worse than acknowledging one viable path |

package/agents/README.md

@@ -18,6 +18,7 @@ Roles define what an agent is. Delegates define what an agent does in a specific
 | Mapper | `mapper.md` | `gsd-codebase-mapper.md` |
 | Researcher | `researcher.md` | `gsd-project-researcher.md` + `gsd-phase-researcher.md` |
 | Synthesizer | `synthesizer.md` | `gsd-research-synthesizer.md` |
+| Approach Explorer | `approach-explorer.md` | `discuss-phase.md` + `list-phase-assumptions.md` + `discovery-phase.md` |
 | Planner | `planner.md` | `gsd-planner.md` + `gsd-plan-checker.md` |
 | Executor | `executor.md` | `gsd-executor.md` |
 | Verifier | `verifier.md` | `gsd-verifier.md` |
@@ -48,6 +49,14 @@ Verifier note:
 - `verifier.md` is phase-scoped.
 - The milestone integration-audit surface exists as `distilled/workflows/audit-milestone.md` with its own `integration-checker.md` role contract. It is not absorbed into the verifier.
 
+## Commit Convention
+
+All commits — whether authored by humans or AI agents — must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). The `semantic-release` automation reads commit messages to determine version bumps and generate the changelog. A commit not following the convention produces no release and no changelog entry.
+
+Use `feat:` for new capabilities, `fix:` for corrections, `chore:` for maintenance that must not trigger a publish, and `test:` for test-only changes. Never use `chore(release):` — that prefix is reserved for the release automation.
+
+See `CONTRIBUTING.md` for the full type table.
+
 ## Archive
 
 `_archive/` contains the original 11 GSD agent files (preserved via `git mv` for history). These are the verbose, GSD-specific sources from which canonical roles were distilled. Do not reference them in workflows; use the canonical roles above.