@opengsd/get-shit-done-redux 1.0.0

package/get-shit-done/workflows/discuss-phase/modes/chain.md

@@ -0,0 +1,97 @@
+# --chain mode — interactive discuss, then auto-advance
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
+> `--chain` is present in `$ARGUMENTS`, or when the parent's `auto_advance`
+> step needs to dispatch to plan-phase under `--auto`.
+
+## Effect
+
+- Discussion is **fully interactive** — questions, gray-area selection, and
+  follow-ups behave exactly the same as default mode.
+- After discussion completes, **auto-advance to plan-phase → execute-phase**
+  (same downstream behavior as `--auto`).
+- This is the middle ground: the user controls the discuss decisions, then
+  plan and execute run autonomously.
+
+## auto_advance step (executed by the parent file)
+
+1. Parse `--auto` and `--chain` flags from `$ARGUMENTS`. **Note:** `--all`
+   is NOT an auto-advance trigger — it only affects area selection. A
+   session with `--all` but without `--auto` or `--chain` returns to manual
+   next-steps after discussion completes.
+
+2. **Sync chain flag with intent** — if user invoked manually (no `--auto`
+   and no `--chain`), clear the ephemeral chain flag from any previous
+   interrupted `--auto` chain. This does NOT touch `workflow.auto_advance`
+   (the user's persistent settings preference):
+   ```bash
+   if [[ ! "$ARGUMENTS" =~ --auto ]] && [[ ! "$ARGUMENTS" =~ --chain ]]; then
+     $GSD_SDK query config-set workflow._auto_chain_active false || true
+   fi
+   ```
+
+3. Read consolidated auto-mode (`active` = chain flag OR user preference):
+   ```bash
+   AUTO_MODE=$($GSD_SDK query check auto-mode --pick active 2>/dev/null || echo "false")
+   ```
+
+4. **If `--auto` or `--chain` flag present AND `AUTO_MODE` is not true:**
+   Persist chain flag to config (handles direct usage without new-project):
+   ```bash
+   $GSD_SDK query config-set workflow._auto_chain_active true
+   ```
+
+5. **If `--auto` flag present OR `--chain` flag present OR `AUTO_MODE` is
+   true:** display banner and launch plan-phase.
+
+   Banner:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    GSD ► AUTO-ADVANCING TO PLAN
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Context captured. Launching plan-phase...
+   ```
+
+   Launch plan-phase using the Skill tool to avoid nested Task sessions
+   (which cause runtime freezes due to deep agent nesting — see #686):
+   ```
+   Skill(skill="gsd-plan-phase", args="${PHASE} --auto ${GSD_WS}")
+   ```
+
+   This keeps the auto-advance chain flat — discuss, plan, and execute all
+   run at the same nesting level rather than spawning increasingly deep
+   Task agents.
+
+6. **Handle plan-phase return:**
+
+   - **PHASE COMPLETE** → Full chain succeeded. Display:
+     ```
+     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      GSD ► PHASE ${PHASE} COMPLETE
+     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+     Auto-advance pipeline finished: discuss → plan → execute
+
+     /clear then:
+
+     Next: /gsd:discuss-phase ${NEXT_PHASE} ${WAS_CHAIN ? "--chain" : "--auto"} ${GSD_WS}
+     ```
+   - **PLANNING COMPLETE** → Planning done, execution didn't complete:
+     ```
+     Auto-advance partial: Planning complete, execution did not finish.
+     Continue: /gsd:execute-phase ${PHASE} ${GSD_WS}
+     ```
+   - **PLANNING INCONCLUSIVE / CHECKPOINT** → Stop chain:
+     ```
+     Auto-advance stopped: Planning needs input.
+     Continue: /gsd:plan-phase ${PHASE} ${GSD_WS}
+     ```
+   - **GAPS FOUND** → Stop chain:
+     ```
+     Auto-advance stopped: Gaps found during execution.
+     Continue: /gsd:plan-phase ${PHASE} --gaps ${GSD_WS}
+     ```
+
+7. **If none of `--auto`, `--chain`, nor config enabled:** route to
+   `confirm_creation` step (existing behavior — show manual next steps).

package/get-shit-done/workflows/discuss-phase/modes/default.md

@@ -0,0 +1,141 @@
+# Default mode — interactive discuss-phase
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when no
+> mode flag is present (the baseline interactive flow). When `--text`,
+> `--batch`, or `--analyze` is also present, layer the corresponding overlay
+> file from this directory on top of the rules below.
+
+This document defines `discuss_areas` for the default flow. The shared steps
+that come before (`initialize`, `check_blocking_antipatterns`, `check_spec`,
+`check_existing`, `load_prior_context`, `cross_reference_todos`,
+`scout_codebase`, `analyze_phase`, `present_gray_areas`) live in the parent
+file and run for every mode.
+
+## discuss_areas (default, interactive)
+
+For each selected area, conduct a focused discussion loop.
+
+**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in config (from init context or `.planning/config.json`). When enabled, before presenting questions for each area:
+1. Do a brief web search for best practices related to the area topic
+2. Summarize the top findings in 2-3 bullet points
+3. Present the research alongside the question so the user can make a more informed decision
+
+Example with research enabled:
+```text
+Let's talk about [Authentication Strategy].
+
+📊 Best practices research:
+• OAuth 2.0 + PKCE is the current standard for SPAs (replaces implicit flow)
+• Session tokens with httpOnly cookies preferred over localStorage for XSS protection
+• Consider passkey/WebAuthn support — adoption is accelerating in 2025-2026
+
+With that context: How should users authenticate?
+```
+
+When disabled (default), skip the research and present questions directly as before.
+
+**Philosophy:** stay adaptive. Default flow is 4 single-question turns, then
+check whether to continue. Each answer should reveal the next question.
+
+**For each area:**
+
+1. **Announce the area:**
+   ```text
+   Let's talk about [Area].
+   ```
+
+2. **Ask 4 questions using AskUserQuestion:**
+   - header: "[Area]" (max 12 chars — abbreviate if needed)
+   - question: Specific decision for this area
+   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why
+   - **Annotate options with code context** when relevant:
+     ```text
+     "How should posts be displayed?"
+     - Cards (reuses existing Card component — consistent with Messages)
+     - List (simpler, would be a new pattern)
+     - Timeline (needs new Timeline component — none exists yet)
+     ```
+   - Include "You decide" as an option when reasonable — captures Claude discretion
+   - **Context7 for library choices:** When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use `mcp__context7__*` tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options.
+
+3. **After the current set of questions, check:**
+   - header: "[Area]" (max 12 chars)
+   - question: "More questions about [area], or move to next? (Remaining: [list other unvisited areas])"
+   - options: "More questions" / "Next area"
+
+   When building the question text, list the remaining unvisited areas so the user knows what's ahead. For example: "More questions about Layout, or move to next? (Remaining: Loading behavior, Content ordering)"
+
+   If "More questions" → ask another 4 single questions, then check again
+   If "Next area" → proceed to next selected area
+   If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"
+
+4. **After all initially-selected areas complete:**
+   - Summarize what was captured from the discussion so far
+   - AskUserQuestion:
+     - header: "Done"
+     - question: "We've discussed [list areas]. Which gray areas remain unclear?"
+     - options: "Explore more gray areas" / "I'm ready for context"
+   - If "Explore more gray areas":
+     - Identify 2-4 additional gray areas based on what was learned
+     - Return to present_gray_areas logic with these new areas
+     - Loop: discuss new areas, then prompt again
+   - If "I'm ready for context": Proceed to write_context
+
+**Canonical ref accumulation during discussion:**
+When the user references a doc, spec, or ADR during any answer — e.g., "read adr-014", "check the MCP spec", "per browse-spec.md" — immediately:
+1. Read the referenced doc (or confirm it exists)
+2. Add it to the canonical refs accumulator with full relative path
+3. Use what you learned from the doc to inform subsequent questions
+
+These user-referenced docs are often MORE important than ROADMAP.md refs because they represent docs the user specifically wants downstream agents to follow. Never drop them.
+
+**Question design:**
+- Options should be concrete, not abstract ("Cards" not "Option A")
+- Each answer should inform the next question or next batch
+- If user picks "Other" to provide freeform input (e.g., "let me describe it", "something else", or an open-ended reply), ask your follow-up as plain text — NOT another AskUserQuestion. Wait for them to type at the normal prompt, then reflect their input back and confirm before resuming AskUserQuestion or the next numbered batch.
+
+**Thinking partner (conditional):**
+If `features.thinking_partner` is enabled in config, check the user's answer for tradeoff signals
+(see `references/thinking-partner.md` for signal list). If tradeoff detected:
+
+```text
+I notice competing priorities here — {option_A} optimizes for {goal_A} while {option_B} optimizes for {goal_B}.
+
+Want me to think through the tradeoffs before we lock this in?
+[Yes, analyze] / [No, decision made]
+```
+
+If yes: provide 3-5 bullet analysis (what each optimizes/sacrifices, alignment with PROJECT.md goals, recommendation). Then return to normal flow.
+
+**Scope creep handling:**
+If user mentions something outside the phase domain:
+```text
+"[Feature] sounds like a new capability — that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to [current area]: [return to current question]"
+```
+
+Track deferred ideas internally.
+
+**Incremental checkpoint — save after each area completes:**
+
+After each area is resolved (user says "Next area"), immediately write a checkpoint file with all decisions captured so far. This prevents data loss if the session is interrupted mid-discussion.
+
+**Checkpoint file:** `${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json`
+
+Schema: read `workflows/discuss-phase/templates/checkpoint.json` for the
+canonical structure — copy it and substitute the live values.
+
+**On session resume:** Handled in the parent's `check_existing` step. After
+`write_context` completes successfully, the parent's `git_commit` step
+deletes the checkpoint.
+
+**Track discussion log data internally:**
+For each question asked, accumulate:
+- Area name
+- All options presented (label + description)
+- Which option the user selected (or their free-text response)
+- Any follow-up notes or clarifications the user provided
+
+This data is used to generate DISCUSSION-LOG.md in the parent's `git_commit` step.

package/get-shit-done/workflows/discuss-phase/modes/power.md

@@ -0,0 +1,44 @@
+# --power mode — bulk question generation, async answering
+
+> **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
+> `--power` is present in `$ARGUMENTS`. The full step-by-step instructions
+> live in the existing `discuss-phase-power.md` workflow file (kept stable
+> at its original path so installed `@`-references continue to resolve).
+
+## Dispatch
+
+```
+Read @~/.claude/get-shit-done/workflows/discuss-phase-power.md
+```
+
+Execute it end-to-end. Do not continue with the standard interactive steps.
+
+## Summary of flow
+
+The power user mode generates ALL questions upfront into machine-readable
+and human-friendly files, then waits for the user to answer at their own
+pace before processing all answers in a single pass.
+
+1. Run the same phase analysis (gray area identification) as standard mode
+2. Write all questions to
+   `{phase_dir}/{padded_phase}-QUESTIONS.json` and
+   `{phase_dir}/{padded_phase}-QUESTIONS.html`
+3. Notify user with file paths and wait for a "refresh" or "finalize"
+   command
+4. On "refresh": read the JSON, process answered questions, update stats
+   and HTML
+5. On "finalize": read all answers from JSON, generate CONTEXT.md in the
+   standard format
+
+## When to use
+
+Large phases with many gray areas, or when users prefer to answer
+questions offline / asynchronously rather than interactively in the chat
+session.
+
+## Combination rules
+
+- `--power --auto`: power wins. Power mode is incompatible with
+  autonomous selection — its purpose is offline answering.
+- `--power --chain`: after the power-mode finalize step writes
+  CONTEXT.md, the chain auto-advance still applies (Read `chain.md`).

package/get-shit-done/workflows/discuss-phase/modes/text.md

@@ -0,0 +1,55 @@
+# --text mode — plain-text overlay (no AskUserQuestion)
+
+> **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`
+> when `--text` is present in `$ARGUMENTS`, OR when
+> `workflow.text_mode: true` is set in config (e.g., per-project default).
+
+## Effect
+
+When text mode is active, **do not use AskUserQuestion at all**. Instead,
+present every question as a plain-text numbered list and ask the user to
+type their choice number. Free-text input maps to the "Other" branch of
+the equivalent AskUserQuestion call.
+
+This is required for Claude Code remote sessions (`/rc` mode) where the
+Claude App cannot forward TUI menu selections back to the host.
+
+## Activation
+
+- Per-session: pass `--text` flag to any command (e.g.,
+  `/gsd:discuss-phase --text`)
+- Per-project: `gsd-sdk query config-set workflow.text_mode true`
+
+Text mode applies to ALL workflows in the session, not just discuss-phase.
+
+## Question rendering
+
+Replace this:
+```text
+AskUserQuestion(
+  header="Layout",
+  question="How should posts be displayed?",
+  options=["Cards", "List", "Timeline"]
+)
+```
+
+With this:
+```text
+Layout — How should posts be displayed?
+  1. Cards
+  2. List
+  3. Timeline
+  4. Other (type freeform)
+
+Reply with a number, or describe your preference.
+```
+
+Wait for the user's reply at the normal prompt. Parse:
+- Numeric reply → mapped to that option
+- Free text → treated as "Other" — reflect it back, confirm, then proceed
+
+## Empty-answer handling
+
+The same answer-validation rules from the parent file apply: empty
+responses trigger one retry, then a clarifying question. Do not proceed
+with empty input.

package/get-shit-done/workflows/discuss-phase/templates/checkpoint.json

@@ -0,0 +1,18 @@
+{
+  "phase": "{PHASE_NUM}",
+  "phase_name": "{phase_name}",
+  "timestamp": "{ISO timestamp}",
+  "areas_completed": ["Area 1", "Area 2"],
+  "areas_remaining": ["Area 3", "Area 4"],
+  "decisions": {
+    "Area 1": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]},
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ],
+    "Area 2": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ]
+  },
+  "deferred_ideas": ["..."],
+  "canonical_refs": ["..."]
+}

