Merge branch 'next' into codex/gsd-onboard
This commit is contained in:
Tom Boucher
@@ -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",
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
94
docs/explanation/claude-orchestration-capability.md
Normal file
94
docs/explanation/claude-orchestration-capability.md
Normal file
@@ -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("<id>")` |
|
||||
| Phase token cap | `budget(<tokens>)` |
|
||||
|
||||
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
|
||||
171
docs/how-to/enable-claude-orchestration-workflow-backend.md
Normal file
171
docs/how-to/enable-claude-orchestration-workflow-backend.md
Normal file
@@ -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("<run-id>")`** wired to the phase run id,
|
||||
- **`budget(<tokens>)`** — 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.
|
||||
@@ -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/<script>"`. Some Claude Code distributions ship as a standalone binary and do not expose a `node` executable on `PATH`; in those environments the plugin's hooks will not run. Verify with `node --version` before relying on the plugin hooks.
|
||||
|
||||
**Runtime build (self-healing).** The runtime CLI's compiled modules under `gsd-core/bin/lib/*.cjs` are build artifacts (ADR-457): they are compiled from `src/*.cts` by `npm run build:lib` and shipped prebuilt in the npm tarball. A plugin-marketplace or git-clone install materializes the repository tree directly and never runs that build step, so those files are initially absent. The CLI heals this automatically: the first `gsd-tools` invocation detects the missing output and compiles it once (using the bundled `typescript` devDependency), then proceeds normally. You may see a one-time `gsd: runtime library not built — compiling once…` notice on stderr; subsequent commands are unaffected. If auto-build cannot run (for example `node_modules` was pruned to production-only and `typescript` is unavailable), the CLI prints an actionable message telling you to run `npm install && npm run build:lib` in the plugin directory.
|
||||
|
||||
#### Claude plugin marketplace discovery (ZCODE and compatible runtimes)
|
||||
|
||||
GSD Core also ships a `.claude-plugin/marketplace.json` marketplace manifest (sibling to `plugin.json`). Runtimes that implement the Claude plugin marketplace contract — such as ZCODE — can discover and install GSD Core from a custom marketplace source without a manual clone:
|
||||
@@ -406,6 +408,22 @@ Skills land in `~/.trae/`. GSD installs skills, agents, and rule references.
|
||||
|
||||
---
|
||||
|
||||
### ZCode
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --zcode --global
|
||||
```
|
||||
|
||||
[ZCode](https://zcode.z.ai/en) is Z.ai's desktop Agentic Development Environment for the GLM-5.2 model. GSD installs skills (nested `SKILL.md` bundles), slash commands, and subagents under `~/.zcode/`:
|
||||
|
||||
- **Skills** → `~/.zcode/skills/gsd-<name>/SKILL.md` (invoke with `$gsd-<name>` in chat)
|
||||
- **Commands** → `~/.zcode/commands/gsd-<name>.md` (invoke with `/gsd-<name>`)
|
||||
- **Subagents** → `~/.zcode/agents/gsd-<name>.md`
|
||||
|
||||
ZCode's skill format is identical to Claude Code's, so no runtime-specific converter is required — GSD lands as a pure declarative descriptor with no hardcoded installer branches. ZCode also natively imports skills and MCP config from `~/.claude`; if you install GSD for **both** Claude and ZCode, you may see duplicate GSD skills inside ZCode, which is expected. To connect ZCode's MCP servers to GSD's companion server, see [how to connect the GSD MCP server](connect-gsd-mcp-server.md).
|
||||
|
||||
---
|
||||
|
||||
## Local vs global install
|
||||
|
||||
All examples above use `--global`, which installs GSD once for your user account. To scope an install to a single project, replace `--global` with `--local`:
|
||||
|
||||
@@ -44,7 +44,7 @@ Core package and are stamped with the package version at release (per
|
||||
ADR-1244 D6). They are not subject to the consent or integrity-pin flow applied
|
||||
to third-party capabilities.
|
||||
|
||||
### Feature capabilities (role: feature) — 18
|
||||
### Feature capabilities (role: feature) — 19
|
||||
|
||||
Feature capabilities extend what the loop does — contributing research,
|
||||
planning, execution, verification, or ship artefacts at the loop extension
|
||||
@@ -55,6 +55,7 @@ points.
|
||||
| `ai-integration` | feature | full | `>=1.6.0` | `plan:pre` | step | first-party |
|
||||
| `assumption-delta` | feature | full | `>=1.6.0` | `plan:pre` | contribution | first-party |
|
||||
| `audit` | feature | full | `>=1.6.0` | — | — | first-party |
|
||||
| `claude-orchestration` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |
|
||||
| `code-review` | feature | full | `>=1.6.0` | `execute:post` | step | first-party |
|
||||
| `drift` | feature | full | `>=1.6.0` | `plan:pre`, `execute:wave:post` | gate | first-party |
|
||||
| `external-job` | feature | full | `>=1.7.0` | `plan:post`, `execute:wave:post` | contribution | first-party |
|
||||
@@ -71,7 +72,7 @@ points.
|
||||
| `tdd` | feature | full | `>=1.6.0` | `plan:pre`, `execute:post` | contribution, gate | first-party |
|
||||
| `ui` | feature | full | `>=1.6.0` | `plan:pre`, `execute:wave:post`, `verify:post` | step, gate | first-party |
|
||||
|
||||
### Runtime capabilities (role: runtime) — 15
|
||||
### Runtime capabilities (role: runtime) — 16
|
||||
|
||||
Runtime capabilities adapt GSD to a specific AI runtime or IDE — emitting
|
||||
skills, agents, hooks configuration, and surface files for that host. They
|
||||
@@ -95,6 +96,7 @@ emission), so their extension-point and hook-kind cells are `—`.
|
||||
| `qwen` | runtime | core | `>=1.6.0` | — | — | first-party |
|
||||
| `trae` | runtime | core | `>=1.6.0` | — | — | first-party |
|
||||
| `windsurf` | runtime | core | `>=1.6.0` | — | — | first-party |
|
||||
| `zcode` | runtime | core | `>=1.6.0` | — | — | first-party |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -548,3 +548,40 @@ Sources consulted:
|
||||
Documentation gaps:
|
||||
- dispatch.subagentToolkit — docs show three built-in subagent types each with different tool subsets (coder=full, explore=read-only, plan=no shell/write); no single 'full' or 'read-only' value covers all types; maintainer should clarify the intended classification.
|
||||
- runtime — CLI core is Python; a Rust Wire implementation also exists; docs do not state a canonical plugin extension runtime.
|
||||
|
||||
---
|
||||
|
||||
## zcode
|
||||
|
||||
> ZCode (Z.ai) is a desktop Agentic Development Environment for the GLM-5.2 model, distributed as an Electron app. It exposes a Claude-Code-shaped extensibility surface (per-user `~/.zcode/skills/<name>/SKILL.md`, slash commands, named subagents, native MCP, and a plugin system). All values below are sourced verbatim from the official ZCode docs.
|
||||
|
||||
| Axis | Value | Source | Evidence |
|
||||
|---|---|---|---|
|
||||
| embeddingMode | declarative | https://zcode.z.ai/en/docs/plugin | "A single plugin can bundle several capabilities. ZCode detects which components a plugin includes from its directory layout" — plugins/skills/commands/agents are config/markdown files; no in-process programmatic extension API is documented. |
|
||||
| commandSurface | slash-file | https://zcode.z.ai/en/docs/commands | "Custom commands are stored as `.md` files under `~/.zcode/commands` ... invoke the command with `/command-name`" |
|
||||
| modelMode | passive | https://zcode.z.ai/en/docs/configuration | Models are connected by provider config (Z.ai/BigModel/OpenAI-compat/Anthropic-compat base URLs + API keys in Model Settings); no programmatic model request API is documented. |
|
||||
| hookBus | host | https://zcode.z.ai/en/docs/plugin | A plugin's bundled components include a "**Hook** — Automation hooks triggered on specific events" — the host fires the events a plugin subscribes to. |
|
||||
| stateIO | filesystem | https://zcode.z.ai/en/docs/skill | "User-level skills for ZCode Agent: `~/.zcode/skills/<skill-name>/SKILL.md`" — full local filesystem (desktop app). |
|
||||
| transport | mcp | https://zcode.z.ai/en/docs/mcp-services | "MCP (Model Context Protocol) connects external capabilities ... type as `stdio` (SSE and HTTP remote servers are also supported)" — native MCP. |
|
||||
| runtime | electron | https://zcode.z.ai/en/docs/install (download path `cdn-zcode.z.ai/zcode/electron/releases/3.2.5/ZCode-3.2.5-mac-arm64.dmg`) | ZCode is shipped as an Electron desktop application; the release artifact lives under the `electron/releases` path. |
|
||||
| dispatch.namedDispatch | true | https://zcode.z.ai/en/docs/subagents | "you can let the Agent pick the subagent automatically, or reference it with `@` in the chat box" — subagents are invoked by name via the Agent tool. |
|
||||
| dispatch.nested | undocumented | searched: https://zcode.z.ai/en/docs/subagents | The docs do not state whether a subagent can itself spawn further subagents. |
|
||||
| dispatch.maxDepth | undocumented | searched: https://zcode.z.ai/en/docs/subagents | No maximum nesting depth is documented. |
|
||||
| dispatch.background | false | https://zcode.z.ai/en/docs/subagents | "**Foreground execution.** Subagents run in the foreground ... Background execution is not enabled yet." |
|
||||
| dispatch.subagentToolkit | full | https://zcode.z.ai/en/docs/subagents | "**general-purpose** is the default built-in subagent ... It has access to all tools"; custom subagents default to "All permissions by default" (inherits every tool). |
|
||||
| dispatch.backgroundDispatch | false | https://zcode.z.ai/en/docs/subagents | "Background execution is not enabled yet" — background dispatch is therefore impossible. |
|
||||
|
||||
Sources consulted:
|
||||
- https://zcode.z.ai/en/docs/skill
|
||||
- https://zcode.z.ai/en/docs/commands
|
||||
- https://zcode.z.ai/en/docs/subagents
|
||||
- https://zcode.z.ai/en/docs/mcp-services
|
||||
- https://zcode.z.ai/en/docs/plugin
|
||||
- https://zcode.z.ai/en/docs/configuration
|
||||
- https://zcode.z.ai/en/docs/install
|
||||
|
||||
Documentation gaps:
|
||||
- dispatch.nested / dispatch.maxDepth — ZCode's subagent docs do not state whether subagents can spawn further subagents or any depth bound.
|
||||
- configHome — skills/commands/agents homes are documented (`~/.zcode/skills`, `~/.zcode/commands`, `~/.zcode/agents`); the exact settings filename under `~/.zcode` (where MCP server config is stored) is not fully documented at time of writing.
|
||||
- Maintenance note — ZCode is a young, fast-moving app (observed at v3.2.x); these axes may need revision as its on-disk config layout stabilizes. Because ZCode also natively imports skills/MCP from `~/.claude`, installing GSD to BOTH `claude` and `zcode` can surface duplicated skills inside ZCode; this overlap is expected and documented.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user