msd-core/commands/gsd/plan-phase.md at 9e2ef2c94dea3f1267deba570c9a423fb38c2f85

Files

Tom Boucher b866b95296 fix(#921,#922): orchestrators must not fork; plan-phase Agent gate is attempt-based (#926 )

`context: fork` strips the `Agent` tool from a subagent's environment.
Spawning orchestrators (`/gsd-autonomous`, `/gsd-execute-phase`,
`/gsd-plan-phase`) depend on `Agent` to dispatch sub-agents; running
them forked silently disables the core capability they exist to provide
(#921). Remove `context: fork` from all three command frontmatter files.
`effort: xhigh` (introduced by #769) is preserved.

The `<runtime_compatibility>` Agent-availability guard added by #913 was
checking whether `Agent` was present *before* attempting the call. On
runtimes where the tool list is dynamically resolved this produced
false-negative aborts in sessions that have the tool (#922). Replace
the introspection-based pattern with an attempt-based gate: always
attempt the `Agent()` call; stop only if a real tool-unavailable error
is returned. This preserves #853's backgrounded-session close-off and
#913's intent of preventing inline role-collapse, while eliminating
false negatives.

Tests updated: enh-769-context-fork-effort.install.test.cjs asserts the
three orchestrators lack `context: fork` and that the converter still
passes the field through for non-orchestrator commands; plan-phase-drift-
guard.test.cjs adds four assertions for the attempt-based gate language;
workflow-size-budget unchanged (budgets not exceeded).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-09 08:42:25 -04:00

3.8 KiB

Raw Blame History

name, description, argument-hint, effort, allowed-tools, requires

name

description

argument-hint

effort

allowed-tools

requires

gsd:plan-phase

Create detailed phase plan (PLAN.md) with verification loop

[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]

xhigh

Read

Write

Bash

Glob

Grep

Agent

AskUserQuestion

WebFetch

mcp__context7__*

discuss-phase

phase

review

update

Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.

Default flow: Research (if needed) → Plan → Verify → Done

Research-only mode (--research-phase <N>): Spawn gsd-phase-researcher for phase N, write RESEARCH.md, then exit before the planner runs. Useful for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops where iterating on research alone is dramatically cheaper than re-spawning the planner. Replaces the deleted research-phase command (#3042).

Research-only modifiers:

No flag — when RESEARCH.md already exists, auto-uses it: emits a one-line notice and exits cleanly, no prompt.
--research — force-refresh: re-spawn the researcher unconditionally, no prompt. Bypasses the existing-RESEARCH.md auto-use path.
--view — view-only: print existing RESEARCH.md to stdout. Does not spawn the researcher. Cheapest mode for the correction-without-replanning loop. If no RESEARCH.md exists yet, errors with a hint to drop --view.

Orchestrator role: Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results.

<execution_context> @~~/.claude/gsd-core/workflows/plan-phase.md @~~/.claude/gsd-core/references/ui-brand.md </execution_context>

<runtime_note> Copilot (VS Code): Use vscode_askquestions wherever this workflow calls AskUserQuestion. They are equivalent — vscode_askquestions is the VS Code Copilot implementation of the same interactive question API. Do not skip questioning steps because AskUserQuestion appears unavailable; use vscode_askquestions instead. </runtime_note>

Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)

Flags:

--research — Force re-research even if RESEARCH.md exists
--skip-research — Skip research, go straight to planning
--gaps — Gap closure mode (reads VERIFICATION.md, skips research)
--skip-verify — Skip verification loop
--prd <file> — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
--ingest <path-or-glob> — Use one or more ADR files instead of discuss-phase. Parses locked decisions + scope fences into CONTEXT.md automatically. Skips discuss-phase entirely.
--ingest-format <auto|nygard|madr|narrative> — Optional ADR parser format override (auto default).
--reviews — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by /gsd:review)
--text — Use plain-text numbered lists instead of TUI menus (required for /rc remote sessions)
--mvp — Vertical MVP mode. Planner organizes tasks as feature slices (UI→API→DB) instead of horizontal layers. On Phase 1 of a new project, also emits SKELETON.md (Walking Skeleton). Can be persisted on a phase via **Mode:** mvp in ROADMAP.md.

Normalize phase input in step 2 before any directory lookups.

Execute end-to-end. Preserve all workflow gates (validation, research, planning, verification loop, routing).

3.8 KiB Raw Blame History

3.8 KiB

Raw Blame History