package/get-shit-done/workflows/discuss-phase/templates/context.md

@@ -0,0 +1,136 @@
+# CONTEXT.md template — for discuss-phase write_context step
+
+> **Lazy-loaded.** Read this file only inside the `write_context` step of
+> `workflows/discuss-phase.md`, immediately before writing
+> `${phase_dir}/${padded_phase}-CONTEXT.md`. Do not put a reference to this
+> file in `<required_reading>` — that defeats the progressive-disclosure
+> savings introduced by issue #2551.
+
+## Variable substitutions
+
+The caller substitutes:
+- `[X]` → phase number
+- `[Name]` → phase name
+- `[date]` → ISO date when context was gathered
+- `${padded_phase}` → zero-padded phase number (e.g., `07`, `15`)
+- `{N}` → counts (requirements, etc.)
+
+## Conditional sections
+
+- **`<spec_lock>`** — include only when `spec_loaded = true` (a `*-SPEC.md`
+  was found by `check_spec`). Otherwise omit the entire `<spec_lock>` block.
+- **Folded Todos / Reviewed Todos** — include subsections only when the
+  `cross_reference_todos` step folded or reviewed at least one todo.
+
+## Template body
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor]
+
+</domain>
+
+[If spec_loaded = true, insert this section:]
+<spec_lock>
+## Requirements (locked via SPEC.md)
+
+**{N} requirements are locked.** See `{padded_phase}-SPEC.md` for full requirements, boundaries, and acceptance criteria.
+
+Downstream agents MUST read `{padded_phase}-SPEC.md` before planning or implementing. Requirements are not duplicated here.
+
+**In scope (from SPEC.md):** [copy the "In scope" bullet list from SPEC.md Boundaries]
+**Out of scope (from SPEC.md):** [copy the "Out of scope" bullet list from SPEC.md Boundaries]
+
+</spec_lock>
+
+<decisions>
+## Implementation Decisions
+
+### [Category 1 that was discussed]
+- **D-01:** [Decision or preference captured]
+- **D-02:** [Another decision if applicable]
+
+### [Category 2 that was discussed]
+- **D-03:** [Decision or preference captured]
+
+### Claude's Discretion
+[Areas where user said "you decide" — note that Claude has flexibility here]
+
+### Folded Todos
+[If any todos were folded into scope from the cross_reference_todos step, list them here.
+Each entry should include the todo title, original problem, and how it fits this phase's scope.
+If no todos were folded: omit this subsection entirely.]
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+[MANDATORY section. Write the FULL accumulated canonical refs list here.
+Sources: ROADMAP.md refs + REQUIREMENTS.md refs + user-referenced docs during
+discussion + any docs discovered during codebase scout. Group by topic area.
+Every entry needs a full relative path — not just a name.]
+
+### [Topic area 1]
+- `path/to/adr-or-spec.md` — [What it decides/defines that's relevant]
+- `path/to/doc.md` §N — [Specific section reference]
+
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What this doc defines]
+
+[If no external specs: "No external specs — requirements fully captured in decisions above"]
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up but belong in other phases. Don't lose them.]
+
+### Reviewed Todos (not folded)
+[If any todos were reviewed in cross_reference_todos but not folded into scope,
+list them here so future phases know they were considered.
+Each entry: todo title + reason it was deferred (out of scope, belongs in Phase Y, etc.)
+If no reviewed-but-deferred todos: omit this subsection entirely.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: [X]-[Name]*
+*Context gathered: [date]*
+```

package/get-shit-done/workflows/discuss-phase/templates/discussion-log.md

@@ -0,0 +1,50 @@
+# DISCUSSION-LOG.md template — for discuss-phase git_commit step
+
+> **Lazy-loaded.** Read this file only inside the `git_commit` step of
+> `workflows/discuss-phase.md`, immediately before writing
+> `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`.
+
+## Purpose
+
+Audit trail for human review (compliance, learning, retrospectives). NOT
+consumed by downstream agents — those read CONTEXT.md only.
+
+## Template body
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+[For each gray area discussed:]
+
+## [Area Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Description from AskUserQuestion] | |
+| [Option 2] | [Description] | ✓ |
+| [Option 3] | [Description] | |
+
+**User's choice:** [Selected option or free-text response]
+**Notes:** [Any clarifications, follow-up context, or rationale the user provided]
+
+---
+
+[Repeat for each area]
+
+## Claude's Discretion
+
+[List areas where user said "you decide" or deferred to Claude]
+
+## Deferred Ideas
+
+[Ideas mentioned during discussion that were noted for future phases]
+```