diff --git a/.changeset/1143-claude-orchestration-capability.md b/.changeset/1143-claude-orchestration-capability.md new file mode 100644 index 000000000..d87aae625 --- /dev/null +++ b/.changeset/1143-claude-orchestration-capability.md @@ -0,0 +1,5 @@ +--- +type: Added +pr: 2044 +--- +**A default-off, BETA, claude-only "Claude orchestration" capability** — adopts Claude Code's Workflow tool (`/effort ultracode`, Agent SDK ≥ v0.3.149) as an optional parallel-execution backend for the GSD loop, restoring the wave parallelism + plan-checker + verifier that the #853 backgrounded-agent nesting limitation forces inline on Claude Code, and folding the existing `gsd-ultraplan-phase` plan-offload under the same runtime gate. When `claude_orchestration.enabled` is on AND the runtime is Claude AND the Workflow tool is detected AND the Agent SDK meets the floor (`claude_orchestration.min_agent_sdk_version`, default `0.3.149`), `execute-phase` emits a generated Workflow script (`waves → parallel() barriers`, `plans → agent({ agentType: 'gsd-executor', isolation: 'worktree' })`, `files_modified overlap → separate sequential stages`, `resumeFromRunId` wired to the phase run id, shared `budget` pool) that composes the SAME executor agent + worktree isolation the inline path uses, so artifacts/commits are produced identically. Detection is pure and fail-closed (any miss → inline), so on any runtime lacking the Workflow tool behaviour is byte-identical to today. Adds a pure module `gsd-core/bin/lib/claude-orchestration.cjs` (`detectWorkflowBackend`, `emitWorkflowScript`), the `capabilities/claude-orchestration/` declaration with two gated loop contributions (`execute:wave:post`, `plan:post`) and a `claude-orchestration` command family (`gsd-tools claude-orchestration detect-backend|emit-workflow`), federated config keys, and an ADR-1143 implementation amendment. (#1143) diff --git a/.changeset/1921-verify-work-gap-recovery.md b/.changeset/1921-verify-work-gap-recovery.md new file mode 100644 index 000000000..776f031bb --- /dev/null +++ b/.changeset/1921-verify-work-gap-recovery.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2025 +--- +**`/gsd:verify-work` preserves verification state across gap-closure execution and no longer auto-promotes deferred follow-ups into blocking gaps** — resuming after `/gsd:execute-phase --gaps-only` used to lose the verification state: the UAT `## Gaps` still read `status: failed` even after their fix plans executed, so verify-work re-diagnosed them as fresh blockers, spawned a new gap plan, and reported only the new plan as verified. A state contract now links each gap to its fix plan: every UAT gap carries a stable `gap_id` (`G-{phase}-{N}`), gap-closure plans tag the ids they address in their frontmatter (`gap_ids: […]`), and a new `reconcile_gaps` step on resume marks a gap `status: resolved` when its plan has a matching `*-SUMMARY.md` — so fixed gaps aren't re-diagnosed and the phase can close. Separately, a deferred-follow-up branch captures future-work ideas (signals like "later", "next version", "out of scope") into a `## Deferred Follow-Ups` section instead of creating a blocking gap/plan. (#1921) diff --git a/.changeset/2002-cli-self-healing-runtime-build.md b/.changeset/2002-cli-self-healing-runtime-build.md new file mode 100644 index 000000000..3e2f35507 --- /dev/null +++ b/.changeset/2002-cli-self-healing-runtime-build.md @@ -0,0 +1,6 @@ +--- +type: Changed +pr: 2036 +--- + +**The GSD CLI now self-heals a missing runtime build.** The compiled `gsd-core/bin/lib/*.cjs` modules are gitignored build artifacts (ADR-457) that ship prebuilt in the npm tarball but are absent on a Claude Code plugin-marketplace / git-clone install, which never runs `npm run build:lib`. Previously every command died at load with `Cannot find module './lib/cli-exit.cjs'`. The `gsd-tools` entrypoint now detects the missing output and compiles it once, on demand (lock-guarded so parallel invocations don't race), then proceeds — a single no-op check on the already-built npm path. When TypeScript is genuinely unavailable it prints an actionable `npm install && npm run build:lib` message instead of crashing. diff --git a/.changeset/2012-phase-complete-progress-row.md b/.changeset/2012-phase-complete-progress-row.md new file mode 100644 index 000000000..3bc84044c --- /dev/null +++ b/.changeset/2012-phase-complete-progress-row.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2032 +--- +**`phase.complete` now updates the `## Progress` rollup row even when an earlier phase-numbered table precedes it** — the Progress-row writer used a non-global regex that matched *any* table row starting with the phase number, so it bound to the first such row (e.g. a `| Phase | Requirements | Count |` coverage table), no-op'd on the wrong 3-column row, and never reached the real Progress row. The regex is now scoped to the `## Progress` section so it binds to the correct table. The command still returned `roadmap_updated: true` (that field is `fs.existsSync(ROADMAP.md)`), masking the silent failure. (#2012) diff --git a/.changeset/2017-context7-plugin-grant-prefix.md b/.changeset/2017-context7-plugin-grant-prefix.md new file mode 100644 index 000000000..91eb0250b --- /dev/null +++ b/.changeset/2017-context7-plugin-grant-prefix.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2029 +--- +**context7 now works for plugin-marketplace installs (8 agents regained doc lookup)** — the agents granted only `mcp__context7__*`, which matches a standalone context7 MCP server but not the official Claude Code plugin-marketplace install (`context7@claude-plugins-official`), whose tools are named `mcp__plugin_context7_context7__*`. The grant never matched, so advisor/ai/domain/phase/project/ui-researcher + planner + executor silently lost documentation lookup and fell back to WebSearch. All 8 agents now grant both forms, the researcher profile table is updated, and a parity guard asserts no agent grants the standalone form without the plugin form. (#2017) diff --git a/.changeset/2018-applysurface-empty-manifest-agents.md b/.changeset/2018-applysurface-empty-manifest-agents.md new file mode 100644 index 000000000..68ddf4024 --- /dev/null +++ b/.changeset/2018-applysurface-empty-manifest-agents.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2031 +--- +**`applySurface` no longer deletes every `gsd-*` agent when the skills manifest resolves empty** — the agent-prune loop in `_syncGsdDir` deleted any `gsd-*.md` not in the staged set, and when the manifest was empty/unresolvable (null manifest, no array entries, no `files` key, or an unresolvable install source root), the staged set was empty → every agent was pruned. Skills were guarded by `pruneSkillDirs`'s manifest-membership check (conservative preservation on empty manifest); agents had no equivalent. The agent-prune loop is now skipped when the manifest is empty/absent, so agents are preserved while copy (adding genuinely new agents) still runs. (#2018) diff --git a/.changeset/2019-planning-config-learnings-path.md b/.changeset/2019-planning-config-learnings-path.md new file mode 100644 index 000000000..110e8ef95 --- /dev/null +++ b/.changeset/2019-planning-config-learnings-path.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2026 +--- +**`planning-config.md` global-learnings path corrected to `~/.gsd/knowledge/`** — the `features.global_learnings` row directed users to `~/.gsd/learnings/`, but the implementation (`src/learnings.cts`, `execute-phase.md`) stores and reads global learnings from `~/.gsd/knowledge/`. Anyone following the docs to inspect, back up, or seed their global learnings looked in a directory the code never touches. (#2019) diff --git a/.changeset/2020-executor-dead-sdk-ref.md b/.changeset/2020-executor-dead-sdk-ref.md new file mode 100644 index 000000000..2491f753e --- /dev/null +++ b/.changeset/2020-executor-dead-sdk-ref.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2027 +--- +**Removed dead SDK file references from runtime-loaded markdown that triggered an infinite `find.exe` storm on Windows** — `agents/gsd-executor.md` pointed at `sdk/src/query/QUERY-HANDLERS.md` and `gsd-core/workflows/reapply-patches.md` at `sdk/dist/cli.js`, both retired with the SDK package (ADR-0174). AI runtimes that resolve doc references by filesystem search ran `find / -iname …`; on Git Bash for Windows `/` maps to the drive root, so `find.exe` traversed the whole disk (14h+, orphaned processes, 4M+ open handles each, unkillable). The references now resolve to live paths, and a new regression guard asserts no `sdk/src|sdk/dist|sdk/handlers` file references remain in agents/workflows/references markdown. (#2020) diff --git a/.changeset/2022-roadmap-verify-gate.md b/.changeset/2022-roadmap-verify-gate.md new file mode 100644 index 000000000..bd31bfd92 --- /dev/null +++ b/.changeset/2022-roadmap-verify-gate.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2030 +--- +**`roadmap update-plan-progress` no longer checks the phase checkbox without verification** — the command stamped the phase-level ROADMAP checkbox and completion date the moment the last plan summary landed (called routinely after every wave and every plan), with **no verification gate** — unlike `phase.complete` which correctly requires `readVerificationStatus(...).status === 'passed'`. Now `isComplete` requires both all plan summaries AND a passed verification, matching the `cmdPhaseComplete` contract, so the checkbox only fires after `gsd-verifier` has confirmed the phase. (#2022) diff --git a/.changeset/gentle-badgers-roar.md b/.changeset/gentle-badgers-roar.md new file mode 100644 index 000000000..a20eb5765 --- /dev/null +++ b/.changeset/gentle-badgers-roar.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2048 +--- +**`model_overrides` Claude model IDs now resolve to Agent-tool aliases on the claude runtime** — a full Claude model ID (e.g. `claude-sonnet-5`) in `model_overrides` was returned verbatim and silently dropped by the Claude Agent tool (whose `model` parameter documents only tier aliases), causing the spawned subagent to inherit the parent session model instead of the configured one. It now maps to the tier alias (`sonnet`/`opus`/`haiku`/`fable`), consistent with the `model_policy` path (#1144). Bare aliases, non-Claude values, and non-Claude runtimes are unchanged; a Claude ID with no alias warns once and falls through to tier resolution. (#2041) diff --git a/.changeset/plucky-jays-dart.md b/.changeset/plucky-jays-dart.md new file mode 100644 index 000000000..0a183d3c1 --- /dev/null +++ b/.changeset/plucky-jays-dart.md @@ -0,0 +1,5 @@ +--- +type: Changed +pr: 2040 +--- +**`/gsd:surface` and `--materialize` now produce byte-identical agent output to a fresh install** — surface-path agents for descriptor-driven runtimes (cursor, windsurf, augment, trae, codebuddy, copilot, antigravity) now receive the same path-prefix rewrite, Co-Authored-By attribution, runtime-specific conversion, and body normalization as the install path. Copilot and Antigravity agents are now installed via the descriptor-driven path (copilot agents get the `.agent.md` filename rename). Cline remains on the inline loop (rules-only local branch). (#1575) diff --git a/.changeset/steady-ibex-run.md b/.changeset/steady-ibex-run.md new file mode 100644 index 000000000..bf1b37a3b --- /dev/null +++ b/.changeset/steady-ibex-run.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 2049 +--- +**Skill-bearing capabilities now surface correctly on flat command-layout installs** — on an install using the flat `commands/gsd-.md` source layout (e.g. a Claude Code local project install with no `commands/gsd/` subdir), every skill-bearing capability (`nyquist`, `code-review`, `security`, `ui`, `mempalace`, `ai-integration`, `profile-pipeline`) was silently reported `surfaced:false`/`enabled:false`/`active:false`, so their loop hooks (`verify:post`, `execute:post`, etc.) never fired even with the corresponding `workflow.*` toggle on. The skill-manifest resolver now detects the flat layout and produces the same stems the nested `commands/gsd/*.md` loader does. (#1858) diff --git a/.changeset/zcode-runtime-1925.md b/.changeset/zcode-runtime-1925.md new file mode 100644 index 000000000..16adbc0e4 --- /dev/null +++ b/.changeset/zcode-runtime-1925.md @@ -0,0 +1,5 @@ +--- +type: Added +pr: 2039 +--- +**ZCode (Z.ai) is now an installable runtime** — a desktop Agentic Development Environment for the GLM-5.2 model can now be targeted with `--zcode`, landing GSD skills at `~/.zcode/skills//SKILL.md` plus slash commands and subagents. ZCode ships as a pure declarative capability descriptor (`capabilities/zcode/capability.json`) with zero hardcoded `runtime === 'zcode'` branches, reusing the Claude skill converter — the de-hardcoded, data-driven runtime path that 1.7.0 (ADR-1016 / ADR-1239) enables. (#1925) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f5fabdb5c..b99a81103 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "gsd-core", "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "source": "./", "author": { "name": "open-gsd", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7d2215103..de21c6772 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gsd-core", "displayName": "GSD Core", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.", "author": { "name": "open-gsd", diff --git a/CONTEXT.md b/CONTEXT.md index f44f91742..fa1df0b0b 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -220,6 +220,8 @@ ADR-1244 Phase 4 (D5+D6) orchestration seam (`gsd-core/bin/lib/capability-lifecy ### Capability Command Dispatch ADR-1244 Phase 5 (D7) registry-driven dispatch of capability command families. First-party families (`graphify`/`intel`/`audit`, shipped in `bin/lib/`) dispatch via `dispatchCapabilityCommand` (`gsd-core/bin/gsd-tools.cjs`) against the FROZEN `capability-registry.cjs` `commandFamilies` (confined to `bin/lib/`) — unchanged. Third-party (installed overlay) families dispatch via `dispatchOverlayCapabilityCommand`: after the first-party path returns false, it calls `loadRegistry({ includeInstalled, cwd })` and dispatches a family iff its `capId` is in `_overlay.commandRoots` — which `capability-loader.cjs` populates ONLY for accepted overlay capabilities that declare `commands` AND pass the loader's activation gate (a **committed** ledger entry, present and non-`_pending`, PLUS — for PROJECT scope — a matching user consent record in the Capability Consent Store; GLOBAL scope needs no consent record). A bundle dropped on disk with no install (no ledger entry) or no on-this-machine consent is NOT command-dispatchable. The router module is `require()`'d FROM the capability's install root via `defaultRequireFromInstallRoot` (bare-`.cjs` basename + `realpath` containment, rejecting `..` traversal and symlink escape); same own-property/function/sync-only guards as the first-party path. Wired into the `runCommand` default arm before "Unknown command". A repo-planted project ledger no longer activates anything on its own (#1459) — see `docs/explanation/capability-trust-model.md` "project-scope trust boundary". +### Claude Orchestration Capability +Default-off, BETA, claude-only Capability (`capabilities/claude-orchestration/`, `role: feature`, `runtimeCompat.supported: ["claude"]`, `tier: full`, `activationKey: claude_orchestration.enabled`) adopting Claude Code's Workflow tool (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149) as an optional parallel-execution backend for the GSD loop, and folding the `gsd-ultraplan-phase` plan-offload under the same runtime gate (#1143; ADR-1143). Pure, fail-closed core in `gsd-core/bin/lib/claude-orchestration.cjs` (generated from `src/claude-orchestration.cts`): `detectWorkflowBackend({ runtimeId, hostIntegration, config, agentSdkVersion }) → { available, backend:'workflow'|'inline', reason }` (gate ladder: enabled → Claude → execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK → SDK ≥ floor; every miss degrades to `inline`, never throws); `emitWorkflowScript({ phaseDir, waves, runId, budgetTokens? }) → { ok, script, summary }` mapping waves → `parallel()` stage barriers, plans → `agent({ agentType:'gsd-executor', isolation:'worktree' })`, `files_modified` overlap → separate sequential stages (greedy first-fit), `resumeFromRunId` wired to the run id, shared `budget(tokens)`; all interpolated identifiers validated script-safe (no `"`,`\`,control chars) and briefs JSON-quoted (review anti-injection). Registers two loop contributions at WIRED points only (execute:wave:pre/execute:pre are declared but not rendered, same constraint external-job documents): `execute:wave:post into:executor` (Workflow-backend guidance) and `plan:post into:planner` (ultraplan ownership declaration), both `when: claude_orchestration.enabled`, `onError: skip`. Federated config keys (`claude_orchestration.enabled` default false, `execution_backend` enum auto|workflow|inline default auto, `min_agent_sdk_version` string default "0.3.149") live only in the registry — uninstall removes them cleanly. Pre-release versions of the floor compare below GA (SemVer precedence). Restores the wave parallelism + plan-checker + verifier that #853 forces inline on Claude Code; on any runtime lacking the Workflow tool, behaviour is byte-identical to today. BETA v1 ships detection + emission + declarative ultraplan ownership + a `claude-orchestration` command family (`gsd-tools claude-orchestration detect-backend|emit-workflow`, router `gsd-core/bin/lib/claude-orchestration-command-router.cjs` from `src/claude-orchestration-command-router.cts`); full install-profile migration of the ultraplan skill into `skills[]` is a follow-up (CLUSTERS/profile gate). Test anchors: `tests/claude-orchestration.test.cjs`, `tests/claude-orchestration-command-router.test.cjs`. ### Loop Extension Point A named, stable site on a host loop step (per-step `pre`/`post` plus per-wave in Execute; 12 total) where Capabilities register hooks. Three hook kinds: `step` (runs as its own sequenced unit), `contribution` (injects into the core step's prompt/context), and `gate` (checks and optionally blocks via a declared `blocking` flag). Each hook declares the artifacts it produces and consumes; hook order is derived by topological sort of that produces/consumes graph (capability-id tiebreak), which also defines data flow — file-artifact based, surviving `/clear` and fresh executor contexts. Hooks are surfaced by runtime resolution with concrete projection: the workflow calls a query that resolves the active hooks and returns fully-rendered, ordered markdown for the executor. Failure is default-resilient — a non-gate hook that errors is skipped with a warning; a hook may opt into `onError: halt`. Part of the Capability system. ADR-857 phase 3c ships the registry-consuming query layer: `gsd-core/bin/lib/loop-resolver.cjs` exposes `resolveLoopHooks({ point, registry, config })` (pure, no I/O), `renderLoopHooks(resolved)` (pure markdown renderer), and `cmdLoopRenderHooks(cwd, point, raw, opts)` (I/O entry point); activated via `gsd-tools loop render-hooks ` which emits `{ point, activeHooks[], rendered }`. Activation is driven by `when` (dotted config key resolved against `loadConfig`), with inline literal `__proto__`/`constructor`/`prototype` prototype-pollution guard. The first phase-6 cutovers wiring workflows to this query have landed — ui-phase at `plan:pre` and ui-review at `verify:post` (in `plan-phase.md`/`autonomous.md`); further per-feature cutovers are ongoing. diff --git a/QUICK-WINS-CONFIRMED-BUGS.md b/QUICK-WINS-CONFIRMED-BUGS.md deleted file mode 100644 index ac041691e..000000000 --- a/QUICK-WINS-CONFIRMED-BUGS.md +++ /dev/null @@ -1,73 +0,0 @@ -# Quick Wins: Confirmed-Bug Fixes - -**Status**: Active -**Started**: 2026-05-16 -**Owner**: Current session (Grok + user) -**Context**: Follow-up to `/gsd-inbox` triage on 2026-05-16 - -## Goal - -Land 6 high-signal, confirmed-bug issues that currently have **zero open pull requests**. These are the cleanest quick-win opportunities available in the public GitHub inbox right now. - -All six issues carry the `confirmed-bug` label, meaning the bug has been verified and a fix is explicitly welcome. - -## The 6 Issues (Prioritized) - -| # | Issue | Short Title | Type | Recommended Flow | Est. Effort | Status | Notes | -|---|-------|-------------|------|------------------|-------------|--------|-------| -| 1 | [#3583](https://github.com/open-gsd/gsd-core/issues/3583) | Claude skill install leaves `/gsd:` in `SKILL.md` body | Installer / Command namespace | PR 3629 (our branch) + competing 3586 | Small (1 file + test) | PR opened / Review | **Leading PR: 3629** (cristianuibar) — reviewed + hardened with CodeRabbit feedback (left-boundary regex + body-scoped guard). Competing PR 3586 has "needs changes" + "ci: failing". Issue still carries `confirmed-bug`. | -| 2 | [#3579](https://github.com/open-gsd/gsd-core/issues/3579) | `build-hooks.js` + npm publish omit graphify auto-update hook | Packaging / Build | `/gsd-quick` | Small | Not started | Classic "new feature missed in release artifact". Easy local verification. | -| 3 | [#3496](https://github.com/open-gsd/gsd-core/issues/3496) | `/gsd:update` changelog extraction skips intermediate versions | Workflow / Update logic | `/gsd-quick` or lightweight plan | Medium-small | Not started | Needs deterministic version-range helper. | -| 4 | [#3588](https://github.com/open-gsd/gsd-core/issues/3588) | Production `npm audit` has 1 high + 5 moderate advisories | Security / Dependencies | Direct + careful review | Medium | Not started | Transitive via `@anthropic-ai/claude-agent-sdk`. May need overrides. | -| 5 | [#3584](https://github.com/open-gsd/gsd-core/issues/3584) | Runtime `bin/lib/*.cjs` still emit `/gsd:` (larger piece deferred from #3583) | Runtime output / Slash formatter | Short plan first, then execute | Medium-Large | Not started | 16+ files. Design a centralized runtime-aware formatter. Do after #3583. | -| 6 | [#3340](https://github.com/open-gsd/gsd-core/issues/3340) | SDK publish lag — agent dir fix never shipped in `@opengsd/gsd-sdk@0.1.0` | Release / SDK publishing | Plan + coordination | Medium (release-focused) | Not started | Oldest. Mostly a publishing/versioning task. | - -## Execution Rules for This Batch - -- **Branch naming**: `fix/NNNN-short-description` (enforced by CI) -- **PR template**: Must use `.github/PULL_REQUEST_TEMPLATE/fix.md` -- **Linking**: `Fixes #NNNN` (or `Closes`) in the PR body -- **Changeset**: Required for all user-facing or security fixes -- **Testing**: All existing tests must pass + new coverage where the issue describes a gap -- **Clean context windows**: Each fix should preferably be driven from a fresh session using the prepared prompts (see session notes or ask for them) -- **GSD self-use**: For the small ones (#3583, #3579, #3496), using `/gsd-quick` (or `/gsd-fast`) inside the fix session is encouraged and appropriate. For #3584, a short planning step is recommended. - -## Status Legend - -- **Not started** — Issue claimed for this batch, no work begun -- **In progress** — Active work in a clean window -- **PR opened** — Pull request created and linked -- **Review** — Awaiting review / CI / merge fixes -- **Merged** — Landed on main -- **Blocked** — Needs input from maintainers or upstream - -## Current Status - -- [x] #3583 — **PR opened** (3629 leading after CodeRabbit review + hardening push; competing 3586 needs changes + CI failing) -- [ ] #3579 — Not started (cleanest next target — 0 PRs) -- [ ] #3496 — PR 3497 open (changes requested) -- [ ] #3588 — Not started -- [ ] #3584 — Not started (larger; deferred runtime cjs colon emissions) -- [ ] #3340 — Not started - -**Progress**: 0 / 6 merged (1 in active review) - -## Process Notes - -- These issues were identified during a `/gsd-inbox` run on 2026-05-16. -- At the time of creation of this file, zero of the six had open PRs. -- 2026-05-16 Grok session: Reviewed PR 3629 (our #3583 fix) for CodeRabbit comments. 1 critical was false-positive (scripts/ *is* published per package.json "files" + npm pack). Applied the 2 valid suggestions (bidirectional word-boundary lookbehind in `buildColonPattern` + body-only scope for the colon-ref regression guard in the test). Tests pass. Pushed hardening commit to the fork branch. Competing PR 3586 exists but is behind on CI/review status. -- Work is intended to be done in **parallel clean context windows** (one issue per fresh Claude/Codex/Gemini session) using dedicated prompts. -- After each fix is complete in its window, the resulting branch + PR description should be brought back here for final review and opening. -- This file serves as the single source of truth for the current batch while execution is in progress. It can be deleted or moved to `docs/archive/` once all six PRs are merged. - -## Related Artifacts - -- Inbox triage report: `/tmp/GSD-INBOX-TRIAGE-2026-05-16.md` (from the `/gsd-inbox` run) -- Full issue list with `confirmed-bug` label: `gh issue list --state open --label confirmed-bug` - ---- - -**Next action**: #3583 now has active PR(s) under review. Next clean quick win (0 PRs, small packaging effort, high value for recently-landed graphify feature): **#3579**. Validated via GitHub search: no PRs mention 3579. Ready for `/gsd-quick` or direct fix (update `scripts/build-hooks.js` HOOKS_TO_COPY + ensure `hooks/lib/` copy in installer + fix any publish filter). - -This document will be updated as status changes. \ No newline at end of file diff --git a/agents/gsd-advisor-researcher.md b/agents/gsd-advisor-researcher.md index b6fcf61c7..62d84bc7e 100644 --- a/agents/gsd-advisor-researcher.md +++ b/agents/gsd-advisor-researcher.md @@ -1,7 +1,7 @@ --- name: gsd-advisor-researcher description: Researches a single gray area decision and returns a structured comparison table with rationale. Spawned by discuss-phase advisor mode. -tools: Read, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__* +tools: Read, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__* color: cyan --- diff --git a/agents/gsd-ai-researcher.md b/agents/gsd-ai-researcher.md index e9df2d44b..9c9a66db3 100644 --- a/agents/gsd-ai-researcher.md +++ b/agents/gsd-ai-researcher.md @@ -1,7 +1,7 @@ --- name: gsd-ai-researcher description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator. -tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__* +tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*, mcp__plugin_context7_context7__* color: green # hooks: # PostToolUse: diff --git a/agents/gsd-domain-researcher.md b/agents/gsd-domain-researcher.md index 3b355b57a..701cb4022 100644 --- a/agents/gsd-domain-researcher.md +++ b/agents/gsd-domain-researcher.md @@ -1,7 +1,7 @@ --- name: gsd-domain-researcher description: Researches the business domain and real-world application context of the AI system being built. Surfaces domain expert evaluation criteria, industry-specific failure modes, regulatory context, and what "good" looks like for practitioners in this field — before the eval-planner turns it into measurable rubrics. Spawned by /gsd:ai-integration-phase orchestrator. -tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__* +tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__* color: purple # hooks: # PostToolUse: diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index 136fea55a..6f4ecc5fd 100644 --- a/agents/gsd-executor.md +++ b/agents/gsd-executor.md @@ -1,7 +1,7 @@ --- name: gsd-executor description: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command. -tools: Read, Write, Edit, Bash, Grep, Glob, Skill, mcp__context7__* +tools: Read, Write, Edit, Bash, Grep, Glob, Skill, mcp__context7__*, mcp__plugin_context7_context7__* color: yellow # hooks: # PostToolUse: @@ -24,7 +24,7 @@ Your job: Execute the plan completely, commit each task, create SUMMARY.md, upda When you need library or framework documentation, check in this order: -1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: +1. If Context7 MCP tools (`mcp__context7__*, mcp__plugin_context7_context7__*`) are available in your environment, use them: - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` @@ -691,7 +691,7 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails. -After SUMMARY.md, update STATE.md using `gsd-tools query` state handlers (named flags; see `sdk/src/query/QUERY-HANDLERS.md`): +After SUMMARY.md, update STATE.md using `gsd-tools query` state handlers (named flags): ```bash # Advance plan counter (handles edge cases automatically) diff --git a/agents/gsd-phase-researcher.md b/agents/gsd-phase-researcher.md index aeec0d9bf..00bd8ff21 100644 --- a/agents/gsd-phase-researcher.md +++ b/agents/gsd-phase-researcher.md @@ -1,7 +1,7 @@ --- name: gsd-phase-researcher description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator. -tools: Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__* +tools: Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__* color: cyan # hooks: # PostToolUse: diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index 3c8ece56e..18a792769 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -1,7 +1,7 @@ --- name: gsd-planner description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd:plan-phase orchestrator. -tools: Read, Write, Edit, Bash, Glob, Grep, Skill, WebFetch, mcp__context7__* +tools: Read, Write, Edit, Bash, Glob, Grep, Skill, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__* color: green # hooks: # PostToolUse: diff --git a/agents/gsd-project-researcher.md b/agents/gsd-project-researcher.md index adfa391b5..c3123e915 100644 --- a/agents/gsd-project-researcher.md +++ b/agents/gsd-project-researcher.md @@ -1,7 +1,7 @@ --- name: gsd-project-researcher description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators. -tools: Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__* +tools: Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__* color: cyan # hooks: # PostToolUse: diff --git a/agents/gsd-ui-researcher.md b/agents/gsd-ui-researcher.md index c75a54982..f48b1fb0c 100644 --- a/agents/gsd-ui-researcher.md +++ b/agents/gsd-ui-researcher.md @@ -1,7 +1,7 @@ --- name: gsd-ui-researcher description: Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator. -tools: Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__* +tools: Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__* color: purple # hooks: # PostToolUse: diff --git a/bin/install.js b/bin/install.js index 5c5cc1a2c..589ca0218 100755 --- a/bin/install.js +++ b/bin/install.js @@ -434,7 +434,7 @@ if (hasMinimal && _profileArgRaw) { function selectRuntimesFromArgs(runtimeArgs) { if (runtimeArgs.includes('--all')) { - return ['claude', 'kimi', 'kilo', 'opencode', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline']; + return ['claude', 'kimi', 'kilo', 'opencode', 'codex', 'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'zcode']; } if (runtimeArgs.includes('--both')) { return ['claude', 'opencode']; @@ -456,6 +456,7 @@ function selectRuntimesFromArgs(runtimeArgs) { if (runtimeArgs.includes('--kimi')) selected.push('kimi'); if (runtimeArgs.includes('--codebuddy')) selected.push('codebuddy'); if (runtimeArgs.includes('--cline')) selected.push('cline'); + if (runtimeArgs.includes('--zcode')) selected.push('zcode'); return selected; } @@ -579,7 +580,7 @@ const banner = '\n' + ' GSD Core ' + dim + 'v' + pkg.version + reset + '\n' + ' Git. Ship. Done.\n' + ' A meta-prompting, context engineering and spec-driven\n' + - ' development workflows for Claude Code, OpenCode, Kimi CLI, Kilo, Codex, Copilot, Antigravity, Cursor, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, Cline and CodeBuddy.\n'; + ' development workflows for Claude Code, OpenCode, Kimi CLI, Kilo, Codex, Copilot, Antigravity, Cursor, Windsurf, Augment, Trae, Qwen Code, Hermes Agent, Cline, CodeBuddy and ZCode.\n'; // Pure seam: parse --config-dir / -c from an arbitrary args array. // Returns the path string, '' for an empty equals-form value, or null when the @@ -636,7 +637,7 @@ if (hasUninstall) { // Show help if requested if (hasHelp) { - console.log(` ${yellow}Usage:${reset} npx ${pkg.name} [options]\n\n ${yellow}Options:${reset}\n ${cyan}-g, --global${reset} Install globally (to config directory)\n ${cyan}-l, --local${reset} Install locally (to current directory)\n ${cyan}--claude${reset} Install for Claude Code only\n ${cyan}--opencode${reset} Install for OpenCode only\n ${cyan}--kilo${reset} Install for Kilo only\n ${cyan}--codex${reset} Install for Codex only\n ${cyan}--kimi${reset} Install for Kimi CLI only\n ${cyan}--copilot${reset} Install for Copilot only\n ${cyan}--antigravity${reset} Install for Antigravity only\n ${cyan}--cursor${reset} Install for Cursor only\n ${cyan}--windsurf${reset} Install for Windsurf only\n ${cyan}--augment${reset} Install for Augment only\n ${cyan}--trae${reset} Install for Trae only\n ${cyan}--qwen${reset} Install for Qwen Code only\n ${cyan}--hermes${reset} Install for Hermes Agent only\n ${cyan}--cline${reset} Install for Cline only\n ${cyan}--codebuddy${reset} Install for CodeBuddy only\n ${cyan}--all${reset} Install for all runtimes\n ${cyan}-u, --uninstall${reset} Uninstall GSD (remove all GSD files)\n ${cyan}-c, --config-dir ${reset} Specify custom config directory\n ${cyan}-h, --help${reset} Show this help message\n ${cyan}--force-statusline${reset} Replace existing statusline config\n ${cyan}--portable-hooks${reset} Emit \$HOME-relative hook paths in settings.json\n (for WSL/Docker bind-mount setups; also GSD_PORTABLE_HOOKS=1)\n ${cyan}--profile=${reset} Install a named skill profile. Profiles:\n core — ${PROFILES.core.length} main-loop skills incl. phase (~130 desc tokens)\n standard — ${PROFILES.standard.length} skills incl. phase, review, config (~700)\n full — all skills (default)\n Composable: --profile=core,audit installs union of closures.\n Profile is persisted and respected by \`gsd update\`.\n ${cyan}--minimal${reset} Alias for --profile=core (back-compat).\n Cuts cold-start overhead from ~12k tokens to ~700.\n Alias: --core-only.\n\n ${yellow}Examples:${reset}\n ${dim}# Interactive install (prompts for runtime and location)${reset}\n npx ${pkg.name}\n\n ${dim}# Install for Claude Code globally${reset}\n npx ${pkg.name} --claude --global\n\n ${dim}# Install for Kilo globally${reset}\n npx ${pkg.name} --kilo --global\n\n ${dim}# Install for Codex globally${reset}\n npx ${pkg.name} --codex --global\n\n ${dim}# Install for Kimi CLI globally${reset}\n npx ${pkg.name} --kimi --global\n\n ${dim}# Install for Kimi CLI under ~/.kimi-code${reset}\n npx ${pkg.name} --kimi --global --config-dir ~/.kimi-code\n\n ${dim}# Install for Copilot globally${reset}\n npx ${pkg.name} --copilot --global\n\n ${dim}# Install for Copilot locally${reset}\n npx ${pkg.name} --copilot --local\n\n ${dim}# Install for Antigravity globally${reset}\n npx ${pkg.name} --antigravity --global\n\n ${dim}# Install for Antigravity locally${reset}\n npx ${pkg.name} --antigravity --local\n\n ${dim}# Install for Cursor globally${reset}\n npx ${pkg.name} --cursor --global\n\n ${dim}# Install for Cursor locally${reset}\n npx ${pkg.name} --cursor --local\n\n ${dim}# Install for Windsurf globally${reset}\n npx ${pkg.name} --windsurf --global\n\n ${dim}# Install for Windsurf locally${reset}\n npx ${pkg.name} --windsurf --local\n\n ${dim}# Install for Augment globally${reset}\n npx ${pkg.name} --augment --global\n\n ${dim}# Install for Augment locally${reset}\n npx ${pkg.name} --augment --local\n\n ${dim}# Install for Trae globally${reset}\n npx ${pkg.name} --trae --global\n\n ${dim}# Install for Trae locally${reset}\n npx ${pkg.name} --trae --local\n\n ${dim}# Install for Hermes Agent globally${reset}\n npx ${pkg.name} --hermes --global\n\n ${dim}# Install for Hermes Agent locally${reset}\n npx ${pkg.name} --hermes --local\n\n ${dim}# Install for Cline globally${reset}\n npx ${pkg.name} --cline --global\n\n ${dim}# Install for Cline locally${reset}\n npx ${pkg.name} --cline --local\n\n ${dim}# Install for CodeBuddy globally${reset}\n npx ${pkg.name} --codebuddy --global\n\n ${dim}# Install for CodeBuddy locally${reset}\n npx ${pkg.name} --codebuddy --local\n\n ${dim}# Install for all runtimes globally${reset}\n npx ${pkg.name} --all --global\n\n ${dim}# Install to custom config directory${reset}\n npx ${pkg.name} --kilo --global --config-dir ~/.kilo-work\n\n ${dim}# Install to current project only${reset}\n npx ${pkg.name} --claude --local\n\n ${dim}# Uninstall GSD from Cursor globally${reset}\n npx ${pkg.name} --cursor --global --uninstall\n\n ${yellow}Notes:${reset}\n The --config-dir option is useful when you have multiple configurations.\n It takes priority over CLAUDE_CONFIG_DIR / OPENCODE_CONFIG_DIR / KILO_CONFIG_DIR / CODEX_HOME / KIMI_CONFIG_DIR / COPILOT_CONFIG_DIR / COPILOT_HOME / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR / AUGMENT_CONFIG_DIR / TRAE_CONFIG_DIR / QWEN_CONFIG_DIR / HERMES_HOME / CLINE_CONFIG_DIR / CODEBUDDY_CONFIG_DIR environment variables.\n Kimi CLI defaults to the first existing generic skills root: ${cyan}~/.config/agents/skills${reset}, then ${cyan}~/.agents/skills${reset}; if neither exists, GSD creates ${cyan}~/.config/agents${reset}.\n Use ${cyan}--config-dir ~/.kimi-code${reset} or ${cyan}KIMI_CONFIG_DIR=~/.kimi-code${reset} for brand-specific Kimi installs.\n`); + console.log(` ${yellow}Usage:${reset} npx ${pkg.name} [options]\n\n ${yellow}Options:${reset}\n ${cyan}-g, --global${reset} Install globally (to config directory)\n ${cyan}-l, --local${reset} Install locally (to current directory)\n ${cyan}--claude${reset} Install for Claude Code only\n ${cyan}--opencode${reset} Install for OpenCode only\n ${cyan}--kilo${reset} Install for Kilo only\n ${cyan}--codex${reset} Install for Codex only\n ${cyan}--kimi${reset} Install for Kimi CLI only\n ${cyan}--copilot${reset} Install for Copilot only\n ${cyan}--antigravity${reset} Install for Antigravity only\n ${cyan}--cursor${reset} Install for Cursor only\n ${cyan}--windsurf${reset} Install for Windsurf only\n ${cyan}--augment${reset} Install for Augment only\n ${cyan}--trae${reset} Install for Trae only\n ${cyan}--qwen${reset} Install for Qwen Code only\n ${cyan}--hermes${reset} Install for Hermes Agent only\n ${cyan}--cline${reset} Install for Cline only\n ${cyan}--codebuddy${reset} Install for CodeBuddy only\n ${cyan}--zcode${reset} Install for ZCode only\n ${cyan}--all${reset} Install for all runtimes\n ${cyan}-u, --uninstall${reset} Uninstall GSD (remove all GSD files)\n ${cyan}-c, --config-dir ${reset} Specify custom config directory\n ${cyan}-h, --help${reset} Show this help message\n ${cyan}--force-statusline${reset} Replace existing statusline config\n ${cyan}--portable-hooks${reset} Emit \$HOME-relative hook paths in settings.json\n (for WSL/Docker bind-mount setups; also GSD_PORTABLE_HOOKS=1)\n ${cyan}--profile=${reset} Install a named skill profile. Profiles:\n core — ${PROFILES.core.length} main-loop skills incl. phase (~130 desc tokens)\n standard — ${PROFILES.standard.length} skills incl. phase, review, config (~700)\n full — all skills (default)\n Composable: --profile=core,audit installs union of closures.\n Profile is persisted and respected by \`gsd update\`.\n ${cyan}--minimal${reset} Alias for --profile=core (back-compat).\n Cuts cold-start overhead from ~12k tokens to ~700.\n Alias: --core-only.\n\n ${yellow}Examples:${reset}\n ${dim}# Interactive install (prompts for runtime and location)${reset}\n npx ${pkg.name}\n\n ${dim}# Install for Claude Code globally${reset}\n npx ${pkg.name} --claude --global\n\n ${dim}# Install for Kilo globally${reset}\n npx ${pkg.name} --kilo --global\n\n ${dim}# Install for Codex globally${reset}\n npx ${pkg.name} --codex --global\n\n ${dim}# Install for Kimi CLI globally${reset}\n npx ${pkg.name} --kimi --global\n\n ${dim}# Install for Kimi CLI under ~/.kimi-code${reset}\n npx ${pkg.name} --kimi --global --config-dir ~/.kimi-code\n\n ${dim}# Install for Copilot globally${reset}\n npx ${pkg.name} --copilot --global\n\n ${dim}# Install for Copilot locally${reset}\n npx ${pkg.name} --copilot --local\n\n ${dim}# Install for Antigravity globally${reset}\n npx ${pkg.name} --antigravity --global\n\n ${dim}# Install for Antigravity locally${reset}\n npx ${pkg.name} --antigravity --local\n\n ${dim}# Install for Cursor globally${reset}\n npx ${pkg.name} --cursor --global\n\n ${dim}# Install for Cursor locally${reset}\n npx ${pkg.name} --cursor --local\n\n ${dim}# Install for Windsurf globally${reset}\n npx ${pkg.name} --windsurf --global\n\n ${dim}# Install for Windsurf locally${reset}\n npx ${pkg.name} --windsurf --local\n\n ${dim}# Install for Augment globally${reset}\n npx ${pkg.name} --augment --global\n\n ${dim}# Install for Augment locally${reset}\n npx ${pkg.name} --augment --local\n\n ${dim}# Install for Trae globally${reset}\n npx ${pkg.name} --trae --global\n\n ${dim}# Install for Trae locally${reset}\n npx ${pkg.name} --trae --local\n\n ${dim}# Install for Hermes Agent globally${reset}\n npx ${pkg.name} --hermes --global\n\n ${dim}# Install for Hermes Agent locally${reset}\n npx ${pkg.name} --hermes --local\n\n ${dim}# Install for Cline globally${reset}\n npx ${pkg.name} --cline --global\n\n ${dim}# Install for Cline locally${reset}\n npx ${pkg.name} --cline --local\n\n ${dim}# Install for CodeBuddy globally${reset}\n npx ${pkg.name} --codebuddy --global\n\n ${dim}# Install for CodeBuddy locally${reset}\n npx ${pkg.name} --codebuddy --local\n\n ${dim}# Install for all runtimes globally${reset}\n npx ${pkg.name} --all --global\n\n ${dim}# Install to custom config directory${reset}\n npx ${pkg.name} --kilo --global --config-dir ~/.kilo-work\n\n ${dim}# Install to current project only${reset}\n npx ${pkg.name} --claude --local\n\n ${dim}# Uninstall GSD from Cursor globally${reset}\n npx ${pkg.name} --cursor --global --uninstall\n\n ${yellow}Notes:${reset}\n The --config-dir option is useful when you have multiple configurations.\n It takes priority over CLAUDE_CONFIG_DIR / OPENCODE_CONFIG_DIR / KILO_CONFIG_DIR / CODEX_HOME / KIMI_CONFIG_DIR / COPILOT_CONFIG_DIR / COPILOT_HOME / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR / AUGMENT_CONFIG_DIR / TRAE_CONFIG_DIR / QWEN_CONFIG_DIR / HERMES_HOME / CLINE_CONFIG_DIR / CODEBUDDY_CONFIG_DIR environment variables.\n Kimi CLI defaults to the first existing generic skills root: ${cyan}~/.config/agents/skills${reset}, then ${cyan}~/.agents/skills${reset}; if neither exists, GSD creates ${cyan}~/.config/agents${reset}.\n Use ${cyan}--config-dir ~/.kimi-code${reset} or ${cyan}KIMI_CONFIG_DIR=~/.kimi-code${reset} for brand-specific Kimi installs.\n`); process.exit(0); } @@ -8593,11 +8594,24 @@ function install(isGlobal, runtime = 'claude', options = {}) { // applyRuntimeContentRewritesInPlace (called inside installRuntimeArtifacts) // handles per-runtime path + branding rewrites, including Qwen/Hermes. // Cline global: emit skills to ~/.cline/skills/ (Cline >= v3.48.0 — #782). - const _isSkillsRuntime = isCodex || isCopilot || isAntigravity || isCursor || isWindsurf || - isAugment || isTrae || isCodebuddy || isQwen || isHermes || - isKimi || - (runtime === 'claude' && isGlobal) || - (isCline && isGlobal); + // Descriptor-driven (ADR-1016 / ADR-1239): a runtime takes the layout-driven + // installRuntimeArtifacts path when its scoped artifactLayout is non-empty + // (it declares any skills/commands/agents/kimi-agents kind for this scope). + // This replaces the prior hardcoded `isCodex || isCopilot || ...` roster so a + // newly-added runtime with an artifact layout installs without a per-runtime + // branch — the add-a-host tax ADR-1239 Phase B retires. Three legacy + // special-cased paths are preserved: opencode/kilo (combined commands+skills + // via copyFlattenedCommands + installOpencodeFamilySkills) and claude-local + // (copyWithPathReplacement + stale-skills cleanup). + const _isSkillsRuntime = (() => { + if (isOpencode || isKilo) return false; // specialized combined path + if (runtime === 'claude' && !isGlobal) return false; // claude-local legacy path + const cap = _capabilityRegistry && _capabilityRegistry.runtimes && _capabilityRegistry.runtimes[runtime]; + const layout = cap && cap.runtime && cap.runtime.artifactLayout; + if (!layout) return false; + const scopeLayout = isGlobal ? layout.global : layout.local; + return Array.isArray(scopeLayout) && scopeLayout.length > 0; + })(); if (_isSkillsRuntime) { // Layout-driven install for skills-based runtimes (full and minimal modes) @@ -8978,9 +8992,11 @@ function install(isGlobal, runtime = 'claude', options = {}) { // (by installRuntimeArtifacts at line 8912), which also performs its own // stale-file prune pass. The inline stale-removal + inline loop both skip them. // Trivial group (cursor/windsurf/augment/trae/codebuddy) cut over together. - // cline is excluded: it takes a rules-only local branch and has a local/global - // complication that the descriptor-driven path does not handle correctly. - const _DESCRIPTOR_AGENTS_RUNTIMES = new Set(['cursor', 'windsurf', 'augment', 'trae', 'codebuddy']); + // #1575: copilot and antigravity cut over — copilot gets .agent.md filename + // rename via _copyStaged(runtime); antigravity uses scope-aware converter. + // cline remains excluded: rules-only local branch + local/global complication + // that the descriptor-driven path does not handle correctly. + const _DESCRIPTOR_AGENTS_RUNTIMES = new Set(['cursor', 'windsurf', 'augment', 'trae', 'codebuddy', 'copilot', 'antigravity']); // Always remove stale gsd-* agents first so re-installing with // `--minimal` actually shrinks a previously-full install. @@ -10401,10 +10417,11 @@ const runtimeMap = { '12': 'opencode', '13': 'qwen', '14': 'trae', - '15': 'windsurf' + '15': 'windsurf', + '16': 'zcode' }; -const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'hermes', 'kimi', 'kilo', 'opencode', 'qwen', 'trae', 'windsurf']; -const ALL_RUNTIMES_OPTION = '16'; +const allRuntimes = ['claude', 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', 'cursor', 'hermes', 'kimi', 'kilo', 'opencode', 'qwen', 'trae', 'windsurf', 'zcode']; +const ALL_RUNTIMES_OPTION = '17'; /** * Build the runtime-selection prompt text shown by the interactive installer. @@ -10427,7 +10444,8 @@ function buildRuntimePromptText() { ${cyan}13${reset}) Qwen Code ${dim}(~/.qwen)${reset} ${cyan}14${reset}) Trae ${dim}(~/.trae)${reset} ${cyan}15${reset}) Windsurf ${dim}(~/.codeium/windsurf)${reset} - ${cyan}16${reset}) All + ${cyan}16${reset}) ZCode ${dim}(~/.zcode)${reset} + ${cyan}17${reset}) All ${dim}Select multiple: 1,2,6 or 1 2 6${reset} `; diff --git a/capabilities/ai-integration/capability.json b/capabilities/ai-integration/capability.json index 89367cc96..679673d94 100644 --- a/capabilities/ai-integration/capability.json +++ b/capabilities/ai-integration/capability.json @@ -1,7 +1,7 @@ { "id": "ai-integration", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "AI design contract", "description": "AI-SPEC design contract workflow for phases that build AI systems; owns the AI integration command, agents, and workflow.ai_integration_phase activation key.", "tier": "full", diff --git a/capabilities/antigravity/capability.json b/capabilities/antigravity/capability.json index cd0736d7c..96b69c82f 100644 --- a/capabilities/antigravity/capability.json +++ b/capabilities/antigravity/capability.json @@ -1,7 +1,7 @@ { "id": "antigravity", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Antigravity", "description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; flat skill layout; tier-1 support.", "tier": "core", @@ -35,6 +35,14 @@ "nesting": "flat", "recursive": false, "converter": "convertClaudeCommandToAntigravitySkill" + }, + { + "kind": "agents", + "destSubpath": "agents", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": "convertClaudeAgentToAntigravityAgent" } ], "local": [ @@ -45,6 +53,14 @@ "nesting": "flat", "recursive": false, "converter": "convertClaudeCommandToAntigravitySkill" + }, + { + "kind": "agents", + "destSubpath": "agents", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": "convertClaudeAgentToAntigravityAgent" } ] }, diff --git a/capabilities/assumption-delta/capability.json b/capabilities/assumption-delta/capability.json index c24ce5c78..23333f0b7 100644 --- a/capabilities/assumption-delta/capability.json +++ b/capabilities/assumption-delta/capability.json @@ -1,7 +1,7 @@ { "id": "assumption-delta", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Assumption-delta architecture checkpoint", "description": "Rarely-firing advisory checkpoint that triggers when a phase makes something plural, optional, or chosen that used to be singular, required, or derived. Surfaces one identity-model question (promote the new general representation to primary, or add it alongside?) so a silent primary-key drift does not accumulate into a later user-facing bug. Non-blocking; fires only on a detected signal.", "tier": "full", diff --git a/capabilities/audit/capability.json b/capabilities/audit/capability.json index 899fbf89a..40fcdc0dc 100644 --- a/capabilities/audit/capability.json +++ b/capabilities/audit/capability.json @@ -1,7 +1,7 @@ { "id": "audit", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Audit", "description": "Open-artifact audit and UAT-gap audit for milestone close gates; exposes `gsd-tools audit-uat` (cross-phase UAT outstanding items) and `gsd-tools audit-open` (structured open-artifact scan across debug, tasks, threads, todos, seeds, UAT, verification, context-questions).", "tier": "full", diff --git a/capabilities/augment/capability.json b/capabilities/augment/capability.json index cc4305b6d..e3f498bb3 100644 --- a/capabilities/augment/capability.json +++ b/capabilities/augment/capability.json @@ -1,7 +1,7 @@ { "id": "augment", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Augment Code", "description": "Augment Code CLI — commands + nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.", "tier": "core", diff --git a/capabilities/claude-orchestration/capability.json b/capabilities/claude-orchestration/capability.json new file mode 100644 index 000000000..95474d492 --- /dev/null +++ b/capabilities/claude-orchestration/capability.json @@ -0,0 +1,85 @@ +{ + "id": "claude-orchestration", + "role": "feature", + "version": "1.7.0-rc.3", + "title": "Claude orchestration (Workflow backend)", + "description": "Default-off, BETA, claude-only capability that adopts Claude Code's Workflow tool (the engine behind /effort ultracode) as an optional parallel-execution backend for the GSD loop. When the runtime exposes the Workflow tool and claude_orchestration.execution_backend resolves to 'workflow', execute-phase emits a generated Workflow script (waves -> parallel() barriers, plans -> agent({ agentType: 'gsd-executor', isolation: 'worktree' }), files_modified overlap -> separate sequential stages, resumeFromRunId wired to the phase run id, shared token budget) that composes the SAME gsd-executor agent and worktree isolation the inline path uses, restoring the wave parallelism the #853 backgrounded-agent nesting limitation forces inline on Claude Code. (The plan-checker and verifier remain inline until separately wired — this capability delivers the parallel-execution backend, not those gates.) Also folds the ultraplan plan-offload under one runtime gate (plan:* surface). On any runtime lacking the Workflow tool, or when the capability is disabled, behaviour is byte-identical to today (inline/manual dispatch). Detection + emission live in gsd-core/bin/lib/claude-orchestration.cjs (pure, fail-closed). Mirrors the existing gsd-ultraplan-phase BETA-isolation posture.", + "tier": "full", + "requires": [], + "engines": { + "gsd": ">=1.7.0" + }, + "runtimeCompat": { + "supported": [ + "claude" + ], + "unsupported": [] + }, + "skills": [], + "agents": [], + "hooks": [], + "commands": [ + { + "family": "claude-orchestration", + "module": "claude-orchestration-command-router.cjs", + "router": "routeClaudeOrchestrationCommand", + "subcommands": [ + "detect-backend", + "emit-workflow" + ] + } + ], + "activationKey": "claude_orchestration.enabled", + "config": { + "claude_orchestration.enabled": { + "type": "boolean", + "default": false, + "description": "Master toggle for the Claude orchestration capability. Default-off + BETA: the Workflow-tool execution backend and the ultraplan plan-offload surface are inert unless this is true. When false, loop behaviour is byte-identical to a non-Claude runtime (inline/manual dispatch)." + }, + "claude_orchestration.execution_backend": { + "type": "enum", + "values": [ + "auto", + "workflow", + "inline" + ], + "default": "auto", + "description": "Which execute-phase dispatch backend to use when the capability is enabled. 'auto' (default) activates the Workflow backend only when the runtime is Claude AND the Workflow tool is detected AND the Agent SDK meets claude_orchestration.min_agent_sdk_version; otherwise it falls back to inline. 'workflow' forces the Workflow backend when the tool is present AND the Agent SDK meets the floor (still fails closed to inline if the tool is absent or the SDK is too old — the floor applies in both modes). 'inline' forces today's manual one-agent-per-message dispatch regardless of tool availability." + }, + "claude_orchestration.min_agent_sdk_version": { + "type": "string", + "default": "0.3.149", + "description": "Minimum Agent SDK version required to activate the Workflow backend under execution_backend='auto'. Defaults to 0.3.149 (the release that introduced the Workflow tool). Raise to pin a higher floor; the detection seam fails closed to inline for any runtime reporting an older or unknown version." + } + }, + "steps": [], + "contributions": [ + { + "point": "execute:wave:post", + "into": "executor", + "fragment": { + "path": "fragments/execute-wave-post.md" + }, + "produces": [], + "consumes": [ + "PLAN.md" + ], + "when": "claude_orchestration.enabled", + "onError": "skip" + }, + { + "point": "plan:post", + "into": "planner", + "fragment": { + "path": "fragments/plan-post.md" + }, + "produces": [], + "consumes": [ + "CONTEXT.md" + ], + "when": "claude_orchestration.enabled", + "onError": "skip" + } + ], + "gates": [] +} diff --git a/capabilities/claude-orchestration/fragments/execute-wave-post.md b/capabilities/claude-orchestration/fragments/execute-wave-post.md new file mode 100644 index 000000000..db0e76d5a --- /dev/null +++ b/capabilities/claude-orchestration/fragments/execute-wave-post.md @@ -0,0 +1,64 @@ +# Claude orchestration — Workflow execution backend (BETA) + +> Injected at `execute:wave:post` `into: executor` only when +> `claude_orchestration.enabled` is true. Default-off; `onError: skip`. + +## When this contribution is active + +The Claude orchestration capability is **default-off and BETA**. It activates only +when ALL of the following hold: + +1. `claude_orchestration.enabled` is `true` in `.planning/config.json`, AND +2. the active runtime is **Claude Code** (the Workflow tool is Claude / Agent + SDK-specific), AND +3. `claude_orchestration.execution_backend` resolves to `workflow` — either + explicitly, or via `auto` — **and** the Agent SDK version is + `>= claude_orchestration.min_agent_sdk_version` (default `0.3.149`). The SDK + floor applies in both `auto` and `workflow` modes (fail-closed: a pre-release + or older SDK never activates the preview backend). + +Detection is fail-closed: any miss degrades to **inline, manual, one-agent-per- +message dispatch** — exactly today's behaviour. On a non-Claude runtime this +contribution is a no-op. + +## What the executor does when the Workflow backend is active + +Instead of the orchestrator fanning out one `Agent(subagent_type=gsd-executor, +isolation=worktree, run_in_background=true)` per message (which on Claude Code +cannot nest further subagents — #853 — and so degrades to sequential inline +execution), execute-phase **emits a generated Workflow script** and lets the main +loop orchestrate it: + +- **waves → one or more sequential `parallel()` barriers** — each wave is a + barrier group; when plans within a wave share `files_modified`, they are split + into separate sequential stages within that wave's barrier (the next wave + still waits for the previous wave to complete). +- **plans → `agent(brief, { agentType: 'gsd-executor', isolation: 'worktree' })`** + — the SAME executor agent and worktree isolation the inline path uses, so the + produced `SUMMARY.md` and commits are identical. +- **`files_modified` overlap → separate sequential stages** — two plans that + touch the same file are placed in different stages within the wave (the same + overlap rule execute-phase already applies inline). +- **`resumeFromRunId`** — wired to the phase run id, so an interrupted phase + resumes without re-running completed plans. +- **`budget(tokens)`** — a shared token pool across the whole phase when the + orchestrator passes a `budgetTokens` value to `emitWorkflowScript` (it is a + function parameter, not a config key; the orchestrator decides the budget). + +The emitter is a pure function exposed through the capability command surface: +`gsd-tools claude-orchestration emit-workflow --waves --run-id +[--phase-dir ] [--budget ]` (or `require('gsd-core/bin/lib/claude-orchestration.cjs').emitWorkflowScript` +directly). It maps the phase's wave/plan manifest to the Workflow script string +and never invokes the Workflow tool itself; the orchestrator runs the emitted +script. Detection is resolved by the orchestrator calling the pure +`detectWorkflowBackend` with the LIVE host descriptor (the CLI +`gsd-tools claude-orchestration detect-backend` is a simulation harness that +assumes a capable host unless `--no-nested-dispatch` is passed — it does not probe +the real runtime; the orchestrator supplies the real descriptor). + +## Fallback contract + +If detection resolves to `inline` (tool absent, SDK too old, runtime not Claude, +or the capability disabled), execute-phase MUST proceed with the standard inline +wave dispatch. The executor MUST NOT assume parallelism, a shared budget, or +resume-from-run-id semantics in that mode. diff --git a/capabilities/claude-orchestration/fragments/plan-post.md b/capabilities/claude-orchestration/fragments/plan-post.md new file mode 100644 index 000000000..bec9b01fa --- /dev/null +++ b/capabilities/claude-orchestration/fragments/plan-post.md @@ -0,0 +1,28 @@ +# Claude orchestration — ultraplan plan-offload ownership (BETA) + +> Injected at `plan:post` `into: planner` only when +> `claude_orchestration.enabled` is true. Default-off; `onError: skip`. + +## Ownership declaration + +The `gsd-ultraplan-phase` plan-offload surface (offloading GSD's plan phase to +Claude Code's ultraplan cloud) is **owned by this capability**, not by a +standalone BETA skill. Both surfaces share one runtime gate +(`claude_orchestration.enabled`), one BETA boundary, and one Claude-Code-only +detection seam. + +## When the planner should consider ultraplan offload + +When this contribution is active (capability enabled, Claude Code runtime), the +planner MAY offer the `/gsd-ultraplan-phase` path as an alternative to local +`/gsd-plan-phase` for phases where cloud-assisted planning adds value. This is +advisory, not mandatory — the stable local planner remains the default. + +## Fallback contract + +If the capability is disabled, or the runtime is not Claude Code, ultraplan +offload is **not surfaced** and the planner proceeds with the standard local +`/gsd-plan-phase`. The `gsd-ultraplan-phase` command itself remains installed +(its own runtime gate already no-ops on non-Claude runtimes); this contribution +only governs whether the capability manifest advertises it as part of the +orchestration surface. diff --git a/capabilities/claude/capability.json b/capabilities/claude/capability.json index e678e318d..f87679b19 100644 --- a/capabilities/claude/capability.json +++ b/capabilities/claude/capability.json @@ -1,7 +1,7 @@ { "id": "claude", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Claude Code", "description": "Anthropic Claude Code — primary development runtime; tier-1 support with full hook surface and skills-based global install.", "tier": "core", diff --git a/capabilities/cline/capability.json b/capabilities/cline/capability.json index f9109f2bc..df94b1775 100644 --- a/capabilities/cline/capability.json +++ b/capabilities/cline/capability.json @@ -1,7 +1,7 @@ { "id": "cline", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Cline", "description": "Cline (VS Code extension) — global-only nested-skill layout; cline-rules hook surface (.clinerules); no hook events emitted; tier-2 support.", "tier": "core", diff --git a/capabilities/code-review/capability.json b/capabilities/code-review/capability.json index 4ffd49e4b..9682c230a 100644 --- a/capabilities/code-review/capability.json +++ b/capabilities/code-review/capability.json @@ -1,7 +1,7 @@ { "id": "code-review", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Code review", "description": "Source-file code review and review-fix workflow support for completed execution work.", "tier": "full", diff --git a/capabilities/codebuddy/capability.json b/capabilities/codebuddy/capability.json index 8325b6f40..5f8d45a6d 100644 --- a/capabilities/codebuddy/capability.json +++ b/capabilities/codebuddy/capability.json @@ -1,7 +1,7 @@ { "id": "codebuddy", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "CodeBuddy", "description": "CodeBuddy (Tencent) — converted commands + skills artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.", "tier": "core", diff --git a/capabilities/codex/capability.json b/capabilities/codex/capability.json index 172ff94b4..7cc85f78b 100644 --- a/capabilities/codex/capability.json +++ b/capabilities/codex/capability.json @@ -1,7 +1,7 @@ { "id": "codex", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "OpenAI Codex CLI", "description": "OpenAI Codex CLI — shell-var command style; per-agent sandbox tiers; config.toml + hooks.json hook surface; tier-1 support.", "tier": "core", diff --git a/capabilities/copilot/capability.json b/capabilities/copilot/capability.json index e57583756..b4c5df53a 100644 --- a/capabilities/copilot/capability.json +++ b/capabilities/copilot/capability.json @@ -1,7 +1,7 @@ { "id": "copilot", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "GitHub Copilot", "description": "GitHub Copilot (VS Code) — markdown config format; copilot-inline hook surface; no hook events emitted; flat skill nesting (unconfirmed recursive loader); tier-2 support.", "tier": "core", @@ -29,6 +29,14 @@ "nesting": "flat", "recursive": false, "converter": "convertClaudeCommandToCopilotSkill" + }, + { + "kind": "agents", + "destSubpath": "agents", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": "convertClaudeAgentToCopilotAgent" } ], "local": [ @@ -39,6 +47,14 @@ "nesting": "flat", "recursive": false, "converter": "convertClaudeCommandToCopilotSkill" + }, + { + "kind": "agents", + "destSubpath": "agents", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": "convertClaudeAgentToCopilotAgent" } ] }, diff --git a/capabilities/cursor/capability.json b/capabilities/cursor/capability.json index 3d6fd7c66..50136585d 100644 --- a/capabilities/cursor/capability.json +++ b/capabilities/cursor/capability.json @@ -1,7 +1,7 @@ { "id": "cursor", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Cursor", "description": "Cursor IDE — skills + converted commands artifact layout; hooks.json surface; Claude hook event dialect; recursive skill loader (flat nesting); tier-2 support.", "tier": "core", diff --git a/capabilities/drift/capability.json b/capabilities/drift/capability.json index 66a18b5b9..5ebea9d1a 100644 --- a/capabilities/drift/capability.json +++ b/capabilities/drift/capability.json @@ -1,7 +1,7 @@ { "id": "drift", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Drift detection gates", "description": "Drift detection gates for the planning loop. At execute:wave:post: a blocking schema drift gate (detects schema files changed without a database push) and a non-blocking codebase drift gate (detects structural additions not reflected in STRUCTURE.md). At plan:pre: a non-blocking, warn-only codebase drift gate (gated on workflow.plan_drift_precheck) that flags a stale codebase map before planning, so plans are authored against a fresh STRUCTURE.md instead of discovering drift mid-execution.", "tier": "full", diff --git a/capabilities/external-job/capability.json b/capabilities/external-job/capability.json index cf1a85aca..a75babb08 100644 --- a/capabilities/external-job/capability.json +++ b/capabilities/external-job/capability.json @@ -1,7 +1,7 @@ { "id": "external-job", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Async external-job scheduler adapter", "description": "Default-off producer of the async external-job manifest (#1164). At execute:wave:post an executor can externalize long-running compute (SLURM first, scheduler-pluggable), commit a .planning/async-jobs/.json manifest, defer SUMMARY.md, and return external_job_waiting. The core loop (#1165) consumes the manifest; this capability is the only thing that writes it. NOTE on contribution point: #1164 specifies execute:wave:pre, but execute-phase.md only dispatches execute:wave:post today (wave:pre is declared in the loop host contract but not rendered); wiring wave:pre dispatch is a core-loop change #1164 explicitly puts out of scope, so this capability registers at wave:post and the executor honors the runtime_budget classification guidance before running any tagged task. The adapter (scripts/slurm-adapter.cjs) reads external_job.submit_timeout_ms / poll_timeout_ms / artifact_dir through the canonical capability-config seam (env override > config > registry default).", "tier": "full", diff --git a/capabilities/gap-analysis/capability.json b/capabilities/gap-analysis/capability.json index 35faec0f5..a8a2be422 100644 --- a/capabilities/gap-analysis/capability.json +++ b/capabilities/gap-analysis/capability.json @@ -1,7 +1,7 @@ { "id": "gap-analysis", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Post-planning gap analysis", "description": "Proactive, non-blocking post-planning coverage report. After all PLAN.md files are generated, cross-references every REQ-ID and D-ID from REQUIREMENTS.md and CONTEXT.md against plan bodies. Emits a Source | Item | Status table. Does not block phase advancement.", "tier": "standard", diff --git a/capabilities/graphify/capability.json b/capabilities/graphify/capability.json index 38855ab72..e9cac6524 100644 --- a/capabilities/graphify/capability.json +++ b/capabilities/graphify/capability.json @@ -1,7 +1,7 @@ { "id": "graphify", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Knowledge graph", "description": "Build, query, and inspect the project knowledge graph in `.planning/graphs/`; exposes graphify CLI subcommands (build, query, status, diff) and the /gsd-graphify skill.", "tier": "full", diff --git a/capabilities/hermes/capability.json b/capabilities/hermes/capability.json index a049eb665..e38f13d63 100644 --- a/capabilities/hermes/capability.json +++ b/capabilities/hermes/capability.json @@ -1,7 +1,7 @@ { "id": "hermes", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Hermes Agent", "description": "Hermes Agent (NousResearch) — skills nest under skills/gsd/ category bucket; nested skill layout; settings-json hook surface; Claude hook event dialect; tier-2 support.", "tier": "core", diff --git a/capabilities/intel/capability.json b/capabilities/intel/capability.json index b33f8499a..361c5b8f6 100644 --- a/capabilities/intel/capability.json +++ b/capabilities/intel/capability.json @@ -1,7 +1,7 @@ { "id": "intel", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Codebase intelligence", "description": "Code-intelligence store for codebase querying, diff, snapshot, and API-surface extraction; exposes `gsd-tools intel` subcommands (query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface) and backs `/gsd-map-codebase` and `gsd-intel-updater`.", "tier": "full", diff --git a/capabilities/kilo/capability.json b/capabilities/kilo/capability.json index 53e29f73c..bc15624fc 100644 --- a/capabilities/kilo/capability.json +++ b/capabilities/kilo/capability.json @@ -1,7 +1,7 @@ { "id": "kilo", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Kilo Code", "description": "Kilo Code — XDG-based config dir; global skills at ~/.kilo/skills (separate from XDG config); flat command/ + skills artifact layout; no lifecycle hook registration; tier-2 support.", "tier": "core", diff --git a/capabilities/kimi/capability.json b/capabilities/kimi/capability.json index f025709ee..67ee60eb2 100644 --- a/capabilities/kimi/capability.json +++ b/capabilities/kimi/capability.json @@ -1,7 +1,7 @@ { "id": "kimi", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Kimi CLI", "description": "Kimi CLI (Moonshot AI) — generic agents root at ~/.config/agents; skills + kimi-agents artifact layout; no hook surface; no hook events; tier-2 support.", "tier": "core", diff --git a/capabilities/mempalace/capability.json b/capabilities/mempalace/capability.json index f4bce2459..69b6a726f 100644 --- a/capabilities/mempalace/capability.json +++ b/capabilities/mempalace/capability.json @@ -1,7 +1,7 @@ { "id": "mempalace", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "MemPalace memory", "description": "Cross-session, cross-project memory: deliberate recall before discuss/plan and verbatim capture + temporal-KG sync at phase boundaries, via the MemPalace MCP server and CLI.", "tier": "full", diff --git a/capabilities/nyquist/capability.json b/capabilities/nyquist/capability.json index f6d75a96e..02f512966 100644 --- a/capabilities/nyquist/capability.json +++ b/capabilities/nyquist/capability.json @@ -1,7 +1,7 @@ { "id": "nyquist", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Nyquist validation", "description": "Validation coverage audit that maps executed work back to tests and manual-only evidence.", "tier": "full", diff --git a/capabilities/opencode/capability.json b/capabilities/opencode/capability.json index f123fa28a..43d1d8815 100644 --- a/capabilities/opencode/capability.json +++ b/capabilities/opencode/capability.json @@ -1,7 +1,7 @@ { "id": "opencode", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "OpenCode", "description": "OpenCode — XDG-based config dir; flat command/ + skills artifact layout; settings-json config format; no lifecycle hook registration; tier-2 support.", "tier": "core", diff --git a/capabilities/pattern-mapper/capability.json b/capabilities/pattern-mapper/capability.json index ac0027951..6603b8728 100644 --- a/capabilities/pattern-mapper/capability.json +++ b/capabilities/pattern-mapper/capability.json @@ -1,7 +1,7 @@ { "id": "pattern-mapper", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Pattern mapping", "description": "Optional codebase-pattern mapping before planning; owns the pattern mapper agent and workflow.pattern_mapper activation key.", "tier": "full", diff --git a/capabilities/profile-pipeline/capability.json b/capabilities/profile-pipeline/capability.json index 2603254c8..baf943bbc 100644 --- a/capabilities/profile-pipeline/capability.json +++ b/capabilities/profile-pipeline/capability.json @@ -1,7 +1,7 @@ { "id": "profile-pipeline", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Developer profiling pipeline", "description": "Developer behavioral profiling from Claude Code session history; scans session JSONL files, extracts and samples user messages, and generates profile artifacts (USER-PROFILE.md, dev-preferences.md, CLAUDE.md sections). Exposes eight `gsd-tools` commands: scan-sessions, extract-messages, profile-sample (pipeline phase) and write-profile, profile-questionnaire, generate-dev-preferences, generate-claude-profile, generate-claude-md (output phase). Backs the /gsd-profile-user skill and gsd-user-profiler agent.", "tier": "full", diff --git a/capabilities/qwen/capability.json b/capabilities/qwen/capability.json index 5d5cf46ff..f0c622497 100644 --- a/capabilities/qwen/capability.json +++ b/capabilities/qwen/capability.json @@ -1,7 +1,7 @@ { "id": "qwen", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Qwen Code", "description": "Qwen Code (Alibaba) — nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.", "tier": "core", diff --git a/capabilities/research/capability.json b/capabilities/research/capability.json index 1cbc891a6..1e17d45eb 100644 --- a/capabilities/research/capability.json +++ b/capabilities/research/capability.json @@ -1,7 +1,7 @@ { "id": "research", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Phase research", "description": "Optional phase research before planning; owns the phase researcher agent and workflow.research activation key.", "tier": "standard", diff --git a/capabilities/schema-gate/capability.json b/capabilities/schema-gate/capability.json index 626122a43..8977f52f0 100644 --- a/capabilities/schema-gate/capability.json +++ b/capabilities/schema-gate/capability.json @@ -1,7 +1,7 @@ { "id": "schema-gate", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Schema push detection gate", "description": "Detects ORM schema-relevant files in the phase scope during planning and injects a mandatory [BLOCKING] schema push task into the plan. Prevents false-positive verification where build/types pass because TypeScript types come from config, not the live database.", "tier": "full", diff --git a/capabilities/security/capability.json b/capabilities/security/capability.json index d4d5fc61a..076925bf5 100644 --- a/capabilities/security/capability.json +++ b/capabilities/security/capability.json @@ -1,7 +1,7 @@ { "id": "security", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Security enforcement", "description": "Threat mitigation verification and ship-time security blocking for phases with security enforcement enabled.", "tier": "full", diff --git a/capabilities/tdd/capability.json b/capabilities/tdd/capability.json index 03b77f394..3ba1beb73 100644 --- a/capabilities/tdd/capability.json +++ b/capabilities/tdd/capability.json @@ -1,7 +1,7 @@ { "id": "tdd", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Test-driven development", "description": "Injects TDD heuristics into the planner and enforces RED/GREEN gate compliance on type:tdd plans after execution. Owns workflow.tdd_mode; the --tdd CLI flag is the ephemeral override.", "tier": "full", diff --git a/capabilities/trae/capability.json b/capabilities/trae/capability.json index 02fcda713..9d6a20a39 100644 --- a/capabilities/trae/capability.json +++ b/capabilities/trae/capability.json @@ -1,7 +1,7 @@ { "id": "trae", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Trae IDE", "description": "Trae IDE — nested-skill artifact layout; no hook surface (profile-marker-only config); tier-2 support.", "tier": "core", diff --git a/capabilities/ui/capability.json b/capabilities/ui/capability.json index fc1266934..600228e4a 100644 --- a/capabilities/ui/capability.json +++ b/capabilities/ui/capability.json @@ -1,7 +1,7 @@ { "id": "ui", "role": "feature", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "UI design contracts", "description": "UI-SPEC design contract + retrospective UI audit for frontend phases.", "tier": "full", diff --git a/capabilities/windsurf/capability.json b/capabilities/windsurf/capability.json index a20ad08c8..7421c4a7a 100644 --- a/capabilities/windsurf/capability.json +++ b/capabilities/windsurf/capability.json @@ -1,7 +1,7 @@ { "id": "windsurf", "role": "runtime", - "version": "1.7.0-rc.2", + "version": "1.7.0-rc.3", "title": "Windsurf", "description": "Windsurf (Codeium) — workspace workflow artifact layout for slash commands; no hook surface; no hook events; tier-2 support.", "tier": "core", diff --git a/capabilities/zcode/capability.json b/capabilities/zcode/capability.json new file mode 100644 index 000000000..debc29f01 --- /dev/null +++ b/capabilities/zcode/capability.json @@ -0,0 +1,102 @@ +{ + "id": "zcode", + "role": "runtime", + "version": "1.7.0-rc.3", + "title": "ZCode", + "description": "ZCode (Z.ai) — desktop Agentic Development Environment for GLM-5.2; Claude-shaped nested skills at ~/.zcode/skills//SKILL.md, slash commands, named subagents, native MCP; declarative plugin surface; profile-marker install; tier-2 community support.", + "tier": "core", + "requires": [], + "engines": { + "gsd": ">=1.6.0" + }, + "runtime": { + "configHome": { + "kind": "dot-home", + "name": ".zcode", + "env": [ + "ZCODE_CONFIG_DIR" + ] + }, + "localConfigDir": ".zcode", + "configFormat": "none", + "artifactLayout": { + "global": [ + { + "kind": "skills", + "destSubpath": "skills", + "prefix": "gsd-", + "nesting": "nested", + "recursive": false, + "converter": "convertClaudeCommandToClaudeSkill" + }, + { + "kind": "commands", + "destSubpath": "commands", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": null + }, + { + "kind": "agents", + "destSubpath": "agents", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": null + } + ], + "local": [ + { + "kind": "skills", + "destSubpath": "skills", + "prefix": "gsd-", + "nesting": "nested", + "recursive": false, + "converter": "convertClaudeCommandToClaudeSkill" + }, + { + "kind": "commands", + "destSubpath": "commands", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": null + }, + { + "kind": "agents", + "destSubpath": "agents", + "prefix": "gsd-", + "nesting": "flat", + "recursive": false, + "converter": null + } + ] + }, + "commandStyle": "slash-hyphen", + "hooksSurface": "none", + "sandboxTier": "none", + "supportTier": 2, + "installSurface": "profile-marker-only", + "writesSharedSettings": false, + "permissionWriter": null, + "extendedHookEvents": [], + "hostIntegration": { + "embeddingMode": "declarative", + "commandSurface": "slash-file", + "dispatch": { + "namedDispatch": true, + "nested": "undocumented", + "maxDepth": "undocumented", + "background": false, + "subagentToolkit": "full", + "backgroundDispatch": false + }, + "modelMode": "passive", + "hookBus": "host", + "stateIO": "filesystem", + "transport": "mcp", + "runtime": "electron" + } + } +} diff --git a/docs/INVENTORY-MANIFEST.json b/docs/INVENTORY-MANIFEST.json index 9bd69d266..91c72c593 100644 --- a/docs/INVENTORY-MANIFEST.json +++ b/docs/INVENTORY-MANIFEST.json @@ -309,6 +309,8 @@ "capability-writer.cjs", "check-command-router.cjs", "cjs-command-router-adapter.cjs", + "claude-orchestration-command-router.cjs", + "claude-orchestration.cjs", "cli-exit.cjs", "cli-skew-check.cjs", "clock.cjs", diff --git a/docs/adr/1143-claude-orchestration-capability.md b/docs/adr/1143-claude-orchestration-capability.md index 128a40909..4541bce43 100644 --- a/docs/adr/1143-claude-orchestration-capability.md +++ b/docs/adr/1143-claude-orchestration-capability.md @@ -86,3 +86,39 @@ These existing multi-model features (`execute-phase` `cross_ai_delegation`, the - **Neutral:** no effect on non-Claude runtimes by construction; no behavior change until explicitly enabled. > **Governance note:** This ADR is a *draft design* accompanying feature request #1143. Per CONTRIBUTING, it is PR'd only after the issue receives `approved-feature`, and the capability is implemented only after #857 is released. + +## Amendment (2026-07-06): BETA v1 implementation landed + +#857 is **released** (CLOSED); the capability infrastructure is live. The BETA v1 +of this capability has shipped as `capabilities/claude-orchestration/` with the +scope agreed in the Decision, refined to the lowest-risk first slice: + +- **Detection + emission** live as pure, fail-closed functions in + `gsd-core/bin/lib/claude-orchestration.cjs` (source `src/claude-orchestration.cts`): + `detectWorkflowBackend` (gate ladder: enabled → Claude runtime → + execution_backend ≠ inline → host dispatch nested+background → valid Agent SDK + → SDK ≥ `claude_orchestration.min_agent_sdk_version`, default `0.3.149`) and + `emitWorkflowScript` (waves → `parallel()` stage barriers, plans → + `agent({ agentType: 'gsd-executor', isolation: 'worktree' })`, `files_modified` + overlap → separate sequential stages, `resumeFromRunId` wired to the phase run + id, shared `budget(tokens)` pool). All interpolated values are validated as + script-safe identifiers or JSON-quoted (review Finding 1). +- **Loop registration** is at the two **wired** points the loop host contract + actually renders: `execute:wave:post into:executor` (Workflow-backend guidance) + and `plan:post into:planner` (ultraplan ownership declaration). `execute:wave:pre` + and `execute:pre` are declared in the contract but **not wired** today, so the + capability registers at `wave:post` (the constraint `external-job` also documents). +- **Config** is federated (`claude_orchestration.enabled` default false / + `activationKey`, `execution_backend` enum `auto|workflow|inline` default `auto`, + `min_agent_sdk_version`); the keys live only in the registry, so uninstall + removes them cleanly. +- **ultraplan ownership** is declared in the manifest (`plan:post` contribution); + full install-profile migration of the `gsd-ultraplan-phase` skill into the + capability's `skills[]` is deferred to a follow-up (it triggers the CLUSTERS / + profile membership gate and is a heavier, install-machinery change). + +Status remains **Proposed** — the BETA is default-off and the end-to-end Workflow +execution path (actual orchestration via the Workflow tool inside Claude Code) is +not verifiable outside that runtime. The capability is structurally complete and +tested at the contract level; flipping to Accepted follows maintainer sign-off on +the E2E behaviour once exercised on Claude Code with the Workflow tool present. diff --git a/docs/adr/1235-descriptor-driven-agent-conversion-migration.md b/docs/adr/1235-descriptor-driven-agent-conversion-migration.md index efff11bc5..e41f10daf 100644 --- a/docs/adr/1235-descriptor-driven-agent-conversion-migration.md +++ b/docs/adr/1235-descriptor-driven-agent-conversion-migration.md @@ -80,6 +80,14 @@ Cross-cutting steps (a, b, c) are applied by the descriptor pipeline for the app 5. **Codex** — fold the `.toml` sidecar into the descriptor (or declare it an explicit companion artifact); the `.md` + `.toml` must both reach parity. 6. **Delete the inline loop** once every runtime is green; remove the now-dead `isKimi`/minimal special-casing that referenced it. +### Cutover progress (#1575) + +- **Step 0 (parity harness):** shipped in `tests/issue-1575-agent-descriptor-parity.test.cjs`. Asserts `applySurface` output is byte-identical to `installRuntimeArtifacts` for all descriptor-driven runtimes. Covers stale-cleanup convergence (pre-existing legacy `.agent.md` pruned correctly). +- **Step 1 (trivial converters):** cursor, windsurf, augment, trae, codebuddy — install-path cutover complete (PR #1438); surface-path parity shipped (#1575: `applySurface` now builds `agentCtx` and passes it to `kind.stage()` for agents, applying path-rewrite + attribution + converter + normalize). +- **Step 2 (scope-aware):** copilot and antigravity — cutover complete (#1575: declared `agents` kind in `capability.json`, added to `_DESCRIPTOR_AGENTS_RUNTIMES`, copilot `.agent.md` rename handled in both `_copyStaged` and `_syncGsdDir`). +- **Cline:** deferred — rules-only local branch + local/global complication not handled by the descriptor-driven path. +- **Remaining:** steps 3–6 (config-reading, no-converter, codex, inline-loop deletion). + ## Risks / trade-offs - **Silent install regression** across ~15 runtimes is the dominant risk; the byte-for-byte golden gate is the mitigation, and per-runtime sequencing bounds the blast radius of any single step. diff --git a/docs/explanation/claude-orchestration-capability.md b/docs/explanation/claude-orchestration-capability.md new file mode 100644 index 000000000..e044a4e1f --- /dev/null +++ b/docs/explanation/claude-orchestration-capability.md @@ -0,0 +1,94 @@ +# Claude orchestration capability (BETA) + +> **Explanation** — *why this capability exists and how it fits the loop.* For the +> step-by-step, see the [capability reference](../reference/capability-matrix.md); +> for the design record, see [ADR-1143](../adr/1143-claude-orchestration-capability.md). + +## The problem + +GSD's `execute-phase` is wave-based: plans carry a wave number, waves run +sequentially, and plans *within* a wave run in parallel when their +`files_modified` sets don't overlap. On most runtimes GSD realizes that by +fanning out one backgrounded `gsd-executor` agent (in a worktree) per plan. + +On **Claude Code** that fan-out degrades. Backgrounded agents on Claude Code have +no `Agent`/`Task` tool, so they cannot nest subagents ([#853]). The autonomous +loop therefore falls back to **inline sequential execution** — and with it +silently drops wave parallelism, the plan-checker, and the verifier — on the one +runtime most GSD users run. + +Claude Code ships an orchestration primitive that sidesteps exactly this: the +**Workflow tool** (the engine behind `/effort ultracode`, Agent SDK ≥ v0.3.149). +A Workflow script *is* the orchestrator — it runs from the main loop and spawns +subagents itself via `agent()`, `parallel()` (barrier), `pipeline()`, and +`phase()`, with `isolation: 'worktree'`, a shared token `budget`, and +`resumeFromRunId`. + +## The capability + +`claude-orchestration` is a **default-off, BETA, claude-only** capability that +adopts the Workflow tool as an optional, runtime-gated parallel-execution +backend, and folds the existing `gsd-ultraplan-phase` plan-offload under the same +gate. It is blocked-on-nothing now that the ADR-857 capability system is released. + +- **`role: feature`**, `runtimeCompat.supported: ["claude"]`, `tier: full`. +- **`activationKey: claude_orchestration.enabled`** — default `false`. Nothing + changes until you opt in. +- Registers at two **wired** loop points: `execute:wave:post` (into the executor) + and `plan:post` (into the planner). Both are `onError: skip` and gated by the + `enabled` key. + +## How it decides whether to activate + +Detection is a pure, **fail-closed** function — `detectWorkflowBackend`. The +Workflow backend activates only when *every* gate passes; any miss degrades to +`inline` (today's behaviour): + +1. `claude_orchestration.enabled` is true. +2. The runtime is Claude (the Workflow tool is Claude / Agent SDK-specific). +3. `claude_orchestration.execution_backend` is `auto` or `workflow` (not `inline`). +4. The host descriptor advertises `dispatch.nested` **and** `dispatch.background` + (the nesting-capable Claude-Code shape — a proxy for Workflow-tool presence, + meaningful only after gate 2). +5. The Agent SDK reports a valid semver version. +6. That version is `>= claude_orchestration.min_agent_sdk_version` + (default `0.3.149`). A pre-release of the floor (e.g. `0.3.149-rc.1`) compares + *below* the GA release per SemVer, so the preview backend stays off. + +## What the executor runs when the backend is active + +`emitWorkflowScript` maps the phase's wave/plan model onto Workflow primitives: + +| GSD concept | Workflow primitive | +|---|---| +| Wave | `parallel()` stage barrier | +| Plan | `agent(brief, { agentType: 'gsd-executor', isolation: 'worktree' })` | +| `files_modified` overlap | forces the plans into separate sequential stages | +| Phase run id | `resumeFromRunId("")` | +| Phase token cap | `budget()` | + +Because the emitted script composes the **same** `gsd-executor` agent and +**worktree isolation** the inline path uses, it produces the same `SUMMARY.md` +artifacts and commits — the only difference is the execution vehicle. + +## The fallback contract + +On any runtime lacking the Workflow tool — or when the capability is disabled, +the SDK is too old, or detection fails for any reason — execute-phase proceeds +with the standard inline wave dispatch. This is a release gate, not a nicety: a +regression test asserts the inline fallback on every non-capable combination, so +the capability is default-off and low-risk by construction. + +## BETA scope (v1) + +The first slice ships **detection + emission + declarative ultraplan ownership**. +The emitter is exercised at the contract level (structure, overlap splitting, +resume, budget, anti-injection). End-to-end execution through the Workflow tool +is verifiable only inside Claude Code with the tool present. Full install-profile +migration of the `gsd-ultraplan-phase` skill into the capability's `skills[]` +array is a follow-up (it touches the cluster/profile machinery); for v1 the +manifest *declares* ultraplan ownership at `plan:post` and the existing skill's +own runtime gate continues to no-op on non-Claude runtimes. + +[#853]: https://github.com/open-gsd/gsd-core/issues/853 +[#1143]: https://github.com/open-gsd/gsd-core/issues/1143 diff --git a/docs/how-to/enable-claude-orchestration-workflow-backend.md b/docs/how-to/enable-claude-orchestration-workflow-backend.md new file mode 100644 index 000000000..a8fea05e1 --- /dev/null +++ b/docs/how-to/enable-claude-orchestration-workflow-backend.md @@ -0,0 +1,171 @@ +# How to enable and use the Claude orchestration backend (BETA) + +Run GSD's execute-phase waves through Claude Code's Workflow tool (`/effort ultracode`, Agent SDK ≥ v0.3.149) instead of the default one-agent-per-message dispatch, and fold the `gsd-ultraplan-phase` plan-offload under the same gate. On Claude Code this restores the wave parallelism that backgrounded-agent nesting (#853) otherwise forces inline. + +> **BETA.** This capability tracks a Claude Code preview surface. It is default-off, fail-closed, and Claude-only. Every detection miss degrades silently to today's inline behaviour — enabling it can never break the loop. See the [explanation doc](../explanation/claude-orchestration-capability.md) for the why, and [ADR-1143](../adr/1143-claude-orchestration-capability.md) for the design. + +**What you need:** +- GSD installed with the `full` profile (the capability is `tier: full`). +- **Claude Code** with the Workflow tool available (Agent SDK ≥ `0.3.149`). On any other runtime the capability is an explicit no-op — you can flip the switch safely, nothing happens. +- A GSD project with at least one planned phase (you need a wave/plan manifest to emit a script for). + +--- + +## Step 1 — Enable the capability + +The capability ships disabled. Turn on the master switch inside your GSD project: + +```bash +gsd-tools query config-set claude_orchestration.enabled true +``` + +That single key gates everything — both the Workflow-backend hook at `execute:wave:post` and the ultraplan ownership declaration at `plan:post`. All other `claude_orchestration.*` keys are optional refinements. + +Verify it took: + +```bash +gsd-tools query config-get claude_orchestration.enabled +# → true +``` + +--- + +## Step 2 — Check whether your runtime qualifies + +Detection is fail-closed: the Workflow backend activates only when **every** gate opens. Before relying on it, confirm your runtime reports as capable: + +```bash +gsd-tools claude-orchestration detect-backend \ + --runtime claude \ + --agent-sdk-version 1.2.0 +``` + +You will get one of two results: + +| `backend` | `available` | Meaning | +|-----------|-------------|---------| +| `workflow` | `true` | Every gate passed — the emitter will produce a Workflow script the orchestrator can run. | +| `inline` | `false` | A gate failed. The `reason` field tells you which: `capability_disabled`, `runtime_not_claude`, `backend_inline`, `workflow_tool_unavailable`, `agent_sdk_version_unknown`, or `agent_sdk_version_below_floor`. | + +> **The CLI is a simulation harness, not a probe.** `detect-backend` assumes a capable host descriptor unless you pass `--no-nested-dispatch`. It exists so you (and the orchestrator) can ask "given these facts, would the backend activate?" The real detection the loop uses is the pure `detectWorkflowBackend` function, called with the live host descriptor. + +### If detection returns `inline` + +Work through the `reason`: + +- **`runtime_not_claude`** — you are on Codex / Cursor / opencode / etc. The Workflow tool is Claude-specific; there is nothing to enable here. Your loop is unchanged. +- **`agent_sdk_version_below_floor`** — upgrade Claude Code / the Agent SDK to at least `claude_orchestration.min_agent_sdk_version` (default `0.3.149`). A pre-release of the floor (e.g. `0.3.149-rc.1`) compares *below* the GA release and will not activate. +- **`workflow_tool_unavailable`** — your host descriptor does not advertise nested + background dispatch. This is unusual on Claude Code; if you see it, the Workflow tool is not present in this session. +- **`agent_sdk_version_unknown`** — the version could not be determined. Supply it explicitly via `--agent-sdk-version`. + +### Pin a higher floor (optional) + +If you want to gate the BETA behind a newer Agent SDK than the default: + +```bash +gsd-tools query config-set claude_orchestration.min_agent_sdk_version 1.0.0 +``` + +--- + +## Step 3 — Choose the execution backend + +`claude_orchestration.execution_backend` controls how aggressively the backend is used once detection passes: + +| Value | Behaviour | +|-------|-----------| +| `auto` (default) | Use the Workflow backend **if** detection passes; otherwise inline. The safe, recommended value. | +| `workflow` | Force the Workflow backend when the tool is present (still fails closed to inline if the tool is absent or the SDK is too old — the floor applies in both modes). | +| `inline` | Force today's manual one-agent-per-message dispatch, even on a capable Claude Code runtime. Use this to A/B compare or to temporarily retire the BETA. | + +Switch with: + +```bash +gsd-tools query config-set claude_orchestration.execution_backend workflow +``` + +--- + +## Step 4 — Emit a Workflow script for a phase + +With the capability enabled and detection passing, generate the Workflow script for a phase's wave/plan manifest. The manifest is the wave/plan model execute-phase already builds: + +```json +{ + "waves": [ + { + "id": "w1", + "plans": [ + { "id": "p1", "brief": "Implement the foo module", "files_modified": ["src/foo.cts"] }, + { "id": "p2", "brief": "Wire the bar seam", "files_modified": ["src/bar.cts"] } + ] + } + ] +} +``` + +Emit the script: + +```bash +gsd-tools claude-orchestration emit-workflow \ + --waves .planning/phases/01-foo/waves.json \ + --run-id phase-01-foo \ + --phase-dir .planning/phases/01-foo \ + --budget 500000 +``` + +The output is a generated Workflow script that maps GSD's model 1:1 onto Workflow primitives: + +- **waves → sequential `parallel()` barriers** (split into separate stages within a wave when `files_modified` overlap), +- **plans → `agent(brief, { agentType: "gsd-executor", isolation: "worktree" })`** — the **same** executor agent and worktree isolation the inline path uses, +- **`resumeFromRunId("")`** wired to the phase run id, +- **`budget()`** — a shared token pool across the whole phase (omit `--budget` to skip). + +Because the script composes the same `gsd-executor` agent + worktree isolation + `SUMMARY.md` artifact as the inline path, the artifacts and commits it produces are identical — only the execution vehicle differs. + +### Run the emitted script + +Feed the emitted script to Claude Code's Workflow tool (`/effort ultracode`, or an Agent SDK `Workflow` invocation). The orchestrator runs it; each `agent()` call spawns a `gsd-executor` in its own worktree, waves barrier between each other, and `resumeFromRunId` lets an interrupted phase resume without re-running completed plans. + +--- + +## Step 5 — Ultraplan plan-offload + +Enabling the capability also folds `gsd-ultraplan-phase` under the same runtime gate. When the capability is on, the planner may offer the `/gsd-ultraplan-phase` path (offload plan-phase to Claude Code's ultraplan cloud) as an alternative to local `/gsd-plan-phase`. This is advisory — the stable local planner remains the default. + +If the capability is off, or the runtime is not Claude Code, ultraplan offload is not surfaced and `/gsd-plan-phase` runs as normal. + +--- + +## Disabling + +To turn the capability off and return to byte-identical inline behaviour: + +```bash +gsd-tools query config-set claude_orchestration.enabled false +``` + +Or force inline dispatch while leaving the capability otherwise on: + +```bash +gsd-tools query config-set claude_orchestration.execution_backend inline +``` + +Either step is sufficient — no uninstall or resurface needed. The federated config keys live only in the capability registry, so they vanish cleanly if the capability is ever removed. + +--- + +## What is and is not wired in BETA v1 + +**Working today:** +- Detection (`detectWorkflowBackend` / `gsd-tools claude-orchestration detect-backend`) — fail-closed, tested across every gate. +- Emission (`emitWorkflowScript` / `gsd-tools claude-orchestration emit-workflow`) — waves→barriers, overlap→stages, resume, budget, anti-injection. +- The contribution fragments at `execute:wave:post` and `plan:post` (gated, `onError: skip`). +- Inline fallback on every non-capable combination (regression-tested). + +**Not yet wired (follow-ups):** +- `execute-phase.md` does not yet auto-branch to emit-and-run the Workflow script. Today you emit the script explicitly (Step 4) and run it via the Workflow tool. Automatic dispatch inside the loop is the next milestone. +- The plan-checker and verifier still run inline — this capability delivers the parallel-execution backend, not those gates. +- Full install-profile migration of the `gsd-ultraplan-phase` skill into the capability's `skills[]` (it is currently declared in the manifest; the skill's own runtime gate continues to no-op on non-Claude runtimes). + +If a preview-API change breaks detection, the capability degrades to inline; it cannot destabilise the core loop. diff --git a/docs/how-to/install-on-your-runtime.md b/docs/how-to/install-on-your-runtime.md index 258290f07..90a6e7f15 100644 --- a/docs/how-to/install-on-your-runtime.md +++ b/docs/how-to/install-on-your-runtime.md @@ -102,6 +102,8 @@ The `gsd-tools` binary (installed as part of the `@opengsd/gsd-core` npm package Node.js (`node`) must also be available on your `PATH`. The plugin's always-on guard hooks (wired in `hooks/hooks.json`) are invoked as `node "${CLAUDE_PLUGIN_ROOT}/hooks/