Files

Tom Boucher 3aaed8f5d7 test: replace deny-list parity tests with polarity-inverted live-registry (#3049 ) (#3284 )

* test: reproduce Windows SDK not found after fresh npx install (#3211)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: red — docs-parity live-registry tests fail against stub helper (#3049)

Adds:
- tests/helpers/live-command-registry.cjs (stub: returns empty Set)
- tests/docs-parity-live-registry.test.cjs (new polarity-inverted test)
- tests/fixtures/live-command-registry/ (fixture .md files)

All parity and helper-contract tests fail because the stub returns an
empty registry. This is the intentional RED state before GREEN
implementation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(test-helpers): live-command-registry derives canonical tokens from commands/gsd/*.md (#3049)

Implements GREEN phase:
- tests/helpers/live-command-registry.cjs: walks commands/gsd/*.md, parses
  YAML frontmatter name: field, emits /gsd-slug, /gsd:slug, $gsd-slug per
  command. Memoized per process. Fails loud on malformed frontmatter (k302).
- tests/docs-parity-live-registry.test.cjs: updated with INTERNAL_COMPONENT_SLUGS
  exemption for path-component and placeholder tokens (gsd-build from GitHub
  org URLs, gsd-workspaces from ~/gsd-workspaces/ paths, gsd-tools from
  bin/gsd-tools.cjs paths, etc.)

Docs drift caught and fixed:
- ns-* rename: /gsd-ns-workflow→/gsd-workflow etc. in COMMANDS, FEATURES,
  INVENTORY, USER-GUIDE (6 commands across 4 English files)
- /gsd-scan → /gsd-map-codebase --fast (FEATURES, INVENTORY, USER-GUIDE)
- /gsd-note → /gsd-capture (FEATURES, issue-driven-orchestration, ja-JP, ko-KR)
- /gsd-do → /gsd-fast (FEATURES, ja-JP, ko-KR)
- /gsd-from-gsd2 → /gsd-import --from-gsd2 (CLI-TOOLS, FEATURES, INVENTORY)
- /gsd-verify-phase → /gsd-validate-phase (STATE-MD-LIFECYCLE)
- /gsd-settings-integrations → /gsd-settings or /gsd-config --integrations (CLI-TOOLS)
- /gsd-dev-preferences removed from profile-user artifact lists (AGENTS, COMMANDS,
  FEATURES in English, ja-JP, ko-KR)
- /gsd-select-framework removed from gsd-framework-selector spawner list
  (AGENTS, INVENTORY)

All 28 new tests pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(test): replace deny-list parity tests with polarity-inverted live-registry approach (#3049)

- Delete bug-3010-reapply-patches-references.test.cjs (hardcoded deny-list)
- Delete bug-3029-3034-stale-command-routes.test.cjs (hardcoded deny-list)
- Delete bug-3042-3044-research-flag-and-stale-refs.test.cjs (deny-list + frontmatter checks)
- Add tests/skill-frontmatter-contract.test.cjs (frontmatter structural checks extracted from deleted file)
- Update tests/commands-doc-parity.test.cjs to derive slug from name: frontmatter field
  instead of filename, so ns-* commands resolve to their actual deployed tokens

Closes #3049

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: annotate commands-doc-parity with source-text-is-the-product exemption (#3049 lint fix)

The readFileSync on commands/gsd/*.md reads product markdown whose deployed
text IS what the user sees — content.startsWith('---') detects YAML frontmatter
in those files, not source-code structure. Add the allow-test-rule exemption
matching the same rationale used in docs-parity-live-registry.test.cjs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: walk docs/** recursively to cover nested locale trees (CR finding 7)

Replaced the non-recursive listMdFiles() with a hand-rolled DFS walker
compatible with Node 20+. Surfaces unreadable-directory errors as stderr
warnings (PRED.k302) rather than silently skipping.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: annotate live-command-registry helper and commands-doc-parity with source-text exemptions (CR findings 6, 8)

Adds allow-test-rule comments to suppress lint-no-source-grep false
positives on YAML frontmatter structure checks in both files.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: anchor --research-phase assertions to arg-parsing section and verify combined refresh (CR findings 9, 10)

Finding 9: scopes --research-phase check to within 1200 chars of the flag
description section header, preventing false positives from prose mentions.

Finding 10: tightens the force-refresh assertion to require BOTH --research
and force/refresh semantics within the --research-phase description section,
verifying the combined-mode contract rather than standalone --research presence.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: fix execSync mock to accept opts parameter, forward to saved implementation (CR finding 5)

The mock at line 212 dropped the options parameter when delegating to
savedExecSync. Updated to (cmd, opts) signature and pass opts through.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: correct routing entrypoint, --fast default, /gsd-review collision, verifying-stage mapping (CR findings 1-4)

Finding 1: Change Freeform Routing command from /gsd-fast to /gsd-progress --do.
/gsd-fast is the inline trivial-task executor, not the routing entrypoint.

Finding 2: Clarify that /gsd-map-codebase --fast REQ-SCAN-02 default (tech+arch)
runs as a single combined-focus agent, resolving the contradiction with REQ-SCAN-01.

Finding 3: Rename the namespace router /gsd-review to /gsd-quality across all docs,
command file, and help.md to eliminate the naming collision with the concrete
cross-AI peer-review command (review.md, name: gsd:review).

Finding 4: Replace /gsd-validate-phase with /gsd-verify-work in the STATE-MD-LIFECYCLE.md
verifying-stage table. /gsd-validate-phase is the retroactive Nyquist-validation
flow, not the normal phase-verification step.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs+test: fix locale doc drift surfaced by recursive walker (CR finding 7 follow-up)

The recursive listMdFiles() walker newly covered docs/**/*.md subdirs.
Stale command references in locale docs are now caught and fixed:

- docs/zh-CN/references/model-profiles.md: remove /gsd-set-profile (deleted command);
  config.json is the current mechanism
- docs/zh-CN/references/ui-brand.md: remove /gsd-alternative-1/2 template placeholders
- docs/{ja-JP,ko-KR,pt-BR}/superpowers/specs/2026-03-20-*: replace
  /gsd-new-workspace, /gsd-list-workspaces, /gsd-remove-workspace with
  /gsd-workspace --new / --list / --remove (consolidated in #2790)

Also adds smoke- and alternative-{1,2} to INTERNAL_COMPONENT_SLUGS (filesystem
path and template placeholder patterns, not slash commands) and introduces
listEnglishMdFiles() to scope the English parity check to docs/ excluding
locale subdirectories (which have their own per-locale describe blocks).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add bash language tag to fenced code blocks in ja-JP and ko-KR workspace specs (CR round 2)

Satisfies MD040 fenced-code-language requirement. These blocks contain
shell commands and were missing the language specifier.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-09 02:49:19 -04:00

9.3 KiB

Raw Blame History

Issue-Driven Orchestration with GSD

Status: stable workflow guide Audience: developers who track work in GitHub Issues, Linear, Jira, or similar issue trackers and want to drive AI-assisted implementation through GSD's existing primitives.

What this guide is

A recipe for combining commands GSD already ships into an issue-tracker → workspace → plan/execute → verify/review → PR loop. It is documentation only. No new commands, no daemon, no tracker integration — every command referenced below already exists in GSD today.

The shape is inspired by OpenAI's open-source Symphony orchestration reference (repository). GSD does not vendor or wrap Symphony. The orchestration concepts map cleanly onto primitives GSD already exposes; this guide just spells the mapping out so you can adopt the pattern without writing glue code or bypassing GSD's safety gates.

Why this exists

GSD has the building blocks for issue-driven AI development — /gsd-workspace --new, /gsd-manager, /gsd-autonomous, /gsd-verify-work, /gsd-review, /gsd-ship, plus STATE.md and the phase artifact suite — but no guide that walks through how to drive them from a single tracker issue without writing custom orchestration scripts. Without that guide the failure modes are:

Underuse: developers run discuss/plan/execute manually and never reach for /gsd-manager or /gsd-autonomous even when their work pattern fits.
Workaround scripts: developers wire ad-hoc shell loops between their tracker and claude invocations, bypassing STATE.md, the phase manifest, and the verification gates.

This guide makes the canonical loop discoverable.

Concept mapping

Each row maps a Symphony-style orchestration concept to the GSD primitive that already serves it. Use this table as a translation key when reading Symphony docs, blog posts, or third-party orchestration write-ups.

Symphony concept	GSD primitive
`WORKFLOW.md` (top-level intent)	`ROADMAP.md` (project intent), `STATE.md` (live status), phase `CONTEXT.md` (per-phase scope), phase `PLAN.md` (executable steps)
One isolated agent workspace per task	`/gsd-workspace --new --strategy worktree`
Agent dispatch and concurrency	`/gsd-manager` (interactive dashboard), `/gsd-autonomous` (unattended)
Per-phase plan and discuss steps	`/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase`
Proof-of-work / test evidence	`/gsd-verify-work` (UAT.md persisted across `/clear`)
Adversarial review	`/gsd-review` (cross-AI peer review of plans)
Human merge gate	`/gsd-ship` (creates PR, optional code review, prepares merge)
Follow-up capture	`/gsd-capture`, `/gsd-capture --seed`, `/gsd-new-milestone`, or a manually opened tracker issue
Concurrency control	Manager / background-agent semantics (no always-on poller)

The mapping is one-way: GSD owns the safety gates (verification, human review, explicit confirmation for follow-up creation). Symphony's "continuous orchestration" framing is intentionally not adopted — see Non-goals.

End-to-end flow

The canonical issue → PR loop, written so it can run from a single tracker issue end-to-end. Replace bracketed placeholders before running.

Pick the tracker issue. Choose one issue from your tracker (GitHub, Linear, etc.) that is well-scoped enough for autonomous implementation — bounded scope, observable acceptance criteria, no upstream dependencies that block execution.
Map to a GSD phase. If the issue maps onto an existing phase in ROADMAP.md, select it. If not, run /gsd-new-milestone (for a new milestone of related issues) or open a phase via /gsd-phase / /gsd-phase --insert. Capture the tracker issue URL in the phase's CONTEXT.md so traceability survives compaction.
Create an isolated workspace. Run /gsd-workspace --new --strategy worktree <slug> to spin up a git worktree with an independent .planning/ directory. The worktree is the safety boundary: any exploration, partial commits, or aborted plans stay outside main.
Run discuss → plan → execute through GSD. From inside the workspace, run /gsd-discuss-phase to clarify ambiguities, /gsd-plan-phase to produce PLAN.md, and either /gsd-manager (interactive dashboard) or /gsd-execute-phase / /gsd-autonomous (unattended) to implement. Avoid driving raw claude invocations from outside GSD — that bypasses STATE.md updates and the phase manifest.
Demand proof-of-work. Run /gsd-verify-work to walk the user through UAT against the phase's acceptance criteria. Tests, screenshots, log captures, and config diffs are all recorded in UAT.md, which persists across /clear and feeds gaps into /gsd-plan-phase --gaps when verification surfaces missed scope.
Pass through the review and ship gates. Run /gsd-review to get adversarial peer review of the plan from independent AI CLIs (catches blind spots model-by-model), then /gsd-ship to open the PR with a rich body assembled from the planning artifacts. Both gates require a human decision before anything reaches the remote.
Capture follow-up work explicitly. Use /gsd-capture for inline notes, /gsd-capture --seed for ideas worth a future phase, or /gsd-new-milestone for a coherent group of follow-ups. Creating a tracker issue from a discovered follow-up requires explicit user confirmation — GSD does not post to remote trackers automatically.

When the PR merges, the loop closes. Auto-close keywords in the PR body (Closes #NNN / Fixes #NNN) close the tracker issue at merge time.

Safety boundaries

The loop is safe because four invariants hold by construction:

Isolated worktrees. Every issue runs in a /gsd-workspace --new worktree, so partial work, aborted plans, and exploratory commits never touch main. gsd-local-patches/ is the recovery surface if a worktree's hand-edits need to come back across an update.
Explicit human review. /gsd-review and /gsd-ship both stop for human approval. There is no auto-merge and no auto-PR-from-execution path. If you want to remove the human gate for a specific repository, that is your branch-protection / merge-queue policy decision, not something GSD opts into for you.
No automatic public posting. GSD never opens, comments on, or closes a tracker issue without an explicit user-initiated command. Follow-up capture defaults to local artifacts (notes, seeds, milestones); pushing back to the tracker is a separate manual step.
Verification before ship. /gsd-verify-work's UAT.md must record evidence before /gsd-ship is run. The recommended discipline is to treat verification_failed as a blocker even when the implementation looks correct — the failure usually surfaces a missed acceptance criterion, not a flaky test.

If any of these invariants is bypassed (e.g. running claude directly against the worktree, skipping /gsd-verify-work, or scripting issue creation through the tracker API without user confirmation), the guarantees of this guide do not apply.

Non-goals

This guide deliberately does not propose any of the following. They are listed here so future contributors don't re-litigate them in code review:

No vendoring or copying Symphony code. GSD reuses its own primitives. The mapping above is conceptual; no Symphony-derived source ships in this repo.
No long-running daemon. GSD does not poll GitHub or Linear. The manager and autonomous workflows handle concurrency through background-agent semantics, not a daemon.
No mandatory tracker dependency. The loop works without any tracker integration. The "tracker issue" step is a human input — the URL goes into CONTEXT.md. GSD has no opinion about which tracker you use, or whether you use one at all.
No bypass of verification, review, or human decision gates. Even when running /gsd-autonomous, the verification and review gates still fire. The "autonomous" label refers to phase-to-phase progression, not to skipping human approval.
No expansion of the default skill / command surface. Every command referenced in this guide already exists. This guide is a documentation surface, not a feature surface.

Possible future follow-up

If maintainer experience with this loop justifies it, a separate approved-enhancement could later add a minimal tracker bridge:

Importing one GitHub or Linear issue into a GSD workspace / phase.
Exporting UAT.md evidence as a comment on the source issue.
Generating follow-up tracker issues from /gsd-capture --seed output.

Each of those would be its own enhancement proposal because each adds integration surface and ongoing maintenance burden. They are out of scope for this guide.

docs/USER-GUIDE.md — task-oriented walkthroughs of individual commands referenced above.
docs/COMMANDS.md — full reference for /gsd-* commands.
docs/FEATURES.md — feature-level capability matrix (workspaces, manager, autonomous, verify, review, ship).
docs/ARCHITECTURE.md — phase-artifact lifecycle and STATE.md mechanics.

9.3 KiB Raw Blame History