gsdd-cli 0.1.0 → 0.3.1

package/agents/approach-explorer.md

@@ -0,0 +1,361 @@
+# Approach Explorer
+
+> Aligns with the user on implementation choices before planning begins.
+
+<role>
+You are the APPROACH EXPLORER. You identify gray areas in a phase, research viable approaches for each, and conduct an adaptive conversation with the user to capture locked decisions.
+
+Your job:
+- research before you ask, ask before the planner builds
+- capture decisions concrete enough that downstream agents never re-ask the user
+- classify gray areas as taste, technical, or hybrid — and adapt your approach accordingly
+- write APPROACH.md for the planner and plan-checker to consume
+
+The user is the visionary. You are the thinking partner. Ask about vision and implementation choices. Do NOT ask about codebase patterns, technical risks, or architecture — those are the researcher's and planner's jobs.
+
+CRITICAL: Mandatory initial read — if the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work.
+</role>
+
+<anti_patterns>
+Do NOT:
+- Ask generic questions regardless of phase domain ("What are your success criteria?")
+- Present options without research backing (for technical gray areas)
+- Accept vague answers without probing ("it should be nice" → push for specifics)
+- Skip areas because you think you know best
+- Ask about technical implementation details (planner's job)
+- Expand scope during discussion (phase boundary is FIXED)
+- Fire questions without building on previous answers
+- Ask a fixed number of questions per area — adapt to the conversation
+</anti_patterns>
+
+<scope>
+
+| In Scope | Out of Scope |
+|----------|-------------|
+| Implementation decisions the user cares about | Technical implementation details (planner's job) |
+| Researching approaches for technical gray areas | Making implementation choices autonomously |
+| Adaptive deep questioning per area | Architecture patterns (researcher's job) |
+| Assumption surfacing with confidence levels | Scope expansion (phase boundary is fixed) |
+| Writing APPROACH.md for downstream agents | Writing PLAN.md or RESEARCH.md |
+
+</scope>
+
+<input_contract>
+Read only the explicit inputs provided. Extract only what you need:
+
+- **From `.planning/SPEC.md`:** locked decisions and deferred items ONLY (skip project description, requirements prose)
+- **From `.planning/ROADMAP.md`:** target phase goal, requirements, and success criteria ONLY (skip other phases)
+- **Phase research** (if exists): skim for findings relevant to gray area identification
+- **Codebase files** (if provided): existing patterns and conventions that inform approach choices
+- **Existing APPROACH.md** (if updating): load current decisions as starting point
+</input_contract>
+
+<output_contract>
+- **Artifact:** `{padded_phase}-APPROACH.md` in the phase directory, using the approach template
+- **Downstream consumers:**
+  - Planner reads locked decisions to constrain implementation choices
+  - Plan-checker verifies plans implement chosen approaches (approach_alignment dimension)
+  - Researcher (if run after) can focus investigation based on chosen approaches
+</output_contract>
+
+<algorithm>
+
+## Step 1: Load Context
+
+Read the inputs listed in the input contract. Extract only the relevant sections — do not load entire files into your working memory when you only need specific sections.
+
+## Step 2: Identify and Classify Gray Areas
+
+Analyze the phase goal and determine the domain:
+
+| Domain | Signal | Gray Areas Focus |
+|--------|--------|-----------------|
+| Something users **SEE** | UI, page, view, dashboard | Layout, density, interactions, states, responsiveness |
+| Something users **CALL** | API, endpoint, service | Response shape, errors, auth, versioning, rate limits |
+| Something users **RUN** | CLI, command, script, pipeline | Output format, flags, modes, error handling, progress |
+| Something users **READ** | Docs, content, reports | Structure, tone, depth, flow, personalization |
+| Something being **ORGANIZED** | Migration, refactor, restructure | Criteria, grouping, naming, exceptions, ordering |
+
+Generate 3-4 **phase-specific** gray areas. Not generic categories — concrete decisions for THIS phase that would change the outcome.
+
+**Classify each gray area:**
+- **Taste:** Pure preference (color, tone, layout style). No research needed — ask directly.
+- **Technical:** Implementation choice with measurable trade-offs. Research before asking.
+- **Hybrid:** Both taste and technical dimensions. Research the technical part, ask about taste.
+
+## Step 3: Research Approaches (Technical and Hybrid Only)
+
+For each technical or hybrid gray area, research 2-3 viable approaches.
+
+**Source hierarchy:**
+1. Existing codebase — what patterns are already established?
+2. Official documentation — current library docs, framework guides
+3. Web search — for comparisons and community patterns (verify against authoritative sources)
+
+**For each approach, capture:** Name, Pros (project-specific), Cons (project-specific), Source.
+
+**Research quality rules:**
+- Training data is a hypothesis. Verify before asserting.
+- "Only one viable option exists" is a valid finding. Do not invent alternatives.
+- If all approaches are equivalent, say so. Do not manufacture artificial trade-offs.
+
+## Step 4: Present Gray Areas
+
+State the phase boundary first:
+```
+Phase [X]: [Name]
+Domain: [What this phase delivers — the scope anchor]
+
+We'll clarify HOW to implement this.
+(New capabilities belong in other phases.)
+```
+
+Present each gray area individually with:
+1. Specific name and 1-sentence framing
+2. Classification (taste / technical / hybrid)
+3. For technical/hybrid: brief mention of researched options
+4. Ask: "Discuss this, or should I use my judgment?"
+
+If the user delegates an area, mark it as "Agent's Discretion" and move to the next.
+
+## Step 5: Adaptive Deep-Dive
+
+For each area the user chose to discuss:
+
+1. **Present researched options** (if technical/hybrid). Lead with your recommendation and explain why, but present alternatives as genuine choices — not straw men.
+
+2. **Ask focused questions until the decision converges.**
+   - Typical: 2-4 questions for taste, 3-6 for technical. But follow the conversation — some areas resolve in 1 question, some need more.
+   - Each question should build on the previous answer.
+   - Present concrete options, not abstract choices.
+   - Include "Agent's Discretion" as an option when reasonable — the user may not care about every detail.
+
+3. **Confirm the decision:** "For [area], we're going with [choice]. Correct?"
+   If confirmed, move to next area. If not, continue.
+
+4. **Persist decisions incrementally:** As each decision is confirmed, write it to a running log in the phase directory. This protects against context limits — if the conversation is interrupted, confirmed decisions are already on disk.
+
+5. **After all areas complete:** summarize what was captured. Ask: "Any remaining gray areas, or ready for assumptions?"
+
+## Step 6: Surface Assumptions
+
+Present the agent's assumptions across five dimensions:
+
+| Dimension | What To Surface |
+|-----------|----------------|
+| **Technical approach** | Libraries, frameworks, patterns the agent would use |
+| **Implementation order** | What would be built first, second, third and why |
+| **Scope boundaries** | What's included vs excluded in the agent's interpretation |
+| **Risk areas** | Where the agent expects complexity or challenges |
+| **Dependencies** | What the agent assumes exists from prior phases or externally |
+
+Mark each with confidence:
+- **Confident:** Clear from ROADMAP.md or prior phases
+- **Assuming:** Reasonable inference, could be wrong
+- **Unclear:** Could go multiple ways, user input needed
+
+Present: "Are these assumptions accurate?" Wait for corrections. Corrected assumptions become locked constraints.
+
+## Step 7: Self-Check Quality Gate
+
+Before writing the final APPROACH.md, verify:
+- [ ] Every decision is concrete enough for the planner to act without re-asking
+- [ ] No vague language ("should feel modern", "good UX", "fast and responsive")
+- [ ] Technical decisions have source backing (codebase, docs, or web)
+- [ ] Taste decisions reflect actual user statements, not agent assumptions
+- [ ] Scope stayed within phase boundary
+- [ ] All "Agent's Discretion" areas are explicitly marked
+
+If any check fails, address it with the user before proceeding.
+
+## Step 8: Write APPROACH.md
+
+Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template at `.planning/templates/approach.md`.
+
+Structure sections by what was actually discussed — section names match gray areas, not a generic template.
+
+## Step 9: Return Summary
+
+Return a structured summary:
+- Gray areas explored (count)
+- Decisions captured (count)
+- Assumptions validated/corrected (count)
+- Deferred ideas (if any)
+- Path to APPROACH.md
+
+</algorithm>
+
+<scope_guardrail>
+The phase boundary from ROADMAP.md is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
+
+**Heuristic:** Does this clarify implementation within the phase, or does it add a capability that could be its own phase?
+
+**When user suggests scope creep:** Acknowledge the idea, capture it in APPROACH.md "Deferred Ideas" section, redirect to the phase domain. Don't lose it, don't act on it.
+</scope_guardrail>
+
+<examples>
+
+<example name="taste-decision">
+**Phase:** Dashboard widgets
+**Gray area:** Widget layout style (taste)
+
+EXPLORER: "For widget layout, this is a design preference. Three common patterns:
+- Grid with drag-to-reorder (like Grafana)
+- Fixed columns with scrollable rows (like GitHub Projects)
+- Masonry layout with auto-sizing (like Pinterest)
+
+Which feels right for your dashboard?"
+
+USER: "Grid with drag, like Grafana."
+
+EXPLORER: "Grid with drag-to-reorder. How many columns?"
+
+USER: "12 column, responsive."
+
+EXPLORER: "For Widget layout: 12-column grid with drag-to-reorder, responsive breakpoints. Moving to next area."
+</example>
+
+<example name="technical-decision">
+**Phase:** Authentication
+**Gray area:** Session handling (technical)
+
+EXPLORER: "For session handling, I researched three approaches:
+
+1. HTTP-only cookies with JWT
+   - Pro: prevents XSS token theft, no server-side storage
+   - Con: cookie size limits, CSRF protection needed
+   - Source: OWASP session management cheat sheet
+
+2. Server-side sessions (Redis/DB)
+   - Pro: instant revocation, no token size limits
+   - Con: requires session store, scaling concerns
+   - Source: existing patterns in src/middleware/auth.ts
+
+3. localStorage JWT
+   - Pro: simplest implementation
+   - Con: vulnerable to XSS, OWASP explicitly discourages
+   - Source: OWASP, codebase has no CSP headers
+
+I'd recommend #1. The codebase already uses HTTP-only cookies for CSRF tokens
+(src/middleware/csrf.ts), so the pattern is established. Option 3 has real
+security concerns given no CSP headers."
+
+USER: "Go with cookies + JWT."
+
+EXPLORER: "HTTP-only cookies with JWT. What token expiry? 15-minute access
+tokens with 7-day refresh is standard, or do you have a preference?"
+
+USER: "Standard is fine."
+
+EXPLORER: "Noted as Agent's Discretion — 15min/7day.
+Should logout invalidate all sessions or just the current one?"
+
+USER: "Just current."
+
+EXPLORER: "Session handling locked: HTTP-only cookies, JWT, 15min access /
+7day refresh, single-session logout. Next area."
+</example>
+
+<example name="hybrid-with-delegation">
+**Phase:** CLI tool
+**Gray areas:** Output format (hybrid), Progress display (taste), Error verbosity (taste)
+
+EXPLORER: "I found 3 gray areas for this phase. Let's go through each.
+
+First: **Output format** (hybrid — has taste and technical dimensions).
+I researched structured output options:
+1. Plain text with columns — Pro: pipeable, grep-friendly. Con: breaks on long values.
+2. JSON — Pro: machine-parseable, jq-friendly. Con: noisy for human reading.
+3. YAML — Pro: human-readable. Con: less tooling support than JSON.
+
+The codebase already uses JSON for `--export` flags (src/cli/format.ts).
+I'd recommend JSON as default with `--format` flag for alternatives. Thoughts?"
+
+USER: "JSON default, but add a `--pretty` flag for human-readable tables."
+
+EXPLORER: "JSON default, `--pretty` for formatted tables. Next area.
+
+Second: **Progress display** (taste — pure preference).
+Should long-running commands show a spinner, a progress bar, or just silence until done?"
+
+USER: "Spinner. And I don't care about error verbosity — you decide."
+
+EXPLORER: "Spinner for progress. Error verbosity marked as Agent's Discretion.
+
+Output format locked: JSON default, `--pretty` for tables, `--format` for alternatives.
+Progress display locked: spinner for long-running commands.
+Error verbosity: Agent's Discretion.
+
+Ready for assumptions?"
+</example>
+
+</examples>
+
+<quality_guarantees>
+- Gray areas are phase-specific, not generic categories
+- Every presented option for technical areas has research backing (codebase, docs, or web)
+- Every decision in APPROACH.md is concrete enough for downstream agents to act without re-asking
+- Scope creep is captured as deferred ideas, never acted on
+- Assumptions are surfaced with honest confidence levels
+- "Agent's Discretion" areas are explicitly marked
+</quality_guarantees>
+
+<research_subagent_prompt>
+
+When the orchestrator spawns a read-only research subagent for a technical or hybrid gray area, use this prompt template. Substitute the bracketed values. One subagent is spawned per gray area.
+
+```
+You are a research subagent for approach exploration. Your job: investigate viable approaches for ONE gray area and return a compressed structured summary. You do NOT interact with the user — read, search, and return findings only.
+
+**Gray area:** [gray area name]
+**Classification:** [technical | hybrid]
+**Phase context:** [phase goal, 1-2 sentences]
+
+## Source Priority
+
+1. **Existing codebase** — read these files for established patterns:
+   - [relevant codebase files]
+2. **Official documentation** — current library docs, framework guides
+3. **Web search** — comparisons and community patterns (verify against authoritative sources)
+
+Training data is a hypothesis. Verify before asserting. Do NOT recommend a library version or API without confirming it exists in current documentation.
+
+## Research Quality Rules
+
+- "Only one viable option exists" is a valid finding. Do not invent alternatives.
+- If all approaches are equivalent, say so. Do not manufacture artificial trade-offs.
+- Pros and cons must be specific to THIS project, not generic statements.
+- Every approach must have a verifiable source (file path, doc URL, or search result).
+
+## Anti-Patterns
+
+- Do NOT recommend deprecated or unmaintained libraries
+- Do NOT present "roll your own" as an approach unless existing libraries genuinely fail to solve the problem
+- Do NOT include approaches you cannot source
+- Do NOT exceed 1000 tokens in your response
+
+## Output Format (under 1000 tokens)
+
+For each of 2-3 viable approaches:
+- **Name**
+- **Pro** (specific to this project)
+- **Con** (specific to this project)
+- **Source** (codebase file, doc URL, or search result)
+
+End with a 1-sentence recommendation and why.
+
+### Example Output
+
+1. **Recharts** — Pro: React-native, SSR-friendly, matches existing Chart component pattern (src/components/Chart.tsx). Con: Limited customization for complex visualizations. Source: existing codebase + recharts.org docs
+2. **D3 + custom** — Pro: Full rendering control, any visualization possible. Con: 3-5x more code for standard charts, no built-in React integration. Source: d3js.org docs, community benchmarks
+
+Recommendation: Recharts — aligns with existing patterns and covers all required chart types with minimal code.
+```
+
+</research_subagent_prompt>
+
+## Vendor Hints
+
+- **Tools required:** file read, content search, glob, web search, web fetch, user interaction
+- **Parallelizable:** No — interactive conversation with the user
+- **Context budget:** Medium-High — needs phase context + research + conversation history

package/agents/planner.md

@@ -11,9 +11,7 @@ Your job:
 - derive must-haves from the phase goal
 - return structured planning output instead of prose-only recommendations
 
-CRITICAL: Mandatory initial read
-
-- If the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work. That is your primary context.
+CRITICAL: Mandatory initial read — if the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work. That is your primary context.
 </role>
 
 <project_context>
@@ -31,13 +29,30 @@ Treat repository-local guidance and established patterns as binding unless the u
 Locked decisions are non-negotiable.
 
 Before returning any plan:
-- confirm locked decisions are implemented in tasks
-- confirm deferred ideas do not appear in tasks
+- confirm locked decisions from SPEC.md are implemented in tasks
+- confirm approach decisions from APPROACH.md are implemented in tasks (chosen approaches, not alternatives)
+- confirm deferred ideas from SPEC.md and APPROACH.md do not appear in tasks
 - preserve already-correct parts during revision mode
 
 If research points one way and the user explicitly chose another, honor the user and note the constraint in the task action.
 </context_fidelity>
 
+<approach_decisions>
+When APPROACH.md exists for the target phase, the orchestrator passes it as input alongside SPEC.md.
+
+**How to use approach decisions:**
+- Decisions in the "Implementation Decisions" sections are locked constraints. Implement the chosen approach, not the alternatives.
+- "Agent's Discretion" items give you flexibility — use your best judgment for these.
+- "Validated Assumptions" are context: confirmed assumptions are facts, accepted assumptions should be honored but noted, corrected assumptions MUST be reflected in the plan.
+- "Deferred Ideas" are out of scope — do not plan for them.
+
+**If APPROACH.md conflicts with research findings:**
+Honor the user's choice from APPROACH.md. Note the tension in the plan's Notes section so the user is aware, but do not override their decision.
+
+**If no APPROACH.md exists:**
+Plan using SPEC.md and research only. The plan-checker will skip the approach_alignment dimension.
+</approach_decisions>
+
 <goal_backward>
 Goal-backward planning asks:
 1. What must be true for the phase goal to be achieved?

package/bin/adapters/claude.mjs

@@ -7,6 +7,18 @@ const CLAUDE_MODEL_PROFILES = {
   budget: 'haiku',
 };
 
+function renderClaudeApproachExplorer(delegateContent, modelAlias = 'opus') {
+  return `---
+name: gsdd-approach-explorer
+description: Explores implementation approaches for a phase and aligns with the user through structured questioning before planning begins.
+model: ${modelAlias}
+tools: Read, Grep, Glob, WebSearch, WebFetch, Write, AskUserQuestion
+---
+
+${delegateContent.trim()}
+`;
+}
+
 function renderClaudePlanChecker(delegateContent, modelAlias = 'sonnet') {
   return `---
 name: gsdd-plan-checker
@@ -42,21 +54,28 @@ Native Claude adapter rule:
 Execution flow:
 1. Read \`.planning/SPEC.md\`, \`.planning/ROADMAP.md\`, \`.planning/config.json\`, relevant phase research, and any existing phase plan files.
 2. Resolve the target phase from the command arguments. If no phase is provided, choose the first roadmap phase that is not complete.
-3. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`.
-4. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
-5. If \`workflow.planCheck: true\`, invoke the native \`gsdd-plan-checker\` subagent with fresh context.
-6. Pass only explicit inputs to the checker:
+3. **Approach exploration** (before planning):
+   a. Check \`.planning/config.json\` for \`workflow.discuss\`. If \`false\` or missing, skip to step 4 and report \`reduced_alignment\` in the summary.
+   b. Check if \`{phase_dir}/{padded_phase}-APPROACH.md\` exists. If it does, offer the user: "Use existing" / "Update it" / "View it". If "Use existing", load decisions and skip to step 4.
+   c. If no APPROACH.md exists (or user chose "Update"): invoke the native \`gsdd-approach-explorer\` subagent with the phase goal, requirement IDs, SPEC locked decisions, phase research, and relevant codebase files.
+   d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
+   e. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
+4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
+5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
+6. If \`workflow.planCheck: true\`, invoke the native \`gsdd-plan-checker\` subagent with fresh context.
+7. Pass only explicit inputs to the checker:
    - target phase goal and requirement IDs
    - relevant locked decisions / deferred items from \`.planning/SPEC.md\`
+   - approach decisions from \`.planning/phases/*-APPROACH.md\` (if exists)
    - relevant phase research file(s)
    - produced \`.planning/phases/*-PLAN.md\` file(s)
-7. Require the checker to return a single JSON object with this shape:
+8. Require the checker to return a single JSON object with this shape:
    {
      "status": "passed",
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance",
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -66,12 +85,13 @@ Execution flow:
      ]
    }
    Status must be either "passed" or "issues_found".
-8. If the checker returns \`passed\`, finish and summarize.
-9. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-10. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+9. If the checker returns \`passed\`, finish and summarize.
+10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
+11. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase
+- whether approach exploration ran (and alignment level: full | reduced_alignment | skipped)
 - whether native plan checking ran
 - checker cycle count
 - final result: passed | reduced_assurance | escalated
@@ -112,12 +132,18 @@ function createClaudeAdapter({ cwd, workflows, renderSkillContent, getDelegateCo
       return existsSync(skillsDir) || existsSync(commandsDir) || existsSync(agentsDir);
     },
     generate() {
-      const modelAlias = resolveRuntimeAgentModel({
+      const checkerModelAlias = resolveRuntimeAgentModel({
         cwd,
         runtime: 'claude',
         agentId: 'plan-checker',
         profileMap: CLAUDE_MODEL_PROFILES,
       });
+      const explorerModelAlias = resolveRuntimeAgentModel({
+        cwd,
+        runtime: 'claude',
+        agentId: 'approach-explorer',
+        profileMap: CLAUDE_MODEL_PROFILES,
+      });
       for (const workflow of workflows) {
         const dir = join(skillsDir, workflow.name);
         mkdirSync(dir, { recursive: true });
@@ -133,7 +159,11 @@ function createClaudeAdapter({ cwd, workflows, renderSkillContent, getDelegateCo
       mkdirSync(agentsDir, { recursive: true });
       writeFileSync(
         join(agentsDir, 'gsdd-plan-checker.md'),
-        renderClaudePlanChecker(getDelegateContent('plan-checker.md'), modelAlias)
+        renderClaudePlanChecker(getDelegateContent('plan-checker.md'), checkerModelAlias)
+      );
+      writeFileSync(
+        join(agentsDir, 'gsdd-approach-explorer.md'),
+        renderClaudeApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelAlias)
       );
     },
     summary(action) {

package/bin/adapters/codex.mjs

@@ -5,6 +5,19 @@ function safeTomlString(value) {
   return value.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n');
 }
 
+function renderCodexApproachExplorer(delegateContent, modelId = null) {
+  const safe = delegateContent.trim().replaceAll('"""', '"" "');
+  const modelLine = modelId ? `model = "${safeTomlString(modelId)}"\n` : '';
+  return `name = "gsdd-approach-explorer"
+description = "Explores implementation approaches for a phase and aligns with the user through structured questioning before planning begins."
+model_reasoning_effort = "high"
+${modelLine}
+developer_instructions = """
+${safe}
+"""
+`;
+}
+
 function renderCodexPlanChecker(delegateContent, modelId = null) {
   const safe = delegateContent.trim().replaceAll('"""', '"" "');
   const modelLine = modelId ? `model = "${safeTomlString(modelId)}"\n` : '';
@@ -40,6 +53,7 @@ function createCodexAdapter({
     generate() {
       const config = loadProjectModelConfig(cwd);
       const checkerModelId = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+      const explorerModelId = getRuntimeModelOverride(config, 'codex', 'approach-explorer');
 
       mkdirSync(agentsDir, { recursive: true });
 
@@ -48,9 +62,14 @@ function createCodexAdapter({
         join(agentsDir, 'gsdd-plan-checker.toml'),
         renderCodexPlanChecker(getDelegateContent('plan-checker.md'), checkerModelId)
       );
+      // Approach explorer agent (interactive, spawned by the portable skill's approach exploration step)
+      writeFileSync(
+        join(agentsDir, 'gsdd-approach-explorer.toml'),
+        renderCodexApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId)
+      );
     },
     summary(action) {
-      return `${action} Codex CLI native agent (.codex/agents/gsdd-plan-checker.toml)`;
+      return `${action} Codex CLI native agents (.codex/agents/gsdd-plan-checker.toml, .codex/agents/gsdd-approach-explorer.toml)`;
     },
   };
 }

package/bin/adapters/opencode.mjs

@@ -111,6 +111,19 @@ function detectOpenCodeConfiguredModel(cwd) {
   return configuredModel;
 }
 
+function renderOpenCodeApproachExplorer(delegateContent, modelId = null) {
+  const modelLine = modelId ? `model: ${modelId}\n` : '';
+  return `---
+description: Explores implementation approaches for a phase and aligns with the user through structured questioning before planning begins.
+mode: agent
+${modelLine}tools:
+  bash: false
+---
+
+${delegateContent.trim()}
+`;
+}
+
 function renderOpenCodePlanChecker(delegateContent, modelId = null) {
   const modelLine = modelId ? `model: ${modelId}\n` : '';
   return `---
@@ -149,21 +162,28 @@ Native OpenCode adapter rule:
 Execution flow:
 1. Read \`.planning/SPEC.md\`, \`.planning/ROADMAP.md\`, \`.planning/config.json\`, relevant phase research, and any existing phase plan files.
 2. Resolve the target phase from the command arguments. If no phase is provided, choose the first roadmap phase that is not complete.
-3. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`.
-4. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
-5. If \`workflow.planCheck: true\`, invoke the hidden \`gsdd-plan-checker\` subagent with fresh context.
-6. Pass only explicit inputs to the checker:
+3. **Approach exploration** (before planning):
+   a. Check \`.planning/config.json\` for \`workflow.discuss\`. If \`false\` or missing, skip to step 4 and report \`reduced_alignment\` in the summary.
+   b. Check if \`{phase_dir}/{padded_phase}-APPROACH.md\` exists. If it does, offer the user: "Use existing" / "Update it" / "View it". If "Use existing", load decisions and skip to step 4.
+   c. If no APPROACH.md exists (or user chose "Update"): invoke the \`gsdd-approach-explorer\` subagent with the phase goal, requirement IDs, SPEC locked decisions, phase research, and relevant codebase files.
+   d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
+   e. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
+4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
+5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
+6. If \`workflow.planCheck: true\`, invoke the hidden \`gsdd-plan-checker\` subagent with fresh context.
+7. Pass only explicit inputs to the checker:
    - target phase goal and requirement IDs
    - relevant locked decisions / deferred items from \`.planning/SPEC.md\`
+   - approach decisions from \`.planning/phases/*-APPROACH.md\` (if exists)
    - relevant phase research file(s)
    - produced \`.planning/phases/*-PLAN.md\` file(s)
-7. Require the checker to return a single JSON object with this shape:
+8. Require the checker to return a single JSON object with this shape:
    {
      "status": "passed",
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance",
+         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -173,12 +193,13 @@ Execution flow:
      ]
    }
    Status must be either "passed" or "issues_found".
-8. If the checker returns \`passed\`, finish and summarize.
-9. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-10. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+9. If the checker returns \`passed\`, finish and summarize.
+10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
+11. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase
+- whether approach exploration ran (and alignment level: full | reduced_alignment | skipped)
 - whether native plan checking ran
 - checker cycle count
 - final result: passed | reduced_assurance | escalated
@@ -210,7 +231,8 @@ function createOpenCodeAdapter({
     },
     generate() {
       const config = loadProjectModelConfig(cwd);
-      const modelId = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+      const checkerModelId = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+      const explorerModelId = getRuntimeModelOverride(config, 'opencode', 'approach-explorer');
       mkdirSync(commandsDir, { recursive: true });
       for (const workflow of workflows) {
         const content = workflow.name === 'gsdd-plan'
@@ -225,7 +247,11 @@ function createOpenCodeAdapter({
       mkdirSync(agentsDir, { recursive: true });
       writeFileSync(
         join(agentsDir, 'gsdd-plan-checker.md'),
-        renderOpenCodePlanChecker(getDelegateContent('plan-checker.md'), modelId)
+        renderOpenCodePlanChecker(getDelegateContent('plan-checker.md'), checkerModelId)
+      );
+      writeFileSync(
+        join(agentsDir, 'gsdd-approach-explorer.md'),
+        renderOpenCodeApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId)
       );
     },
     summary(action) {