Merge branch 'next' into fix/1514-retired-phase-total-phases
This commit is contained in:
Behruz Nassre Esfahani
5
.changeset/1532-core-lock-liveness.md
Normal file
5
.changeset/1532-core-lock-liveness.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1532
|
||||
---
|
||||
**Core-path file locks now verify the holder process is alive before stealing a stale lock (#1532)** — the STATE.md write lock (`acquireStateLock`) and the `.planning/` workspace lock (`withPlanningLock`) previously stole locks on a bare `mtime` timer with no liveness check, so a live-but-slow holder (e.g. a deep `.planning/` scan on slow NFS) could have its lock stolen mid-write, corrupting STATE.md or losing an update. Both locks now gate stealing on `process.kill(pid,0)` liveness with a deadman ceiling above the wait budget (pid-reuse backstop), `withPlanningLock` no longer force-steals a live holder on timeout (and can no longer leak an uncaught `EEXIST`), `writeStateMd` computes its disk scan inside the lock, and `acquireStateLock` no longer leaks a file descriptor or strands an empty lock on a recoverable write error. The steal itself is now race-safe: a lock is never stolen while its body is still being written (the create→pid-write window), and stealing uses an atomic rename with an identity re-confirm so two waiters can no longer both reclaim the same lock and end up holding it concurrently. The uncontended path is unchanged.
|
||||
7
.changeset/clever-seals-rest.md
Normal file
7
.changeset/clever-seals-rest.md
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1438
|
||||
---
|
||||
**Thread `isGlobal` install scope through the descriptor-driven `convertedAgentsKind` / `stageAgentsForRuntimeWithConverter` plumbing** — a prerequisite for the ADR-1235 agent-conversion cutover. No runtime declares a converted `agents` kind yet; the `capability.json` wiring is deferred to a follow-up that first ships the ADR-1235 §0 byte-for-byte parity harness (so the `/gsd:surface` / `--materialize` consumer can mirror the legacy agent pipeline before the kind goes live). The legacy `bin/install.js` agent loop remains authoritative, so installed agent output is unchanged. (#1173)
|
||||
|
||||
<!-- docs-exempt: internal install-path plumbing only (ADR-1235 cutover prerequisite); no runtime declares the converted agents kind, the legacy loop remains authoritative, and installed agent output is unchanged — no user-facing command/config/behavior surface. -->
|
||||
5
.changeset/daring-ravens-wake.md
Normal file
5
.changeset/daring-ravens-wake.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 1421
|
||||
---
|
||||
**`/gsd-review` now asks external reviewers to verify plan claims against the source** — the reviewer prompt requires opening the referenced files, citing `file:line` evidence + mechanism, and tracing asserted behavior, with a graceful-degradation clause for reviewers that have no file access. This turns every capable agentic reviewer into a real second source instead of a plan-text paraphraser. (#1318)
|
||||
5
.changeset/eager-wolves-run.md
Normal file
5
.changeset/eager-wolves-run.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1418
|
||||
---
|
||||
**All GSD agents load on Gemini again** — the Claude `Skill`/`SlashCommand` tools were converted to an invalid `skill` tool that Gemini rejects, aborting the load of 22 of 34 agents. They are now excluded from the Gemini and Gemini-backed Antigravity agent `tools:` frontmatter, the same way `AskUserQuestion` already is. (#1394)
|
||||
5
.changeset/merry-deer-greet.md
Normal file
5
.changeset/merry-deer-greet.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 722
|
||||
---
|
||||
**`/gsd-capture --list-seeds` audits parked seeds** — a new read-only listing of `.planning/seeds/` showing each seed's ID, status, scope, and trigger, with an optional status filter (e.g. `--list-seeds dormant`). Backed by the `gsd-tools list-seeds` command. Previously seeds could only be created or auto-surfaced at `/gsd-new-milestone`, with no way to browse them on demand (#441).
|
||||
5
.changeset/proud-sloths-glide.md
Normal file
5
.changeset/proud-sloths-glide.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1574
|
||||
---
|
||||
**OpenCode and other AGENTS-native runtimes now get a root `AGENTS.md` from `/gsd:new-project`** — the workflow hardcoded a codex-only branch that sent every other runtime to `.claude/CLAUDE.md`, a location OpenCode never loads. A shared `getProjectInstructionFile(runtime)` policy (claude→`.claude/CLAUDE.md`, codex/opencode/kilo/kimi→`AGENTS.md`, copilot→`.github/copilot-instructions.md`, antigravity/gemini→`GEMINI.md`) is now the single source of truth consumed by both the new-project workflow and the generate-claude-md path, with a parity test guarding drift.
|
||||
5
.changeset/rapid-bears-hum.md
Normal file
5
.changeset/rapid-bears-hum.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Added
|
||||
pr: 1597
|
||||
---
|
||||
**Plugin installs now expose GSD skills** — when GSD is installed as a Claude Code plugin (`claude plugin install`), its skills are available via `gsd-core:<skill>` the native way. Previously, plugin-only installs lacked the skill surface because `bin/install.js` never ran; agents that preload `global:gsd-core:<skill>` (PR #1261) now resolve against plugin-provided skills. (#1596)
|
||||
5
.changeset/sturdy-birds-climb.md
Normal file
5
.changeset/sturdy-birds-climb.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1409
|
||||
---
|
||||
**Codex runtime no longer crashes on startup** — every `gsd-tools` command previously aborted with `Cannot find module '../../../package.json'` on Codex, whose runtime root has no `package.json`, because a module in the loader chain did a top-level require of it. The version emitted into Hermes skill frontmatter is now sourced lazily from the installed `gsd-core/VERSION` (validated semver), so `gsd-tools` loads on every runtime and never emits `version: undefined`. (#1383)
|
||||
5
.changeset/sturdy-jays-run.md
Normal file
5
.changeset/sturdy-jays-run.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1410
|
||||
---
|
||||
**`query agent-skills` no longer returns empty output on Windows** — the plain (non-`--json`) path wrote the `<agent_skills>` block then immediately called `process.exit(0)`, which truncated the async stdout buffer on Windows pipes/files so every `${AGENT_SKILLS_*}` workflow capture expanded empty and configured per-agent skills were silently dropped. It now flushes synchronously via the same `writeAllSync` helper the `--json` path uses. (#1400)
|
||||
5
.changeset/sunny-deer-roar.md
Normal file
5
.changeset/sunny-deer-roar.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 1552
|
||||
---
|
||||
roadmap analyze no longer reports phantom missing_phase_details for milestone-prefixed (M-NN) phase IDs
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "gsd-core",
|
||||
"displayName": "GSD Core",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
|
||||
"author": {
|
||||
"name": "open-gsd",
|
||||
@@ -19,5 +19,6 @@
|
||||
"gsd"
|
||||
],
|
||||
"commands": "./commands/gsd/",
|
||||
"skills": "./skills/",
|
||||
"hooks": "./hooks/hooks.json"
|
||||
}
|
||||
|
||||
@@ -155,7 +155,7 @@ Module owning which skills and agents are written to runtime config directories
|
||||
Module owning the per-runtime mapping from artifact kind to filesystem placement. ADR-3660 defines the typed `kinds` per runtime (`commands`, `agents`, `skills`) with destination subpath, prefix, and stage adapter (with per-runtime converters in `bin/install.js`: `convertClaudeCommandToClaudeSkill`, `…CodexSkill`, `…CopilotSkill`, `…AntigravitySkill`). Owns the per-runtime `nested` skill-bundle decision (#69): a `skillsKind` flag in `src/runtime-artifact-layout.cts` drives whether a runtime receives the nested router layout (6 `gsd-ns-*` routers + concrete skills under `<router>/skills/<name>/`) or the flat `skills/gsd-<stem>/` layout; the evidence/doc-link matrix is recorded in a comment above `resolveRuntimeArtifactLayout`. Phase 1 applies this seam to the Runtime Surface Module (`surface.cjs:applySurface`); as of #813, `applySurface` applies the same per-runtime skill-body path rewrites as `installRuntimeArtifacts` for `skills` kinds — re-surfacing no longer overwrites installed SKILL.md bodies with converter-default `~/.claude` paths. Per ADR-1508 / #1511 the former `getInstallExports`/`loadInstallExports` relay (a `GSD_TEST_MODE`-guarded `require('bin/install.js')` by which `surface.cjs` reached `computePathPrefix`/`applyRuntimeContentRewritesInPlace`) was DELETED from this module; content rewriting now lives in the Runtime Artifact Conversion Module and `surface.cjs:applySurface` calls its `rewriteStagedSkillBodies` directly. The resolved `scope` is still carried on the `Layout` object so `applySurface` derives the same `pathPrefix` (global `$HOME` form vs. absolute) as a fresh install. Phase 2 is planned to migrate install/uninstall in `bin/install.js` so all lifecycle sites iterate one shared layout table instead of re-encoding runtime layout logic. This design is intended to remove the #3659 class of omissions. Migrations remain under the Installer Migration Module (ADR-0008). See ADR-3660.
|
||||
|
||||
### Runtime Artifact Conversion Module
|
||||
Sibling Module to Runtime Artifact Layout Module. Owns projection from canonical Claude-authored command/agent/skill markdown into runtime-specific artifact bodies, including converter selection, frontmatter/body normalization, runtime path rewrites, and staged artifact generation. Runtime Artifact Layout remains responsible for filesystem placement (`kind`, destination subpath, prefix, nesting); Runtime Artifact Conversion owns the content Implementation behind that placement seam so install, uninstall/surface parity, and future plugin/package projections stop reaching back through `bin/install.js` for converter functions or `GSD_TEST_MODE`-guarded installer exports. Chosen direction: sibling Module, not an expanded Layout Module, to preserve ADR-3660's narrow placement responsibility while deepening artifact content locality. First slice: relocate only the layout-reached conversion family (`convertClaudeCommandTo*Skill`, converted command-file emitters, `buildKimiAgentArtifacts`) plus the minimal helper closure they need; do not leave helper dependencies in `bin/install.js` because that would preserve the same shallow seam under a new filename. Installer integration decision: `bin/install.js` imports the conversion Module at top level and re-exports the moved names for compatibility; the conversion Module must not import `bin/install.js` or Runtime Artifact Layout, so the dependency direction becomes installer/layout Adapters -> conversion Module, never conversion -> installer. First-slice Interface decision: export the existing compatibility names only; do not introduce a grouped `convertRuntimeArtifact` Interface until after relocation proves byte-for-byte behavior. SHIPPED (ADR-1508): the converter family relocated in #1510 Phase 1 (`getDirName`→runtime-name-policy, `processAttribution` here); #1511 Phase 2 moved the content-rewrite engine here in full — `_applyRuntimeRewrites` (per-runtime switch, injected attribution), the staged-content walkers `applyRuntimeContentRewritesInPlace`/`applyRuntimeContentRewritesForCommandsInPlace`, `computePathPrefix` (private; `_computePathPrefix` for tests), and the deep public seam `rewriteStagedSkillBodies`/`rewriteStagedCommandBodies({runtime,configDir,scope,homedir?,platform?,resolveAttribution?})`. `bin/install.js` binds these back (single owner, exports preserved); `getCommitAttribution` stays in `bin/install.js` (impure install-time config I/O) and is injected. The `getInstallExports` relay in Runtime Artifact Layout Module was deleted; the dependency direction installer/layout → conversion (never upward) is now enforced. Exception: opencode and kilo path-prefix rewriting is a deliberate `bin/install.js`-owned pre-conversion step (`applyOpencodeFamilyPathPrefix`) per #784, not a violation of the single-owner rule. Source: `gsd-core/bin/lib/runtime-artifact-conversion.cjs` (generated from `src/runtime-artifact-conversion.cts`).
|
||||
Sibling Module to Runtime Artifact Layout Module. Owns projection from canonical Claude-authored command/agent/skill markdown into runtime-specific artifact bodies, including converter selection, frontmatter/body normalization, runtime path rewrites, and staged artifact generation. Runtime Artifact Layout remains responsible for filesystem placement (`kind`, destination subpath, prefix, nesting); Runtime Artifact Conversion owns the content Implementation behind that placement seam so install, uninstall/surface parity, and future plugin/package projections stop reaching back through `bin/install.js` for converter functions or `GSD_TEST_MODE`-guarded installer exports. Chosen direction: sibling Module, not an expanded Layout Module, to preserve ADR-3660's narrow placement responsibility while deepening artifact content locality. First slice: relocate only the layout-reached conversion family (`convertClaudeCommandTo*Skill`, converted command-file emitters, `buildKimiAgentArtifacts`) plus the minimal helper closure they need; do not leave helper dependencies in `bin/install.js` because that would preserve the same shallow seam under a new filename. Installer integration decision: `bin/install.js` imports the conversion Module at top level and re-exports the moved names for compatibility; the conversion Module must not import `bin/install.js` or Runtime Artifact Layout, so the dependency direction becomes installer/layout Adapters -> conversion Module, never conversion -> installer. First-slice Interface decision: export the existing compatibility names only; do not introduce a grouped `convertRuntimeArtifact` Interface until after relocation proves byte-for-byte behavior. SHIPPED (ADR-1508): the converter family relocated in #1510 Phase 1 (`getDirName`→runtime-name-policy, `processAttribution` here); #1511 Phase 2 moved the content-rewrite engine here in full — `_applyRuntimeRewrites` (per-runtime switch, injected attribution), the staged-content walkers `applyRuntimeContentRewritesInPlace`/`applyRuntimeContentRewritesForCommandsInPlace`, `computePathPrefix` (private; `_computePathPrefix` for tests), and the deep public seam `rewriteStagedSkillBodies`/`rewriteStagedCommandBodies({runtime,configDir,scope,homedir?,platform?,resolveAttribution?})`. `bin/install.js` binds these back (single owner, exports preserved); `getCommitAttribution` stays in `bin/install.js` (impure install-time config I/O) and is injected. The `getInstallExports` relay in Runtime Artifact Layout Module was deleted; the dependency direction installer/layout → conversion (never upward) is now enforced. Exception: opencode and kilo path-prefix rewriting is a deliberate `bin/install.js`-owned pre-conversion step (`applyOpencodeFamilyPathPrefix`) per #784, not a violation of the single-owner rule. Source: `gsd-core/bin/lib/runtime-artifact-conversion.cjs` (generated from `src/runtime-artifact-conversion.cts`). Also exports `resolveVersionFrom(libDir)` — a lazy, defensive GSD-version resolver (installed-tree `gsd-core/VERSION` first, then the source/npm `package.json` three dirs up, both validated against the repo's shared semver-prefix shape, degrading to `''` on failure) that replaced a module-load-time `require('../../../package.json')` which crashed on runtimes whose root carries no `package.json` (e.g. Codex) (#1383).
|
||||
|
||||
### Runtime Artifact Install Plan Module
|
||||
Module owning install-time staging and content-rewrite selection for a pre-resolved Runtime Artifact Layout. Interface: `createRuntimeArtifactInstallPlan({ layout, resolvedProfile, homedir?, platform?, resolveAttribution?, deps? }) -> { ok:true, plan:{ items, cleanupDirs } } | { ok:false, kind:'stage_failed'|'rewrite_failed', message, cleanupDirs, failedKind? }`. It iterates `layout.kinds` in order, calls each kind's `stage(resolvedProfile)`, delegates `commands` to Runtime Artifact Conversion `rewriteStagedCommandBodies`, delegates `skills` and `kimi-agents` to `rewriteStagedSkillBodies`, leaves non-rewritten kinds unchanged, and projects copy items as `{ kind, sourceDir, destDir }`. It deliberately does not prune, copy, run legacy migrations, print output, or execute cleanup; those remain Installer Module adapter responsibilities until later slices wire the plan into `bin/install.js`. Source: `gsd-core/bin/lib/runtime-artifact-install-plan.cjs` (generated from `src/runtime-artifact-install-plan.cts`). See Runtime Artifact Layout Module and Runtime Artifact Conversion Module.
|
||||
|
||||
@@ -1517,11 +1517,17 @@ function convertGeminiToolName(claudeTool) {
|
||||
// Task/Agent: exclude — agents are auto-registered as callable tools.
|
||||
// AskUserQuestion: exclude — Gemini CLI does not expose an ask_user tool;
|
||||
// emitting it causes frontmatter validation errors (#3362).
|
||||
// Skill/SlashCommand: exclude — Gemini CLI has no 'skill' built-in tool;
|
||||
// the lowercase fallback would emit an invalid 'skill'/'slashcommand' name
|
||||
// that fails frontmatter validation (tools.N: Invalid tool name) and aborts
|
||||
// the entire agent load (#1394).
|
||||
if (
|
||||
claudeTool === 'Task' ||
|
||||
claudeTool === 'Agent' ||
|
||||
claudeTool === 'AskUserQuestion' ||
|
||||
claudeTool === 'ask_user'
|
||||
claudeTool === 'ask_user' ||
|
||||
claudeTool === 'Skill' ||
|
||||
claudeTool === 'SlashCommand'
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
@@ -12048,7 +12054,10 @@ module.exports = {
|
||||
// #1191 — exported so tests exercise the REAL readSettings, not a replica
|
||||
readSettings,
|
||||
stripJsonComments,
|
||||
...runtimeArtifactConversion,
|
||||
// Compatibility relays retained after auditing the former broad
|
||||
// runtimeArtifactConversion spread (#1559).
|
||||
processAttribution,
|
||||
applyRuntimeContentRewritesForCommandsInPlace,
|
||||
};
|
||||
|
||||
// Main logic — only run when not loaded as a module for testing
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "ai-integration",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "antigravity",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Antigravity",
|
||||
"description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; nested skill layout; tier-1 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "audit",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "augment",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "claude",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Claude Code",
|
||||
"description": "Anthropic Claude Code — primary development runtime; tier-1 support with full hook surface and skills-based global install.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "cline",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "code-review",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Code review",
|
||||
"description": "Source-file code review and review-fix workflow support for completed execution work.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "codebuddy",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "CodeBuddy",
|
||||
"description": "CodeBuddy (Tencent) — converted commands + skills artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "codex",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "copilot",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "cursor",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "drift",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Drift detection gates",
|
||||
"description": "Post-execution drift detection gates that run after each wave completes. Provides two gates 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).",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "gap-analysis",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "gemini",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Gemini CLI",
|
||||
"description": "Google Gemini CLI — commands-only artifact layout (TOML); Gemini hook event dialect; settings-json hook surface; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "graphify",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "hermes",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "intel",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "kilo",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "kimi",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "mempalace",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "nyquist",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Nyquist validation",
|
||||
"description": "Validation coverage audit that maps executed work back to tests and manual-only evidence.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "opencode",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "pattern-mapper",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Pattern mapping",
|
||||
"description": "Optional codebase-pattern mapping before planning; owns the pattern mapper agent and workflow.pattern_mapper activation key.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "profile-pipeline",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "qwen",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Qwen Code",
|
||||
"description": "Qwen Code (Alibaba) — nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "research",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Phase research",
|
||||
"description": "Optional phase research before planning; owns the phase researcher agent and workflow.research activation key.",
|
||||
"tier": "standard",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "schema-gate",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "security",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Security enforcement",
|
||||
"description": "Threat mitigation verification and ship-time security blocking for phases with security enforcement enabled.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "tdd",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "trae",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Trae IDE",
|
||||
"description": "Trae IDE — nested-skill artifact layout; no hook surface (profile-marker-only config); tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "ui",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "UI design contracts",
|
||||
"description": "UI-SPEC design contract + retrospective UI audit for frontend phases.",
|
||||
"tier": "full",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"id": "windsurf",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Windsurf",
|
||||
"description": "Windsurf (Codeium) — nested under ~/.codeium/windsurf; skills-only artifact layout; no hook surface; no hook events; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: gsd:capture
|
||||
description: Capture ideas, tasks, notes, and seeds to their destination
|
||||
argument-hint: "[--note | --backlog | --seed | --list] [text]"
|
||||
argument-hint: "[--note | --backlog | --seed | --list | --list-seeds] [text]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
@@ -21,6 +21,7 @@ Mode routing:
|
||||
- **--backlog**: Add an idea to the backlog parking lot (999.x numbering) → add-backlog workflow
|
||||
- **--seed**: Capture a forward-looking idea with trigger conditions → plant-seed workflow
|
||||
- **--list**: List pending todos and select one to work on → check-todos workflow
|
||||
- **--list-seeds**: List/audit captured seeds (optional status filter) → list-seeds workflow
|
||||
</objective>
|
||||
|
||||
<routing>
|
||||
@@ -32,6 +33,7 @@ Mode routing:
|
||||
| --backlog | ROADMAP.md backlog section (999.x) | add-backlog |
|
||||
| --seed | .planning/seeds/SEED-NNN-slug.md | plant-seed |
|
||||
| --list | Interactive todo browser + action router | check-todos |
|
||||
| --list-seeds | Read-only seed list/audit (optional status filter) | list-seeds |
|
||||
|
||||
</routing>
|
||||
|
||||
@@ -41,6 +43,7 @@ Mode routing:
|
||||
@~/.claude/gsd-core/workflows/add-backlog.md
|
||||
@~/.claude/gsd-core/workflows/plant-seed.md
|
||||
@~/.claude/gsd-core/workflows/check-todos.md
|
||||
@~/.claude/gsd-core/workflows/list-seeds.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
@@ -51,6 +54,7 @@ Parse the first token of $ARGUMENTS:
|
||||
- If it is `--note`: strip the flag, pass remainder to note workflow
|
||||
- If it is `--backlog`: strip the flag, pass remainder to add-backlog workflow
|
||||
- If it is `--seed`: strip the flag, pass remainder to plant-seed workflow
|
||||
- If it is `--list-seeds`: strip the flag, pass remainder (optional status filter) to list-seeds workflow
|
||||
- If it is `--list`: pass remainder (optional area filter) to check-todos workflow
|
||||
- Otherwise: pass all of $ARGUMENTS to add-todo workflow
|
||||
</context>
|
||||
|
||||
@@ -477,6 +477,9 @@ node gsd-tools.cjs current-timestamp [full|date|filename]
|
||||
# Count and list pending todos
|
||||
node gsd-tools.cjs list-todos [area]
|
||||
|
||||
# List captured seeds (optionally filter by status: dormant|active|triggered)
|
||||
node gsd-tools.cjs list-seeds [status]
|
||||
|
||||
# Check file/directory existence
|
||||
node gsd-tools.cjs verify-path-exists <path>
|
||||
|
||||
|
||||
@@ -1370,6 +1370,8 @@ Execute a trivial task inline — no subagents, no planning overhead. For typo f
|
||||
|
||||
Cross-AI peer review of phase plans from external AI CLIs.
|
||||
|
||||
Reviewers are prompted to verify the plan's claims against the actual repository source — opening the referenced files and citing `file:line` evidence with the mechanism — rather than reviewing the plan text in isolation. A reviewer that has no file access flags what it cannot verify instead of asserting it, and `file:line`-grounded findings are weighted more heavily during consensus synthesis.
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--phase N` | **Yes** | Phase number to review |
|
||||
@@ -1485,10 +1487,11 @@ Capture ideas, tasks, notes, and seeds to their appropriate destination. Default
|
||||
| `--backlog <description>` | Add to the backlog parking lot using 999.x numbering |
|
||||
| `--seed [idea summary]` | Capture a forward-looking idea with trigger conditions |
|
||||
| `--list` | List pending todos and select one to work on |
|
||||
| `--list-seeds [status]` | List/audit captured seeds, optionally filtered by status (read-only) |
|
||||
| `--global` | Use global scope (for note operations) |
|
||||
|
||||
**Backlog:** 999.x numbering keeps items outside the active phase sequence; phase directories are created immediately so `/gsd-discuss-phase` and `/gsd-plan-phase` work on them.
|
||||
**Seeds:** Preserve full WHY, WHEN to surface, and breadcrumbs — consumed by `/gsd-new-milestone`.
|
||||
**Seeds:** Preserve full WHY, WHEN to surface, and breadcrumbs — consumed by `/gsd-new-milestone`. Audit parked seeds anytime with `--list-seeds` (optionally `--list-seeds dormant`).
|
||||
|
||||
**Produces:** `.planning/todos/` (default), note files (--note), ROADMAP.md backlog section (--backlog), `.planning/seeds/SEED-NNN-slug.md` (--seed)
|
||||
|
||||
@@ -1500,6 +1503,8 @@ Capture ideas, tasks, notes, and seeds to their appropriate destination. Default
|
||||
/gsd-capture --backlog "GraphQL API layer" # Add to backlog
|
||||
/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
|
||||
/gsd-capture --list # Browse and act on todos
|
||||
/gsd-capture --list-seeds # Audit all captured seeds
|
||||
/gsd-capture --list-seeds dormant # Filter seeds by status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -1230,9 +1230,9 @@ When verification returns `human_needed`, items are persisted as a trackable HUM
|
||||
|
||||
### 43. Backlog Parking Lot
|
||||
|
||||
**Commands:** `/gsd-capture --backlog <description>`, `/gsd-review-backlog`, `/gsd-capture --seed <idea>`
|
||||
**Commands:** `/gsd-capture --backlog <description>`, `/gsd-review-backlog`, `/gsd-capture --seed <idea>`, `/gsd-capture --list-seeds [status]`
|
||||
|
||||
**Purpose:** Capture ideas that aren't ready for active planning. Backlog items use 999.x numbering to stay outside the active phase sequence. Seeds are forward-looking ideas with trigger conditions that surface automatically at the right milestone.
|
||||
**Purpose:** Capture ideas that aren't ready for active planning. Backlog items use 999.x numbering to stay outside the active phase sequence. Seeds are forward-looking ideas with trigger conditions that surface automatically at the right milestone. `--list-seeds` provides a read-only audit of all parked seeds (with optional status filter) without waiting for the next milestone.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-BACKLOG-01: Backlog items MUST use 999.x numbering to stay outside active phase sequence
|
||||
@@ -1241,6 +1241,7 @@ When verification returns `human_needed`, items are persisted as a trackable HUM
|
||||
- REQ-BACKLOG-04: Promoted items MUST be renumbered into the active milestone sequence
|
||||
- REQ-SEED-01: Seeds MUST capture the full WHY and WHEN to surface conditions
|
||||
- REQ-SEED-02: `/gsd-new-milestone` MUST scan seeds and present matches
|
||||
- REQ-SEED-03: `/gsd-capture --list-seeds` MUST list seeds with status, scope, and trigger for audit, with optional status filtering
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|
||||
@@ -147,6 +147,7 @@
|
||||
"ingest-docs.md",
|
||||
"insert-phase.md",
|
||||
"list-phase-assumptions.md",
|
||||
"list-seeds.md",
|
||||
"list-workspaces.md",
|
||||
"manager.md",
|
||||
"map-codebase.md",
|
||||
|
||||
@@ -215,6 +215,7 @@ Full roster at `gsd-core/workflows/*.md`. Workflows are thin orchestrators that
|
||||
| `ingest-docs.md` | Scan a repo for mixed planning docs; classify, synthesize, and bootstrap or merge into `.planning/` with a conflicts report. | `/gsd-ingest-docs` |
|
||||
| `insert-phase.md` | Insert a decimal phase for urgent work discovered mid-milestone. | `/gsd-phase --insert` |
|
||||
| `list-phase-assumptions.md` | Surface Claude's assumptions about a phase before planning. | `/gsd-discuss-phase --assumptions` |
|
||||
| `list-seeds.md` | List and audit captured seeds (read-only), with optional status filter. | `/gsd-capture --list-seeds` |
|
||||
| `list-workspaces.md` | List all GSD workspaces found in `~/gsd-workspaces/` with their status. | `/gsd-workspace --list` |
|
||||
| `manager.md` | Interactive milestone command center — dashboard, inline discuss, background plan/execute. | `/gsd-manager` |
|
||||
| `map-codebase.md` | Orchestrate parallel codebase mapper agents to produce `.planning/codebase/` docs. | `/gsd-map-codebase` |
|
||||
|
||||
@@ -334,6 +334,15 @@ Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, s
|
||||
|
||||
`/gsd-new-milestone` scans all seeds and presents matches. **Storage:** `.planning/seeds/SEED-NNN-slug.md`
|
||||
|
||||
Once you've parked a few, audit them on demand instead of waiting for the next milestone to surface them:
|
||||
|
||||
```bash
|
||||
/gsd-capture --list-seeds # Review every parked seed
|
||||
/gsd-capture --list-seeds dormant # Narrow to one status
|
||||
```
|
||||
|
||||
This is read-only — it renders an audit table (ID, status, scope, trigger, title) and a per-status summary, and never modifies a seed. Filter by `dormant`, `active`, or `triggered` when you only want to see seeds in one state.
|
||||
|
||||
### Persistent Context Threads
|
||||
|
||||
Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-1016: Runtime Capability Descriptor
|
||||
|
||||
- **Status:** Proposed
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-06-10
|
||||
- **Issue:** [#1016](https://github.com/open-gsd/gsd-core/issues/1016)
|
||||
- **Epic:** [#857](https://github.com/open-gsd/gsd-core/issues/857) (Capability system) — rollout phase 5
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-1235: Migrate agent conversion to the descriptor-driven install path
|
||||
|
||||
- **Status:** Proposed
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-06-14
|
||||
- **Issue:** #1235
|
||||
- **Builds on:** [ADR-3660](3660-runtime-artifact-layout-module.md) (runtime artifact layout), [ADR-457](457-generated-cjs-single-source.md) (the `src/*.cts` build-at-publish tree the converters live in), [ADR-1016](1016-runtime-capability-descriptor.md) (runtime capability descriptor)
|
||||
|
||||
97
docs/adr/1593-skill-mapping-converter-methodology.md
Normal file
97
docs/adr/1593-skill-mapping-converter-methodology.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Skill mapping & converter methodology across runtimes
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-06-22
|
||||
- **Issue:** [#1593](https://github.com/open-gsd/gsd-core/issues/1593)
|
||||
- **Epic:** [#1258](https://github.com/open-gsd/gsd-core/issues/1258) (Phase A — *"do first"*)
|
||||
- **Extends:** [ADR-3660](3660-runtime-artifact-layout-module.md) (layout), [ADR-1016](1016-runtime-capability-descriptor.md) (enum — accepted here)
|
||||
- **Sibling:** [ADR-1508](1508-runtime-artifact-conversion-module.md) (module ownership), [ADR-766](766-claude-code-plugin-manifest-module.md) (Claude plugin manifest)
|
||||
|
||||
## Context
|
||||
|
||||
GSD installs skills into 16 host CLIs (claude, codex, gemini, opencode, kilo, cursor, copilot, antigravity, windsurf, augment, trae, qwen, hermes, codebuddy, cline, kimi). The methodology governing *how* a source command file in `commands/gsd/*.md` becomes an installed skill on each runtime is real, load-bearing, and documented in fragments across three sources that disagree on what they own:
|
||||
|
||||
1. **[ADR-3660](3660-runtime-artifact-layout-module.md)** (Accepted) — owns the *structural* layout: the `{ kind, destSubpath, prefix, nesting, recursive, converter }` `ArtifactKindDescriptor` shape, per-runtime dest path, the `gsd-` prefix, flat-vs-nested under `gsd-ns-*` routers, and the `stage` closure contract binding each layout to its converter. ADR-3660 says where artifacts go; it does not describe what the converters *do*.
|
||||
2. **[ADR-1016](1016-runtime-capability-descriptor.md)** (header Status: Proposed — **corrected to Accepted by this ADR**, see Decision 2) — owns the closed `ConverterName` enum and declares `artifactLayout` as descriptor data. Vocabulary only: it closes the set of named converters; it does not describe each converter's transform contract.
|
||||
3. **`src/runtime-artifact-conversion.cts`** (~2,600 lines, the converter functions) — the actual per-runtime transform semantics: frontmatter filtering, tool-name rewrites, path rewrites, namespacing, description truncation, SKILL.md-vs-flat body format. **No ADR.** A future maintainer (human or agent) has no single place that says "this converter rewrites X, drops Y, truncates at Z."
|
||||
|
||||
A just-merged sibling — **[ADR-1508](1508-runtime-artifact-conversion-module.md)** (PR #1509, 2026-06-21) — owns *module ownership + dependency direction* for the conversion engine. Its body explicitly defers the methodology to this ADR: *"Distinct from epic #1258: #1258 Phase A documents the converter transform-contract catalog; this ADR decides module ownership + dependency direction."* The module now has a home; the *methodology it implements* did not.
|
||||
|
||||
Two concrete failures fall out of this documentation gap (surfaced while triaging #1243):
|
||||
|
||||
1. **Consumption:** `agent_skills`'s `global:` resolver hand-resolved a file path and could not reach plugin-provided skills. The resolution (PR #1261, Claude consume side) had to reverse-engineer the converter + layout + the platform's native skill-resolution mechanism separately because no ADR described how they relate.
|
||||
2. **Provision:** GSD ships as a first-party plugin/extension on multiple platforms (`.claude-plugin/plugin.json` per ADR-766, `gemini-extension.json` per #775), but those manifests do not provide GSD's skills the platform-native way — the Claude manifest declares `commands` + `hooks`, no `skills`. No ADR states the provision methodology each platform demands.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. This ADR is the single authoritative description of the per-runtime skill mapping and converter transform contracts
|
||||
|
||||
It codifies — in one place — what ADR-3660 (layout), ADR-1016 (vocabulary), and `runtime-artifact-conversion.cts` (semantics) each carry a third of. The companion reference page, [`docs/reference/skill-mapping-matrix.md`](../reference/skill-mapping-matrix.md), holds the maintainable per-runtime table; this ADR holds the *decisions* behind it. **References, does not duplicate, ADR-3660** (the layout owner) — extends it with the converter + mapping methodology.
|
||||
|
||||
### 2. ADR-1016's `ConverterName` enum is Accepted (header correction)
|
||||
|
||||
ADR-1016's header says `Proposed`, but its `ConverterName` closed enum is **already code-enforced**: `gsd-core/bin/lib/capability-validator.cjs` rejects unknown converter names (*"is not a known ConverterName"*), and the enum is locked by a fail-first regression test at `tests/capability-registry.test.cjs:3956` (ADR-857 phase 5e). The decision is realized; the record is stale. This ADR accepts the enum and the ADR-1016 header is corrected `Proposed` → `Accepted` as a metadata correction (no behavior change).
|
||||
|
||||
The closed enum `VALID_CONVERTER_NAMES` (`capability-validator.cjs:651-678`) holds **24 names** in two blocks:
|
||||
|
||||
- **15 commands/skills converters** — the block ADR-1016's *"15 named first-party functions covering the 16 runtimes"* refers to. Of these, 13 are skill converters and 2 are command converters (`convertClaudeCommandToCodebuddyCommand`, `convertClaudeCommandToCursorCommand`). Three runtimes share `convertClaudeCommandToClaudeSkill` (claude, qwen, hermes), so the 15 skill-bearing runtimes (all except commands-only Gemini) resolve to 13 distinct skill converters.
|
||||
- **9 agent converters** (`convertClaudeAgentTo{Copilot,Antigravity,Cursor,Windsurf,Augment,Trae,Codebuddy,Cline,Codex}Agent`) — added by #1173 for the descriptor-driven agent-conversion wiring (ADR-1235). These are not yet declared by any runtime's `agents` kind descriptor (the `convertedAgentsKind` builder exists but the declarations are deferred to a #1173 follow-up; the legacy `bin/install.js` agent loop remains authoritative).
|
||||
|
||||
### 3. The converter transform-contract categories
|
||||
|
||||
Every skill converter in `runtime-artifact-conversion.cts` composes some subset of eight transform categories. This is the catalog ADR-1508 deferred:
|
||||
|
||||
| # | Category | What it does | Representative functions |
|
||||
|---|----------|--------------|--------------------------|
|
||||
| 1 | **Frontmatter extraction & reconstruction** | Extract `(name, description, allowed-tools, argument-hint, agent, context, effort)` from the source command frontmatter; reconstruct in the runtime's skill frontmatter shape. | `extractFrontmatterAndBody`, `skillFrontmatterName`, every `convertClaudeCommandTo*Skill` |
|
||||
| 2 | **Description truncation** | Runtimes with description-length limits truncate to the cap (e.g. Codex: 180 chars → `metadata.short-description`). | `convertClaudeCommandToCodexSkill` (`toSingleLine` + 177-char slice) |
|
||||
| 3 | **Tool-name rewrites** | Map Claude tool names to runtime equivalents. | `convertToolName`, `convertKimiToolName`, `convertCopilotToolName`, `convertGeminiToolName`; inline: `AskUserQuestion`→`question`, `SlashCommand`→`skill` (opencode) |
|
||||
| 4 | **Path rewrites** | `~/.claude` → the runtime's config path; `computePathPrefix` derives the install-target prefix; `transformContentToHyphen` normalizes `/gsd:<cmd>` → `gsd-<cmd>`. | `computePathPrefix`, `applyOpencodeFamilyPathPrefix`, `convertClaudeToOpencodeFrontmatter` |
|
||||
| 5 | **Slash-command → skill-mention conversion** | For runtimes that surface skills (not slash commands), rewrite `/gsd:<cmd>` invocations into skill-tool mentions. | `convertSlashCommandsTo{Cursor,Windsurf,Augment,Trae,Codebuddy}SkillMentions` |
|
||||
| 6 | **Runtime-specific branding / fields** | Emit runtime-required frontmatter the source does not carry. | Hermes: `version:`; Qwen: numeric `priority:` (`QWEN_SKILL_PRIORITY`); Codex: `metadata.short-description`; Kimi: name normalization |
|
||||
| 7 | **Agent-reference neutralization** | For non-Claude runtimes, replace "Claude" → "the agent" and `CLAUDE.md` → the runtime's instruction file. | `neutralizeAgentReferences` |
|
||||
| 8 | **Body format (SKILL.md-vs-flat)** | Governed by the layout `nesting` flag + the `stage` closure: nested runtimes ship `<router>/skills/<name>/SKILL.md`; flat runtimes ship `<prefix><stem>/SKILL.md` at one level. | `stageSkillsForRuntimeAsSkills` (in `install-profiles.cts`), `buildNamespaceBundleMap` |
|
||||
|
||||
A converter's contract is the fixed subset of these eight categories it applies, in order. **Transform order is load-bearing for byte-parity** (cf. ADR-1235 §0): stale-cleanup → path-prefix rewrite → `processAttribution` → runtime converter/branding → body normalization → filename rename. A converter that silently inherits another's ordering breaks byte-for-byte parity without a test signal.
|
||||
|
||||
### 4. The per-runtime skill mapping
|
||||
|
||||
The full 16-runtime matrix — dest path, prefix, nesting, loader recursion, converter, and per-runtime notes — lives in the companion reference page: [`docs/reference/skill-mapping-matrix.md`](../reference/skill-mapping-matrix.md). The authoritative source for any cell is the runtime's `capabilities/<runtime>/capability.json` `artifactLayout` descriptor (resolved by `resolveRuntimeArtifactLayout` in `runtime-artifact-layout.cts`); the reference page is the human-readable projection, kept in sync going forward.
|
||||
|
||||
Three structural facts the matrix encodes:
|
||||
|
||||
- **All 15 skill-bearing runtimes use `prefix: "gsd-"`.** (Gemini is commands-only — no skills kind.)
|
||||
- **Six runtimes nest** under `gsd-ns-*` routers (cline, qwen, hermes, augment, trae, antigravity) because their skill loaders scan one level deep; the rest stay flat because their loaders recurse (cursor, opencode, kilo) or because nesting was reverted (claude — Skill-tool errors on unknown names, #924).
|
||||
- **Three runtimes share `convertClaudeCommandToClaudeSkill`** (claude, qwen, hermes); the other 12 skill-bearing runtimes each have a dedicated converter.
|
||||
|
||||
### 5. Plugin / external-skill provision + consumption methodology
|
||||
|
||||
GSD's first-party plugin/extension on every supported platform should both **provide** its own skills and **consume** external/plugin-provided skills through each platform's *documented, native* mechanism — **never** by reaching into an undocumented or ephemeral cache.
|
||||
|
||||
**Provision** — ship GSD's skills the platform-native way:
|
||||
- **Claude Code:** the `.claude-plugin/plugin.json` manifest should declare a `skills` field / `skills/` dir (today it declares only `commands` + `hooks`, per ADR-766). This is Phase B-provide / Phase D.
|
||||
- **Other platforms:** assessed per-platform in Phase C; where a platform has no documented skill-provision model, record N/A with rationale.
|
||||
|
||||
**Consumption** — resolve plugin/external skills through the platform's native skill-resolution mechanism:
|
||||
- **Claude Code:** the sub-agent `skills:` frontmatter preload (full content injected) and the runtime `Skill` tool (loads a namespaced skill by name). PR #1261 (Phase B consume side, merged 2026-06-15) is the reference implementation: `agent_skills` accepts the namespaced form `global:<plugin>:<skill>` and emits a by-name Skill-tool directive — no cache path is ever read.
|
||||
- **Other platforms:** assessed per-platform in Phase C.
|
||||
|
||||
**Rejected:** reading another plugin's ephemeral cache (e.g. Claude Code's `${CLAUDE_PLUGIN_ROOT}` / `~/.claude/plugins/cache`, which *"changes when the plugin updates"*), or copying skill files to undocumented locations. These are workarounds, not fixes — the platform's native mechanism is the contract.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **+** One authoritative description of the per-runtime skill mapping + converter transform contracts. A future maintainer or agent reads this ADR + the reference matrix instead of reverse-engineering three sources.
|
||||
- **+** Unblocks Phases B-provide, C (C1–C6), and D of epic #1258 — each per-platform implementation cites this ADR as its methodology contract.
|
||||
- **+** ADR-1016's header reflects reality (Accepted, not Proposed) — the ADR README index is corrected.
|
||||
- **+** Closes the documentation leak adjacent to ADR-1508: the module has a home (ADR-1508), the methodology it implements has a record (this ADR).
|
||||
- **−** The reference matrix must stay in sync with the capability descriptors. The descriptors (`capabilities/<runtime>/capability.json` `artifactLayout`) remain the source of truth; the reference page is a projection. A future runtime addition must update both the descriptor and the matrix row (the descriptor's `TypeError` on unknown runtime is the structural guard; the matrix drift is a documentation gap, not a runtime failure).
|
||||
- **−** The eight transform-contract categories are descriptive, not type-enforced. A converter that grows a ninth category does not trip a gate — the closed `ConverterName` enum (ADR-1016) gates the *set* of converters, not the *shape* of each converter's transform.
|
||||
|
||||
## Relationship to other ADRs and issues
|
||||
|
||||
- **[ADR-3660](3660-runtime-artifact-layout-module.md)** (layout owner, Accepted) — extended, not duplicated. This ADR documents the converter contracts that ADR-3660's `stage` closure binds but does not describe.
|
||||
- **[ADR-1016](1016-runtime-capability-descriptor.md)** (enum owner, header corrected to Accepted here) — the closed `ConverterName` enum is the type-enforcement substrate; this ADR documents what each named converter *does*.
|
||||
- **[ADR-1508](1508-runtime-artifact-conversion-module.md)** (module owner, Accepted) — sibling. ADR-1508 decides *module ownership + dependency direction*; this ADR decides *methodology + transform contracts*. ADR-1508's Phase 1–2 implementation (epic #1507, relocating helpers inside `runtime-artifact-conversion.cts`) touches the same file this ADR documents — they are sequenced, not conflicting.
|
||||
- **[ADR-766](766-claude-code-plugin-manifest-module.md)** (Claude plugin manifest, Accepted) — referenced for the provision methodology (the `skills` manifest field Phase B-provide / Phase D adds).
|
||||
- **[ADR-1235](1235-descriptor-driven-agent-conversion-migration.md)** (descriptor-driven agent conversion) — complementary; its byte-parity transform-ordering rule is cited in Decision 3.
|
||||
- **Epic [#1258](https://github.com/open-gsd/gsd-core/issues/1258)** — this is Phase A. Phase B-consume (PR #1261, merged) is the reference implementation canonized in Decision 5. Phases B-provide, C (C1–C6), D are tracked as separate issues per the epic's governance.
|
||||
@@ -68,3 +68,13 @@ To keep the Seam honest about where the plugin contract ends:
|
||||
- Installer Module (`bin/install.js`) — owns the `settings.json` always-on hook wiring this Module mirrors for the plugin path.
|
||||
- `CONTEXT.md` § Glossary — Domain modules and seams (where this Module is registered).
|
||||
- Claude Code plugin contract: <https://code.claude.com/docs/en/plugins-reference>.
|
||||
|
||||
## Amendment 2026-06-22 — Skills surface projection (#1596)
|
||||
|
||||
The original mapping table projected commands + hooks but omitted skills. Phase B-provide of epic #1258 adds the skills surface:
|
||||
|
||||
| gsd-core surface / source | Claude Code plugin field | Rule / invariant |
|
||||
|---|---|---|
|
||||
| Skill surface (`commands/gsd/*.md` → build-converted) | `skills: "./skills/"` | A `skills/` dir of build-generated `gsd-<stem>/SKILL.md` files, produced by `scripts/gen-plugin-skills.cjs` running `convertClaudeCommandToClaudeSkill` (the same converter the file-copy installer uses). Generated at build time (`npm run build`) and committed (consistent with ADR-457's generated-committed-output pattern). This closes the gap where plugin-only installs lacked the skill surface because `bin/install.js` never ran. Methodology defined by ADR-1593 §5. |
|
||||
|
||||
The `skills/` dir is **generated, not hand-authored** — `scripts/gen-plugin-skills.cjs --check` verifies staleness. The conformance test (`tests/issue-766-plugin-manifest.test.cjs` Section H) asserts the manifest field, dir presence, frontmatter validity, and count parity with `commands/gsd/*.md` (`DEFECT.GENERATIVE-FIX`).
|
||||
|
||||
@@ -48,7 +48,7 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop
|
||||
| [15-autonomous-cross-ai-convergence.md](15-autonomous-cross-ai-convergence.md) | Cross-AI plan convergence via existing orchestration commands | Proposed |
|
||||
| [22-plan-drift-guard.md](22-plan-drift-guard.md) | Plan-vs-codebase drift guard: defaults and symbol-resolver seam | Proposed |
|
||||
| [3524-cjs-sdk-hard-seam.md](3524-cjs-sdk-hard-seam.md) | CJS↔SDK hard seam — single canonical owner per responsibility (#3524) | Superseded by ADR-0174 |
|
||||
| [3660-runtime-artifact-layout-module.md](3660-runtime-artifact-layout-module.md) | Runtime Artifact Layout Module owns per-runtime artifact placement | Proposed |
|
||||
| [3660-runtime-artifact-layout-module.md](3660-runtime-artifact-layout-module.md) | Runtime Artifact Layout Module owns per-runtime artifact placement | Accepted |
|
||||
| [0174-retire-gsd-sdk-package-boundary.md](0174-retire-gsd-sdk-package-boundary.md) | Retire @opengsd/gsd-sdk package boundary — single-runtime collapse | Accepted |
|
||||
| [452-eslint-lint-harness.md](452-eslint-lint-harness.md) | Adopt standard ESLint flat-config lint harness; retire homegrown regex scanners | Accepted |
|
||||
| [456-test-rigor-architecture.md](456-test-rigor-architecture.md) | Test-rigor architecture — deterministic scheduling, antagonistic tier, typed-surface mandate, delete-bad-tests policy | Accepted |
|
||||
@@ -56,10 +56,11 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop
|
||||
| [660-release-from-next-head.md](660-release-from-next-head.md) | Release from the head of next; immutable release tags; @next dist-tag as the RC surface | Proposed |
|
||||
| [58-runtime-install-policy-module.md](58-runtime-install-policy-module.md) | Runtime Install Policy Module owns the typed install-plan projection | Accepted |
|
||||
| [766-claude-code-plugin-manifest-module.md](766-claude-code-plugin-manifest-module.md) | Claude Code Plugin Manifest Module owns the projection of gsd-core surfaces onto the Claude Code plugin contract | Accepted |
|
||||
| [1016-runtime-capability-descriptor.md](1016-runtime-capability-descriptor.md) | Runtime Capability Descriptor | Proposed |
|
||||
| [1016-runtime-capability-descriptor.md](1016-runtime-capability-descriptor.md) | Runtime Capability Descriptor | Accepted |
|
||||
| [1235-descriptor-driven-agent-conversion-migration.md](1235-descriptor-driven-agent-conversion-migration.md) | Migrate agent conversion to the descriptor-driven install path (parity + per-runtime cutover) | Proposed |
|
||||
| [1411-resolution-provenance.md](1411-resolution-provenance.md) | Resolution must report provenance, not fall open silently | Accepted |
|
||||
| [1508-runtime-artifact-conversion-module.md](1508-runtime-artifact-conversion-module.md) | Runtime Artifact Conversion Module owns per-runtime content rewriting | Accepted |
|
||||
| [1593-skill-mapping-converter-methodology.md](1593-skill-mapping-converter-methodology.md) | Skill mapping & converter methodology across runtimes | Accepted |
|
||||
|
||||
## Seam map
|
||||
|
||||
|
||||
82
docs/reference/skill-mapping-matrix.md
Normal file
82
docs/reference/skill-mapping-matrix.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Per-runtime skill mapping matrix
|
||||
|
||||
> **Reference** page. The authoritative source for every cell is the runtime's `capabilities/<runtime>/capability.json` `artifactLayout` descriptor, resolved by `resolveRuntimeArtifactLayout` in `gsd-core/src/runtime-artifact-layout.cts`. This page is the human-readable projection; when they disagree, the descriptor wins.
|
||||
>
|
||||
> **Decision record:** [ADR-1593 — Skill mapping & converter methodology across runtimes](../adr/1593-skill-mapping-converter-methodology.md). See also [ADR-3660](../adr/3660-runtime-artifact-layout-module.md) (layout owner) and [ADR-1016](../adr/1016-runtime-capability-descriptor.md) (converter enum).
|
||||
|
||||
## How to read this matrix
|
||||
|
||||
GSD ships skills (and commands/agents) as Markdown files under `commands/gsd/*.md`. Each runtime installs them via a per-runtime **layout** (where they go) and a per-runtime **converter** (how their content is rewritten). The layout is a typed `ArtifactKindDescriptor`:
|
||||
|
||||
```
|
||||
{ kind, destSubpath, prefix, nesting, recursive, converter }
|
||||
```
|
||||
|
||||
- **dest** — the destination subpath under the runtime's config dir (e.g. `skills`, `skills/gsd`).
|
||||
- **prefix** — the filename/dir prefix (`gsd-` for every skill-bearing runtime).
|
||||
- **nesting** — `flat` (skills at one level) or `nested` (concrete skills nested under `gsd-ns-*` router dirs).
|
||||
- **loader** — whether the runtime's skill loader recurses (`recursive: true` → nesting saves nothing, so the layout stays flat).
|
||||
- **converter** — the `ConverterName` (closed enum, ADR-1016) that rewrites the source command into the runtime's skill format. `null` means raw-copy (no conversion).
|
||||
|
||||
For the transform each converter applies, see [ADR-1593 §3 — converter transform-contract categories](../adr/1593-skill-mapping-converter-methodology.md#3-the-converter-transform-contract-categories).
|
||||
|
||||
## The 16-runtime matrix
|
||||
|
||||
| Runtime | Skill dest (global) | Prefix | Nesting | Loader | Converter | Notes |
|
||||
|---------|---------------------|--------|---------|--------|-----------|-------|
|
||||
| **claude** | `skills/` | `gsd-` | flat | one-level (reverted from nested, #924) | `convertClaudeCommandToClaudeSkill` | Local scope ships commands+agents only (no `skills` kind). Plugin manifest (ADR-766) ships skills via build-generated `skills/` dir (Phase B-provide, PR #1597, merged). |
|
||||
| **codex** | `skills/` | `gsd-` | flat | unconfirmed → conservative | `convertClaudeCommandToCodexSkill` | TOML config (`configFormat: toml`). Description truncated to 180 chars (`metadata.short-description`). `sandboxTier: codex-agent-sandbox`. |
|
||||
| **gemini** | — *(no skills kind)* | — | — | — | — | Commands-only (TOML `.toml` in `commands/gsd`). No skill surface; extension model has no `skills` field (C1: N/A). |
|
||||
| **opencode** | `skills/` | `gsd-` | flat | recursive (`**` glob) | `convertClaudeCommandToOpencodeSkill` | XDG config home. Shares the opencode-family converter entry point (`convertClaudeCommandToOpencodeFamilySkill`). Also ships `command` (singular) commands. |
|
||||
| **kilo** | `skills/` | `gsd-` | flat | recursive (`**` glob) | `convertClaudeCommandToKiloSkill` | OpenCode fork; same `**` glob loader. `permissionWriter: kilo`. Also ships `command` commands. |
|
||||
| **cursor** | `skills/` | `gsd-` | flat | recursive | `convertClaudeCommandToCursorSkill` | Also ships flat `commands/` via `convertClaudeCommandToCursorCommand`. `configFormat: none`. |
|
||||
| **copilot** | `skills/` | `gsd-` | flat | unconfirmed → conservative | `convertClaudeCommandToCopilotSkill` | Markdown config. Scope-aware converter (global-home vs workspace-relative). |
|
||||
| **antigravity** | `skills/` | `gsd-` | nested | non-recursive (one-level) | `convertClaudeCommandToAntigravitySkill` | `dot-home-nested` config home. Scope-aware converter. Nesting confirmed: *"will not recursive scan"*. |
|
||||
| **windsurf** | `skills/` | `gsd-` | flat | unconfirmed → conservative | `convertClaudeCommandToWindsurfSkill` | `configFormat: none`. `installSurface: profile-marker-only`. |
|
||||
| **augment** | `skills/` | `gsd-` | nested | non-recursive (single-level) | `convertClaudeCommandToAugmentSkill` | Also ships flat `commands/`. Settings-json config. |
|
||||
| **trae** | `skills/` | `gsd-` | nested | non-recursive (flat; nesting errors) | `convertClaudeCommandToTraeSkill` | `configFormat: none`. Trae IDE (trae.ai), not trae-agent. |
|
||||
| **qwen** | `skills/` | `gsd-` | nested | non-recursive (flat readdir) | `convertClaudeCommandToClaudeSkill` | **Shares Claude's converter.** Emits numeric `priority:` (`QWEN_SKILL_PRIORITY`) for `/skills` ordering. Settings-json config. |
|
||||
| **hermes** | `skills/gsd/` | `gsd-` | nested | non-recursive (single-level probe) | `convertClaudeCommandToClaudeSkill` | **Shares Claude's converter.** `destSubpath: skills/gsd` (category dir). Emits required `version:` field. `prefix: gsd-` restored by #947. |
|
||||
| **codebuddy** | `skills/` | `gsd-` | flat | unconfirmed → conservative | `convertClaudeCommandToCodebuddySkill` | Also ships flat `commands/` via `convertClaudeCommandToCodebuddyCommand`. `dot-home` config. |
|
||||
| **cline** | `skills/` | `gsd-` | nested | non-recursive (flat `fs.readdir`) | `convertClaudeCommandToClineSkill` | **Global-only** — `local: []` (no local skill install). Targets `~/.cline/skills/<name>/SKILL.md` (Cline ≥ v3.48.0). `markdown-dir` config. |
|
||||
| **kimi** | `skills/` | `gsd-` | flat | (false) | `convertClaudeCommandToKimiSkill` | Also ships a special `kimi-agents` kind (`buildKimiAgentArtifacts`). Name normalization (`normalizeKimiSkillName`). `generic-agents-root` config. |
|
||||
|
||||
### Structural facts
|
||||
|
||||
- **All 15 skill-bearing runtimes use `prefix: "gsd-"`.** Gemini is the only runtime with no skills kind (commands-only TOML).
|
||||
- **Six runtimes nest** (cline, qwen, hermes, augment, trae, antigravity) because their skill loaders scan one level deep — nesting drops nested concrete skills out of the eager top-level listing while keeping them readable by file path (the namespace-router contract, #69).
|
||||
- **Eight runtimes stay flat**: three because their loaders recurse (cursor, opencode, kilo — nesting saves nothing), one because nesting was reverted (claude — the Skill tool errors on unknown names rather than re-routing, #924), and four conservatively where the loader depth is unconfirmed (codex, copilot, windsurf, codebuddy).
|
||||
- **Three runtimes share `convertClaudeCommandToClaudeSkill`** (claude, qwen, hermes). The converter branches on the `runtime` arg for per-runtime branding (Hermes `version:`, Qwen `priority:`).
|
||||
|
||||
## Nesting/loader verification (June 2026)
|
||||
|
||||
The nesting flag is set per the verified loader behavior of each runtime. Sources:
|
||||
|
||||
| Behavior | Runtimes | Evidence |
|
||||
|----------|----------|----------|
|
||||
| **NEST** (non-recursive / one-level scan) | cline, qwen, hermes, augment, trae, antigravity | cline `skills.ts` flat `fs.readdir`; Qwen `skill-load.ts` flat readdir; hermes single-level subdir probe; augment flat single-level; trae flat (nesting errors, Trae-AI/TRAE#2253); antigravity *"will not recursive scan"* |
|
||||
| **FLAT** (recursive loader → nesting gives no saving) | cursor, opencode, kilo | cursor walks skills root recursively; opencode `skill/index.ts` glob `skills/**/SKILL.md`; kilo (opencode fork, same `**` glob) |
|
||||
| **FLAT** (reverted from nested) | claude | anthropics/claude-code#28266 — one-level scan, but Skill-tool errors on unknown names rather than re-routing via the router (#924) |
|
||||
| **FLAT** (unconfirmed → conservative) | codex, copilot, windsurf, codebuddy | Loader depth not independently verified; kept flat to avoid mis-nesting |
|
||||
|
||||
## Plugin / external-skill provision + consumption
|
||||
|
||||
Per [ADR-1593 §5](../adr/1593-skill-mapping-converter-methodology.md#5-plugin--external-skill-provision--consumption-methodology), each platform's first-party packaging should provide and consume skills through the platform's *documented, native* mechanism.
|
||||
|
||||
| Runtime | Provision model | Consumption model | Outcome |
|
||||
|---------|-----------------|-------------------|---------|
|
||||
| **claude** | `.claude-plugin/plugin.json` `"skills": "./skills/"` — build-generated dir (PR #1597, merged) | Sub-agent `skills:` preload + runtime `Skill` tool (PR #1261, merged) | **Implemented (Phase B)** |
|
||||
| **gemini** | **N/A** — `gemini-extension.json` supports `mcpServers` + `contextFileName` only; no `skills` field. Gemini CLI SDK lists skills as a future extension primitive (*"currently not implemented"*). | **N/A** — same rationale. | **C1: N/A** |
|
||||
| **codex** | **N/A** — no plugin/extension manifest model. Uses `AGENTS.md` + TOML via file-copy install. | **N/A** — same rationale. | **C2: N/A** |
|
||||
| **opencode / kilo** | **N/A** — no first-party plugin manifest. Recursive `skills/**/SKILL.md` glob loader scans the local config dir that `bin/install.js` writes to. | **N/A** — same rationale. | **C3: N/A** |
|
||||
| **cursor, copilot, windsurf, codebuddy** | **N/A** — IDE-based tools with no plugin skill-provision model. File-copy install only. | **N/A** — same rationale. | **C4: N/A** |
|
||||
| **cline, qwen, hermes, augment, trae, antigravity** | **N/A** — CLI tools with no plugin marketplace model. File-copy install only. | **N/A** — same rationale. | **C5: N/A** |
|
||||
| **kimi** | **N/A** — special `kimi-agents` kind but no plugin/extension manifest. File-copy install only. | **N/A** — same rationale. | **C6: N/A** |
|
||||
|
||||
**Phase D (first-party packaging parity):** Complete. Claude Code's `.claude-plugin/plugin.json` is the only first-party manifest with a `skills` field (Phase B-provide, PR #1597). Gemini's `gemini-extension.json` is context-only (no skills field — C1 N/A). No other first-party packaging exists.
|
||||
|
||||
> **Rejected for all platforms:** reading another plugin's ephemeral/undocumented cache (e.g. Claude Code's `${CLAUDE_PLUGIN_ROOT}` / `~/.claude/plugins/cache`). The platform's native mechanism is the contract; cache-reading is a workaround, not a fix.
|
||||
|
||||
## Keeping this page in sync
|
||||
|
||||
The `capabilities/<runtime>/capability.json` `artifactLayout` descriptors are the source of truth. When a runtime's layout changes, update the descriptor first; this page is the projection. Adding a new runtime requires: (1) a new `capabilities/<runtime>/capability.json` with an `artifactLayout`, (2) a new converter in the closed `ConverterName` enum (ADR-1016), and (3) a new row in this matrix.
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "gsd-core",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
|
||||
"contextFileName": "GEMINI.md"
|
||||
}
|
||||
|
||||
@@ -25,6 +25,7 @@
|
||||
* generate-slug <text> Convert text to URL-safe slug
|
||||
* current-timestamp [format] Get timestamp (full|date|filename)
|
||||
* list-todos [area] Count and enumerate pending todos
|
||||
* list-seeds [status] List captured seeds (optional status filter)
|
||||
* verify-path-exists <path> Check file/directory existence
|
||||
* config-ensure-section Initialize .planning/config.json
|
||||
* history-digest Aggregate all SUMMARY.md data
|
||||
@@ -636,8 +637,8 @@ async function main() {
|
||||
'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
|
||||
'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
|
||||
'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
|
||||
'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
|
||||
'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
|
||||
'capability, classify-confidence, git, learnings, list-seeds, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
|
||||
'profile-sample, progress, project-instruction-file, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
|
||||
'task, template, user-story, validate, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
|
||||
'Global flags:\n' +
|
||||
' --raw Emit raw output without post-processing\n' +
|
||||
@@ -688,6 +689,10 @@ async function main() {
|
||||
'worktree', 'prompt-budget',
|
||||
'research-store', 'research-plan', 'package-legitimacy', 'classify-confidence',
|
||||
'user-story', // pure string validation — no .planning/ access needed
|
||||
// #1529: pure runtime→filename projection via getProjectInstructionFile; no
|
||||
// .planning/ access needed, and resolving project root would break workflow
|
||||
// invocations that run before .planning/ exists (new-project Step 1).
|
||||
'project-instruction-file',
|
||||
]);
|
||||
if (!SKIP_ROOT_RESOLUTION.has(command)) {
|
||||
cwd = findProjectRoot(cwd);
|
||||
@@ -1102,11 +1107,39 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
|
||||
break;
|
||||
}
|
||||
|
||||
case 'project-instruction-file': {
|
||||
// #1529: pure runtime→filename projection. Backs the
|
||||
// `gsd_run query project-instruction-file --runtime <r>` call in
|
||||
// new-project.md so the bash workflow and profile-output.cjs share one
|
||||
// source of truth (getProjectInstructionFile in runtime-name-policy.cjs).
|
||||
// No SDK bridge — pure local lookup, runs before .planning/ exists.
|
||||
const { getProjectInstructionFile } = require('./lib/runtime-name-policy.cjs');
|
||||
// Parse --runtime <value> (space or = form); default to empty so the
|
||||
// safe AGENTS.md cross-agent default applies.
|
||||
const pifArgs = args.slice(1);
|
||||
let pifRuntime = '';
|
||||
for (let i = 0; i < pifArgs.length; i++) {
|
||||
const a = pifArgs[i];
|
||||
if (a === '--runtime' && pifArgs[i + 1] !== undefined) { pifRuntime = pifArgs[++i]; continue; }
|
||||
if (a.startsWith('--runtime=')) { pifRuntime = a.slice('--runtime='.length); continue; }
|
||||
// First positional that isn't a flag also works (lenient); otherwise ignore unknown flags.
|
||||
if (!a.startsWith('-') && !pifRuntime) { pifRuntime = a; }
|
||||
}
|
||||
const filename = getProjectInstructionFile(pifRuntime);
|
||||
process.stdout.write(filename + '\n');
|
||||
break;
|
||||
}
|
||||
|
||||
case 'list-todos': {
|
||||
commands.cmdListTodos(cwd, args[1], raw);
|
||||
break;
|
||||
}
|
||||
|
||||
case 'list-seeds': {
|
||||
commands.cmdListSeeds(cwd, args[1], raw);
|
||||
break;
|
||||
}
|
||||
|
||||
case 'verify-path-exists': {
|
||||
commands.cmdVerifyPathExists(cwd, args[1], raw);
|
||||
break;
|
||||
|
||||
@@ -10,7 +10,7 @@ const capabilities = {
|
||||
"ai-integration": {
|
||||
"id": "ai-integration",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -63,7 +63,7 @@ const capabilities = {
|
||||
"antigravity": {
|
||||
"id": "antigravity",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Antigravity",
|
||||
"description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; nested skill layout; tier-1 support.",
|
||||
"tier": "core",
|
||||
@@ -123,7 +123,7 @@ const capabilities = {
|
||||
"audit": {
|
||||
"id": "audit",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -160,7 +160,7 @@ const capabilities = {
|
||||
"augment": {
|
||||
"id": "augment",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -229,7 +229,7 @@ const capabilities = {
|
||||
"claude": {
|
||||
"id": "claude",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Claude Code",
|
||||
"description": "Anthropic Claude Code — primary development runtime; tier-1 support with full hook surface and skills-based global install.",
|
||||
"tier": "core",
|
||||
@@ -295,7 +295,7 @@ const capabilities = {
|
||||
"cline": {
|
||||
"id": "cline",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -338,7 +338,7 @@ const capabilities = {
|
||||
"code-review": {
|
||||
"id": "code-review",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Code review",
|
||||
"description": "Source-file code review and review-fix workflow support for completed execution work.",
|
||||
"tier": "full",
|
||||
@@ -399,7 +399,7 @@ const capabilities = {
|
||||
"codebuddy": {
|
||||
"id": "codebuddy",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "CodeBuddy",
|
||||
"description": "CodeBuddy (Tencent) — converted commands + skills artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -468,7 +468,7 @@ const capabilities = {
|
||||
"codex": {
|
||||
"id": "codex",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -521,7 +521,7 @@ const capabilities = {
|
||||
"copilot": {
|
||||
"id": "copilot",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -574,7 +574,7 @@ const capabilities = {
|
||||
"cursor": {
|
||||
"id": "cursor",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -643,7 +643,7 @@ const capabilities = {
|
||||
"drift": {
|
||||
"id": "drift",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Drift detection gates",
|
||||
"description": "Post-execution drift detection gates that run after each wave completes. Provides two gates 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).",
|
||||
"tier": "full",
|
||||
@@ -707,7 +707,7 @@ const capabilities = {
|
||||
"gap-analysis": {
|
||||
"id": "gap-analysis",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -748,7 +748,7 @@ const capabilities = {
|
||||
"gemini": {
|
||||
"id": "gemini",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Gemini CLI",
|
||||
"description": "Google Gemini CLI — commands-only artifact layout (TOML); Gemini hook event dialect; settings-json hook surface; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -805,7 +805,7 @@ const capabilities = {
|
||||
"graphify": {
|
||||
"id": "graphify",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -846,7 +846,7 @@ const capabilities = {
|
||||
"hermes": {
|
||||
"id": "hermes",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -899,7 +899,7 @@ const capabilities = {
|
||||
"intel": {
|
||||
"id": "intel",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -951,7 +951,7 @@ const capabilities = {
|
||||
"kilo": {
|
||||
"id": "kilo",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1026,7 +1026,7 @@ const capabilities = {
|
||||
"kimi": {
|
||||
"id": "kimi",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1082,7 +1082,7 @@ const capabilities = {
|
||||
"mempalace": {
|
||||
"id": "mempalace",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1256,7 +1256,7 @@ const capabilities = {
|
||||
"nyquist": {
|
||||
"id": "nyquist",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Nyquist validation",
|
||||
"description": "Validation coverage audit that maps executed work back to tests and manual-only evidence.",
|
||||
"tier": "full",
|
||||
@@ -1306,7 +1306,7 @@ const capabilities = {
|
||||
"opencode": {
|
||||
"id": "opencode",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1376,7 +1376,7 @@ const capabilities = {
|
||||
"pattern-mapper": {
|
||||
"id": "pattern-mapper",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Pattern mapping",
|
||||
"description": "Optional codebase-pattern mapping before planning; owns the pattern mapper agent and workflow.pattern_mapper activation key.",
|
||||
"tier": "full",
|
||||
@@ -1430,7 +1430,7 @@ const capabilities = {
|
||||
"profile-pipeline": {
|
||||
"id": "profile-pipeline",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1507,7 +1507,7 @@ const capabilities = {
|
||||
"qwen": {
|
||||
"id": "qwen",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Qwen Code",
|
||||
"description": "Qwen Code (Alibaba) — nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -1564,7 +1564,7 @@ const capabilities = {
|
||||
"research": {
|
||||
"id": "research",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Phase research",
|
||||
"description": "Optional phase research before planning; owns the phase researcher agent and workflow.research activation key.",
|
||||
"tier": "standard",
|
||||
@@ -1616,7 +1616,7 @@ const capabilities = {
|
||||
"schema-gate": {
|
||||
"id": "schema-gate",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1662,7 +1662,7 @@ const capabilities = {
|
||||
"security": {
|
||||
"id": "security",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Security enforcement",
|
||||
"description": "Threat mitigation verification and ship-time security blocking for phases with security enforcement enabled.",
|
||||
"tier": "full",
|
||||
@@ -1761,7 +1761,7 @@ const capabilities = {
|
||||
"tdd": {
|
||||
"id": "tdd",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -1814,7 +1814,7 @@ const capabilities = {
|
||||
"trae": {
|
||||
"id": "trae",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Trae IDE",
|
||||
"description": "Trae IDE — nested-skill artifact layout; no hook surface (profile-marker-only config); tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -1866,7 +1866,7 @@ const capabilities = {
|
||||
"ui": {
|
||||
"id": "ui",
|
||||
"role": "feature",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "UI design contracts",
|
||||
"description": "UI-SPEC design contract + retrospective UI audit for frontend phases.",
|
||||
"tier": "full",
|
||||
@@ -1961,7 +1961,7 @@ const capabilities = {
|
||||
"windsurf": {
|
||||
"id": "windsurf",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Windsurf",
|
||||
"description": "Windsurf (Codeium) — nested under ~/.codeium/windsurf; skills-only artifact layout; no hook surface; no hook events; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -2721,7 +2721,7 @@ const runtimes = {
|
||||
"antigravity": {
|
||||
"id": "antigravity",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Antigravity",
|
||||
"description": "Google Antigravity IDE — nested under ~/.gemini/antigravity; probed across 1.x and 2.x layouts; Gemini hook event dialect; nested skill layout; tier-1 support.",
|
||||
"tier": "core",
|
||||
@@ -2781,7 +2781,7 @@ const runtimes = {
|
||||
"augment": {
|
||||
"id": "augment",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -2850,7 +2850,7 @@ const runtimes = {
|
||||
"claude": {
|
||||
"id": "claude",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Claude Code",
|
||||
"description": "Anthropic Claude Code — primary development runtime; tier-1 support with full hook surface and skills-based global install.",
|
||||
"tier": "core",
|
||||
@@ -2916,7 +2916,7 @@ const runtimes = {
|
||||
"cline": {
|
||||
"id": "cline",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -2959,7 +2959,7 @@ const runtimes = {
|
||||
"codebuddy": {
|
||||
"id": "codebuddy",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "CodeBuddy",
|
||||
"description": "CodeBuddy (Tencent) — converted commands + skills artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -3028,7 +3028,7 @@ const runtimes = {
|
||||
"codex": {
|
||||
"id": "codex",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3081,7 +3081,7 @@ const runtimes = {
|
||||
"copilot": {
|
||||
"id": "copilot",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3134,7 +3134,7 @@ const runtimes = {
|
||||
"cursor": {
|
||||
"id": "cursor",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3203,7 +3203,7 @@ const runtimes = {
|
||||
"gemini": {
|
||||
"id": "gemini",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Gemini CLI",
|
||||
"description": "Google Gemini CLI — commands-only artifact layout (TOML); Gemini hook event dialect; settings-json hook surface; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -3260,7 +3260,7 @@ const runtimes = {
|
||||
"hermes": {
|
||||
"id": "hermes",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3313,7 +3313,7 @@ const runtimes = {
|
||||
"kilo": {
|
||||
"id": "kilo",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3388,7 +3388,7 @@ const runtimes = {
|
||||
"kimi": {
|
||||
"id": "kimi",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3444,7 +3444,7 @@ const runtimes = {
|
||||
"opencode": {
|
||||
"id": "opencode",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"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",
|
||||
@@ -3514,7 +3514,7 @@ const runtimes = {
|
||||
"qwen": {
|
||||
"id": "qwen",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Qwen Code",
|
||||
"description": "Qwen Code (Alibaba) — nested-skill artifact layout; settings-json hook surface; Claude hook event dialect; tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -3571,7 +3571,7 @@ const runtimes = {
|
||||
"trae": {
|
||||
"id": "trae",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Trae IDE",
|
||||
"description": "Trae IDE — nested-skill artifact layout; no hook surface (profile-marker-only config); tier-2 support.",
|
||||
"tier": "core",
|
||||
@@ -3623,7 +3623,7 @@ const runtimes = {
|
||||
"windsurf": {
|
||||
"id": "windsurf",
|
||||
"role": "runtime",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"title": "Windsurf",
|
||||
"description": "Windsurf (Codeium) — nested under ~/.codeium/windsurf; skills-only artifact layout; no hook surface; no hook events; tier-2 support.",
|
||||
"tier": "core",
|
||||
|
||||
@@ -394,6 +394,16 @@ List pending todos and select one to work on.
|
||||
Usage: `/gsd:capture --list`
|
||||
Usage: `/gsd:capture --list api`
|
||||
|
||||
**`/gsd:capture --list-seeds [status]`**
|
||||
List and audit captured seeds (read-only).
|
||||
|
||||
- Lists all seeds with ID, status, scope, trigger, and title
|
||||
- Optional status filter (e.g., `/gsd:capture --list-seeds dormant`)
|
||||
- Does not modify any seed — enrich with `/gsd:capture --seed --enrich SEED-NNN`
|
||||
|
||||
Usage: `/gsd:capture --list-seeds`
|
||||
Usage: `/gsd:capture --list-seeds dormant`
|
||||
|
||||
### User Acceptance Testing
|
||||
|
||||
**`/gsd:verify-work [phase]`**
|
||||
|
||||
63
gsd-core/workflows/list-seeds.md
Normal file
63
gsd-core/workflows/list-seeds.md
Normal file
@@ -0,0 +1,63 @@
|
||||
<purpose>
|
||||
List captured seeds for browsing and audit, with an optional status filter. Read-only — never mutates seeds.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_seeds">
|
||||
Load seed context. An optional status filter (e.g. `dormant`, `active`, `triggered`) may follow `--list-seeds`.
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
|
||||
SEEDS=$(gsd_run list-seeds "$STATUS_FILTER")
|
||||
if [[ "$SEEDS" == @file:* ]]; then SEEDS=$(cat "${SEEDS#@file:}"); fi
|
||||
```
|
||||
|
||||
Replace `$STATUS_FILTER` with the filter token from `$ARGUMENTS` if one was given, otherwise omit it.
|
||||
|
||||
Extract from the JSON: `count`, `seeds[]` (each has `seed_id`, `status`, `scope`, `trigger_when`, `planted`, `title`), and `summary` (a `{ status: count }` map).
|
||||
</step>
|
||||
|
||||
<step name="empty_case">
|
||||
If `count` is 0:
|
||||
```
|
||||
No seeds found.
|
||||
|
||||
Plant one with /gsd:capture --seed "<forward-looking idea>".
|
||||
```
|
||||
(If a status filter was given and nothing matched, say so: `No seeds with status "<filter>".`) Exit.
|
||||
</step>
|
||||
|
||||
<step name="render_table">
|
||||
Render the seeds as a table, sorted by `seed_id` (already sorted by the tool). Truncate `trigger_when` and `title` to keep the table readable.
|
||||
|
||||
```
|
||||
Seeds
|
||||
─────────────────────────────────────────────────────────────────────
|
||||
ID Status Scope Trigger Title
|
||||
SEED-001 dormant large when websockets land Real-time collaboration
|
||||
SEED-006 triggered medium MILE-04 planning Remove legacy auth crates
|
||||
─────────────────────────────────────────────────────────────────────
|
||||
<count> seeds (<summary rendered as "N status" pairs, e.g. "1 dormant, 1 triggered">)
|
||||
```
|
||||
|
||||
Then offer next actions as plain text (no mutation here):
|
||||
```
|
||||
- /gsd:capture --seed --enrich <ID> enrich a seed with trigger, why, and scope
|
||||
- /gsd:capture --list-seeds <status> filter by status
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Seeds listed with ID, status, scope, trigger, and title
|
||||
- [ ] Status filter applied when provided
|
||||
- [ ] Empty / no-match case handled with guidance
|
||||
- [ ] Summary line shows total and per-status counts
|
||||
- [ ] No seed files were modified (read-only)
|
||||
</success_criteria>
|
||||
@@ -109,9 +109,9 @@ elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then RUNTIME="o
|
||||
else RUNTIME="claude"; fi
|
||||
```
|
||||
|
||||
Set the instruction file variable:
|
||||
Set the instruction file variable via the shared runtime-name policy adapter (`gsd-tools query project-instruction-file`, backed by `getProjectInstructionFile` in `runtime-name-policy.cjs` — the single source of truth shared with `profile-output.cjs`):
|
||||
```bash
|
||||
if [ "$RUNTIME" = "codex" ]; then INSTRUCTION_FILE="AGENTS.md"; else INSTRUCTION_FILE=".claude/CLAUDE.md"; fi
|
||||
INSTRUCTION_FILE=$(gsd_run query project-instruction-file --runtime "$RUNTIME")
|
||||
```
|
||||
|
||||
All subsequent references to the project instruction file use `$INSTRUCTION_FILE`.
|
||||
@@ -1533,7 +1533,7 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
|
||||
- `.planning/REQUIREMENTS.md`
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/STATE.md`
|
||||
- `$INSTRUCTION_FILE` (`AGENTS.md` for Codex, `.claude/CLAUDE.md` for all other runtimes)
|
||||
- `$INSTRUCTION_FILE` (runtime-derived via the shared `getProjectInstructionFile` policy: `AGENTS.md` for codex/opencode/kilo/kimi, `.github/copilot-instructions.md` for copilot, `GEMINI.md` for gemini/antigravity, `.claude/CLAUDE.md` for claude)
|
||||
|
||||
</output>
|
||||
|
||||
@@ -1555,7 +1555,7 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
|
||||
- [ ] ROADMAP.md created with phases, requirement mappings, success criteria
|
||||
- [ ] STATE.md initialized
|
||||
- [ ] REQUIREMENTS.md traceability updated
|
||||
- [ ] `$INSTRUCTION_FILE` generated with GSD workflow guidance (AGENTS.md for Codex, `.claude/CLAUDE.md` otherwise; an existing hand-crafted file without GSD markers is left untouched unless `--force`)
|
||||
- [ ] `$INSTRUCTION_FILE` generated with GSD workflow guidance (runtime-derived via the shared `getProjectInstructionFile` policy — `AGENTS.md` for codex/opencode/kilo/kimi, `.github/copilot-instructions.md` for copilot, `GEMINI.md` for gemini/antigravity, `.claude/CLAUDE.md` for claude; an existing hand-crafted file without GSD markers is left untouched unless `--force`)
|
||||
- [ ] User knows next step is `/gsd:discuss-phase 1`
|
||||
|
||||
**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
|
||||
|
||||
@@ -157,6 +157,14 @@ Provide structured feedback on plan quality, completeness, and risks.
|
||||
|
||||
## Review Instructions
|
||||
|
||||
**Verify against source — do not review the plan text in isolation.** You are running inside the project's git working tree (the current directory). The plans reference real files, migrations, routes, and tests that exist in this repo now.
|
||||
1. Open the referenced files and check each claim against the actual code.
|
||||
2. For every strength or concern, cite concrete `path/to/file:line` evidence plus the mechanism.
|
||||
3. When a plan asserts a mechanism works (a guard, a query filter, a test that exercises a path), trace whether it actually does what is claimed — do not take the plan's word for it.
|
||||
4. If you cannot read the repo (no file access), say so and downgrade that finding to an open question rather than asserting it.
|
||||
|
||||
Findings citing `file:line` evidence are weighted far more heavily than impressionistic ones; a review that only restates the plan's own claims has low value.
|
||||
|
||||
Analyze each plan and provide:
|
||||
|
||||
1. **Summary** — One-paragraph assessment
|
||||
@@ -273,7 +281,7 @@ fi
|
||||
|
||||
**CodeRabbit:**
|
||||
|
||||
Note: CodeRabbit reviews the current git diff/working tree — it does not accept a prompt or model flag. It may take up to 5 minutes. Use `timeout: 360000` on the Bash tool call.
|
||||
Note: CodeRabbit reviews the current git diff/working tree — it does not accept a prompt or model flag. It may take up to 5 minutes. Use `timeout: 360000` on the Bash tool call. The source-grounding requirement in the build_prompt Review Instructions applies only to the prompt-fed reviewers above; CodeRabbit is a diff-only reviewer and never receives it. Treat its output as a diff observation, not a grounded plan-level verdict.
|
||||
|
||||
```bash
|
||||
coderabbit review --prompt-only 2>/dev/null > /tmp/gsd-review-coderabbit-{phase}.md
|
||||
@@ -714,7 +722,7 @@ trimmed_reviewers: # only present if at least one reviewer was trimmed
|
||||
|
||||
## Consensus Summary
|
||||
|
||||
{synthesize common concerns across all reviewers}
|
||||
{synthesize common concerns across all reviewers. CodeRabbit is a diff-only reviewer (it never received the source-grounding prompt), so do not weight its verdict as a grounded plan review — fold in its diff findings, but base plan-level consensus on the prompt-fed reviewers.}
|
||||
|
||||
### Agreed Strengths
|
||||
{strengths mentioned by 2+ reviewers}
|
||||
|
||||
4
package-lock.json
generated
4
package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "@opengsd/gsd-core",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@opengsd/gsd-core",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@anthropic-ai/claude-agent-sdk": "^0.2.84",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@opengsd/gsd-core",
|
||||
"version": "1.6.0-rc.1",
|
||||
"version": "1.6.0-rc.2",
|
||||
"description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
|
||||
"bin": {
|
||||
"gsd-core": "bin/install.js",
|
||||
@@ -10,6 +10,7 @@
|
||||
"files": [
|
||||
"bin",
|
||||
"commands",
|
||||
"skills",
|
||||
"gsd-core",
|
||||
"assets",
|
||||
"agents",
|
||||
@@ -78,11 +79,12 @@
|
||||
"check:alias-drift": "node scripts/check-alias-drift.cjs",
|
||||
"check:identity-drift": "node scripts/lint-package-identity-drift.cjs",
|
||||
"check:integrity": "node scripts/check-npm-integrity.cjs",
|
||||
"build": "npm run generate:identity && npm run build:lib && npm run gen:loop-host-contract && npm run gen:capability-registry && npm run build:hooks",
|
||||
"build": "npm run generate:identity && npm run build:lib && npm run gen:plugin-skills && npm run gen:loop-host-contract && npm run gen:capability-registry && npm run build:hooks",
|
||||
"build:hooks": "node scripts/build-hooks.js",
|
||||
"build:lib": "tsc -p tsconfig.build.json",
|
||||
"generate:identity": "node scripts/generate-package-identity.cjs",
|
||||
"gen:loop-host-contract": "node scripts/gen-loop-host-contract.cjs --write",
|
||||
"gen:plugin-skills": "node scripts/gen-plugin-skills.cjs --write",
|
||||
"gen:capability-registry": "node scripts/gen-capability-registry.cjs --write",
|
||||
"prepack": "npm run build:lib",
|
||||
"prepare": "npm run build:lib",
|
||||
|
||||
117
scripts/gen-plugin-skills.cjs
Normal file
117
scripts/gen-plugin-skills.cjs
Normal file
@@ -0,0 +1,117 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* gen-plugin-skills.cjs — generates skills/gsd-<stem>/SKILL.md from
|
||||
* commands/gsd/*.md using convertClaudeCommandToClaudeSkill.
|
||||
*
|
||||
* Usage:
|
||||
* node scripts/gen-plugin-skills.cjs # print summary to stdout
|
||||
* node scripts/gen-plugin-skills.cjs --write # write skills/ dir
|
||||
* node scripts/gen-plugin-skills.cjs --check # exit 1 if committed skills/ is stale
|
||||
*
|
||||
* #1596 Phase B-provide. The Claude Code plugin contract discovers skills from
|
||||
* a skills/ directory (plugins-reference). GSD's source-of-truth commands live
|
||||
* in commands/gsd/*.md (command frontmatter); this script converts each to
|
||||
* skill format using the same convertClaudeCommandToClaudeSkill the file-copy
|
||||
* installer uses, producing a build-generated skills/ dir that ships in the
|
||||
* npm package and serves plugin-only installs.
|
||||
*
|
||||
* Depends on: gsd-core/bin/lib/runtime-artifact-conversion.cjs (compiled from
|
||||
* src/runtime-artifact-conversion.cts by `npm run build:lib`). Must run AFTER
|
||||
* build:lib in the build chain.
|
||||
*/
|
||||
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
const ROOT = path.resolve(__dirname, '..');
|
||||
const COMMANDS_DIR = path.join(ROOT, 'commands', 'gsd');
|
||||
const SKILLS_DIR = path.join(ROOT, 'skills');
|
||||
const CONVERSION_MODULE = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'runtime-artifact-conversion.cjs');
|
||||
const PREFIX = 'gsd-';
|
||||
const RUNTIME = 'claude';
|
||||
|
||||
function generateSkills(conversion) {
|
||||
const cmdNames = conversion.readGsdCommandNames();
|
||||
const files = fs.readdirSync(COMMANDS_DIR).filter(f => f.endsWith('.md'));
|
||||
const results = [];
|
||||
for (const file of files) {
|
||||
const stem = file.slice(0, -3);
|
||||
const skillName = PREFIX + stem;
|
||||
const src = fs.readFileSync(path.join(COMMANDS_DIR, file), 'utf8');
|
||||
const converted = conversion.convertClaudeCommandToClaudeSkill(src, skillName, RUNTIME, cmdNames, true);
|
||||
results.push({ skillName, content: converted });
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = new Set(process.argv.slice(2));
|
||||
const WRITE = args.has('--write');
|
||||
const CHECK = args.has('--check');
|
||||
|
||||
if (!fs.existsSync(CONVERSION_MODULE)) {
|
||||
throw new ExitError(
|
||||
1,
|
||||
`gen-plugin-skills: ${path.relative(ROOT, CONVERSION_MODULE)} not found.\n` +
|
||||
'Run `npm run build:lib` first (this script depends on the compiled converter).'
|
||||
);
|
||||
}
|
||||
const conversion = require(CONVERSION_MODULE);
|
||||
const results = generateSkills(conversion);
|
||||
|
||||
if (WRITE) {
|
||||
fs.rmSync(SKILLS_DIR, { recursive: true, force: true });
|
||||
fs.mkdirSync(SKILLS_DIR, { recursive: true });
|
||||
for (const { skillName, content } of results) {
|
||||
const skillDir = path.join(SKILLS_DIR, skillName);
|
||||
fs.mkdirSync(skillDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
|
||||
}
|
||||
process.stdout.write(`gen-plugin-skills: wrote ${results.length} skills to ${path.relative(ROOT, SKILLS_DIR)}/\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (CHECK) {
|
||||
if (!fs.existsSync(SKILLS_DIR)) {
|
||||
throw new ExitError(1, 'gen-plugin-skills: skills/ missing. Run: npm run gen:plugin-skills -- --write');
|
||||
}
|
||||
let stale = 0;
|
||||
const expectedNames = new Set(results.map(r => r.skillName));
|
||||
for (const { skillName, content } of results) {
|
||||
const skillMd = path.join(SKILLS_DIR, skillName, 'SKILL.md');
|
||||
if (!fs.existsSync(skillMd)) {
|
||||
process.stderr.write(`gen-plugin-skills: missing ${path.relative(ROOT, skillMd)}\n`);
|
||||
stale++;
|
||||
continue;
|
||||
}
|
||||
if (fs.readFileSync(skillMd, 'utf8') !== content) {
|
||||
process.stderr.write(`gen-plugin-skills: stale ${path.relative(ROOT, skillMd)}\n`);
|
||||
stale++;
|
||||
}
|
||||
}
|
||||
const existingDirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
|
||||
.filter(e => e.isDirectory() && e.name.startsWith(PREFIX));
|
||||
for (const dir of existingDirs) {
|
||||
if (!expectedNames.has(dir.name)) {
|
||||
process.stderr.write(`gen-plugin-skills: stale (no source) ${path.relative(ROOT, path.join(SKILLS_DIR, dir.name))}\n`);
|
||||
stale++;
|
||||
}
|
||||
}
|
||||
if (stale > 0) {
|
||||
throw new ExitError(1, `gen-plugin-skills: ${stale} stale skill(s). Run: npm run gen:plugin-skills -- --write`);
|
||||
}
|
||||
process.stdout.write(`gen-plugin-skills: ${results.length} skills up to date\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
`gen-plugin-skills: would write ${results.length} skills to ${path.relative(ROOT, SKILLS_DIR)}/\n` +
|
||||
' (use --write to generate, --check to verify staleness)\n'
|
||||
);
|
||||
return 0;
|
||||
}
|
||||
|
||||
runMain(main);
|
||||
@@ -78,6 +78,7 @@ ALLOWLIST=(
|
||||
'hooks/gsd-read-injection-scanner.js'
|
||||
'tests/read-injection-scanner.security.test.cjs'
|
||||
'tests/security-prompt-injection.security.test.cjs'
|
||||
'tests/list-seeds.test.cjs'
|
||||
'tests/fixtures/adversarial/security/'
|
||||
'SECURITY.md'
|
||||
# These files contain intentional injection examples / security-model prose
|
||||
|
||||
38
skills/gsd-add-tests/SKILL.md
Normal file
38
skills/gsd-add-tests/SKILL.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: gsd-add-tests
|
||||
description: "Generate tests for a completed phase based on UAT criteria and implementation"
|
||||
argument-hint: "<phase> [additional instructions]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
|
||||
|
||||
Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
|
||||
|
||||
Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/add-tests.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase: $ARGUMENTS
|
||||
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
|
||||
</process>
|
||||
37
skills/gsd-ai-integration-phase/SKILL.md
Normal file
37
skills/gsd-ai-integration-phase/SKILL.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: gsd-ai-integration-phase
|
||||
description: "Generate an AI-SPEC.md design contract for phases that involve building AI systems."
|
||||
argument-hint: "[phase number]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Agent
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
- AskUserQuestion
|
||||
- mcp__context7__*
|
||||
---
|
||||
|
||||
<objective>
|
||||
Create an AI design contract (AI-SPEC.md) for a phase involving AI system development.
|
||||
Orchestrates gsd-framework-selector → gsd-ai-researcher → gsd-domain-researcher → gsd-eval-planner.
|
||||
Flow: Select Framework → Research Docs → Research Domain → Design Eval Strategy → Done
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/ai-integration-phase.md
|
||||
@~/.claude/gsd-core/references/ai-frameworks.md
|
||||
@~/.claude/gsd-core/references/ai-evals.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates.
|
||||
</process>
|
||||
33
skills/gsd-audit-fix/SKILL.md
Normal file
33
skills/gsd-audit-fix/SKILL.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: gsd-audit-fix
|
||||
description: "Autonomous audit-to-fix pipeline — find issues, classify, fix, test, commit"
|
||||
argument-hint: "--source <audit-uat> [--severity <medium|high|all>] [--max N] [--dry-run]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Run an audit, classify findings as auto-fixable vs manual-only, then autonomously fix
|
||||
auto-fixable issues with test verification and atomic commits.
|
||||
|
||||
Flags:
|
||||
- `--max N` — maximum findings to fix (default: 5)
|
||||
- `--severity high|medium|all` — minimum severity to process (default: medium)
|
||||
- `--dry-run` — classify findings without fixing (shows classification table)
|
||||
- `--source <audit>` — which audit to run (default: audit-uat)
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/audit-fix.md
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
</process>
|
||||
37
skills/gsd-audit-milestone/SKILL.md
Normal file
37
skills/gsd-audit-milestone/SKILL.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: gsd-audit-milestone
|
||||
description: "Audit milestone completion against original intent before archiving"
|
||||
argument-hint: "[version]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Glob
|
||||
- Grep
|
||||
- Bash
|
||||
- Agent
|
||||
- Write
|
||||
---
|
||||
|
||||
<objective>
|
||||
Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
|
||||
|
||||
**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/audit-milestone.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Version: $ARGUMENTS (optional — defaults to current milestone)
|
||||
|
||||
Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
|
||||
|
||||
**Completed Work:**
|
||||
Glob: .planning/phases/*/*-SUMMARY.md
|
||||
Glob: .planning/phases/*/*-VERIFICATION.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
|
||||
</process>
|
||||
25
skills/gsd-audit-uat/SKILL.md
Normal file
25
skills/gsd-audit-uat/SKILL.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: gsd-audit-uat
|
||||
description: "Cross-phase audit of all outstanding UAT and verification items"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Glob
|
||||
- Grep
|
||||
- Bash
|
||||
---
|
||||
|
||||
<objective>
|
||||
Scan all phases for pending, skipped, blocked, and human_needed UAT items. Cross-reference against codebase to detect stale documentation. Produce prioritized human test plan.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/audit-uat.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Core planning files are loaded in-workflow via CLI.
|
||||
|
||||
**Scope:**
|
||||
Glob: .planning/phases/*/*-UAT.md
|
||||
Glob: .planning/phases/*/*-VERIFICATION.md
|
||||
</context>
|
||||
51
skills/gsd-autonomous/SKILL.md
Normal file
51
skills/gsd-autonomous/SKILL.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: gsd-autonomous
|
||||
description: "Run all remaining phases autonomously — discuss→plan→execute per phase"
|
||||
argument-hint: "[--from N] [--to N] [--only N] [--interactive] [--converge]"
|
||||
effort: max
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
- Agent
|
||||
---
|
||||
|
||||
<objective>
|
||||
Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
|
||||
|
||||
Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
|
||||
|
||||
**Creates/Updates:**
|
||||
- `.planning/STATE.md` — updated after each phase
|
||||
- `.planning/ROADMAP.md` — progress updated after each phase
|
||||
- Phase artifacts — CONTEXT.md, PLANs, SUMMARYs per phase
|
||||
|
||||
**After:** Milestone is complete and cleaned up.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/autonomous.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Optional flags:
|
||||
- `--from N` — start from phase N instead of the first incomplete phase.
|
||||
- `--to N` — stop after phase N completes (halt instead of advancing to next phase).
|
||||
- `--only N` — execute only phase N (single-phase mode).
|
||||
- `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
|
||||
- `--converge` — run each phase's planning step through `gsd-plan-review-convergence` instead of plain `gsd-plan-phase`. Requires `workflow.plan_review_convergence=true`.
|
||||
- `--cross-ai` — compatibility alias for `--converge`.
|
||||
|
||||
When `--converge` or `--cross-ai` is set, reviewer selector flags supported by `gsd-plan-review-convergence` may be passed through: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`.
|
||||
|
||||
Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools query init.milestone-op`, `gsd-tools query roadmap.analyze`). No upfront context loading needed.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates (phase discovery, per-phase execution, blocker handling, progress display).
|
||||
</process>
|
||||
67
skills/gsd-capture/SKILL.md
Normal file
67
skills/gsd-capture/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: gsd-capture
|
||||
description: "Capture ideas, tasks, notes, and seeds to their destination"
|
||||
argument-hint: "[--note | --backlog | --seed | --list | --list-seeds] [text]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Capture ideas, tasks, notes, and seeds to their appropriate destination in the GSD system.
|
||||
|
||||
Mode routing:
|
||||
- **default** (no flag): Capture as a structured todo for later work → add-todo workflow
|
||||
- **--note**: Zero-friction idea capture (append/list/promote) → note workflow
|
||||
- **--backlog**: Add an idea to the backlog parking lot (999.x numbering) → add-backlog workflow
|
||||
- **--seed**: Capture a forward-looking idea with trigger conditions → plant-seed workflow
|
||||
- **--list**: List pending todos and select one to work on → check-todos workflow
|
||||
- **--list-seeds**: List/audit captured seeds (optional status filter) → list-seeds workflow
|
||||
</objective>
|
||||
|
||||
<routing>
|
||||
|
||||
| Flag | Destination | Workflow |
|
||||
|------|-------------|----------|
|
||||
| (none) | Structured todo in .planning/todos/ | add-todo |
|
||||
| --note | Timestamped note file, list, or promote | note |
|
||||
| --backlog | ROADMAP.md backlog section (999.x) | add-backlog |
|
||||
| --seed | .planning/seeds/SEED-NNN-slug.md | plant-seed |
|
||||
| --list | Interactive todo browser + action router | check-todos |
|
||||
| --list-seeds | Read-only seed list/audit (optional status filter) | list-seeds |
|
||||
|
||||
</routing>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/add-todo.md
|
||||
@~/.claude/gsd-core/workflows/note.md
|
||||
@~/.claude/gsd-core/workflows/add-backlog.md
|
||||
@~/.claude/gsd-core/workflows/plant-seed.md
|
||||
@~/.claude/gsd-core/workflows/check-todos.md
|
||||
@~/.claude/gsd-core/workflows/list-seeds.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Arguments: $ARGUMENTS
|
||||
|
||||
Parse the first token of $ARGUMENTS:
|
||||
- If it is `--note`: strip the flag, pass remainder to note workflow
|
||||
- If it is `--backlog`: strip the flag, pass remainder to add-backlog workflow
|
||||
- If it is `--seed`: strip the flag, pass remainder to plant-seed workflow
|
||||
- If it is `--list-seeds`: strip the flag, pass remainder (optional status filter) to list-seeds workflow
|
||||
- If it is `--list`: pass remainder (optional area filter) to check-todos workflow
|
||||
- Otherwise: pass all of $ARGUMENTS to add-todo workflow
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Parse the leading flag (if any) from $ARGUMENTS.
|
||||
2. Load and execute the appropriate workflow end-to-end based on the routing table above.
|
||||
3. Preserve all workflow gates from the target workflow (directory structure, duplicate detection, commits, etc.).
|
||||
</process>
|
||||
24
skills/gsd-cleanup/SKILL.md
Normal file
24
skills/gsd-cleanup/SKILL.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
name: gsd-cleanup
|
||||
description: "Archive accumulated phase directories from completed milestones"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
|
||||
|
||||
Use when `.planning/phases/` has accumulated directories from past milestones.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/cleanup.md
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Identify completed milestones, show a dry-run summary, and archive on confirmation.
|
||||
</process>
|
||||
59
skills/gsd-code-review/SKILL.md
Normal file
59
skills/gsd-code-review/SKILL.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: gsd-code-review
|
||||
description: "Review source files changed during a phase for bugs, security issues, and code quality problems"
|
||||
argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Write
|
||||
- Agent
|
||||
---
|
||||
|
||||
<objective>
|
||||
Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems.
|
||||
|
||||
Spawns the gsd-code-reviewer agent to analyze code at the specified depth level. Produces REVIEW.md artifact in the phase directory with severity-classified findings.
|
||||
|
||||
Arguments:
|
||||
- Phase number (required) — which phase's changes to review (e.g., "2" or "02")
|
||||
- `--depth=quick|standard|deep` (optional) — review depth level, overrides workflow.code_review_depth config
|
||||
- quick: Pattern-matching only (~2 min)
|
||||
- standard: Per-file analysis with language-specific checks (~5-15 min, default)
|
||||
- deep: Cross-file analysis including import graphs and call chains (~15-30 min)
|
||||
- `--files file1,file2,...` (optional) — explicit comma-separated file list, skips SUMMARY/git scoping (highest precedence for scoping)
|
||||
- `--fix` (optional) — after review completes (or if REVIEW.md already exists), auto-apply fixes found. Spawns gsd-code-fixer agent. Accepts sub-flags:
|
||||
- `--all` — include Info findings in fix scope (default: Critical + Warning only)
|
||||
- `--auto` — enable fix + re-review iteration loop, capped at 3 iterations
|
||||
|
||||
Output: {padded_phase}-REVIEW.md in phase directory + inline summary of findings
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/code-review.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase: $ARGUMENTS (first positional argument is phase number)
|
||||
|
||||
Optional flags parsed from $ARGUMENTS:
|
||||
- `--depth=VALUE` — Depth override (quick|standard|deep). If provided, overrides workflow.code_review_depth config.
|
||||
- `--files=file1,file2,...` — Explicit file list override. Has highest precedence for file scoping per D-08. When provided, workflow skips SUMMARY.md extraction and git diff fallback entirely.
|
||||
|
||||
Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<files_to_read>` blocks.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
This command is a thin dispatch layer. It parses arguments and delegates to the workflow.
|
||||
|
||||
Execute end-to-end.
|
||||
|
||||
The workflow (not this command) enforces these gates:
|
||||
- Phase validation (before config gate)
|
||||
- Config gate check (workflow.code_review)
|
||||
- File scoping (--files override > SUMMARY.md > git diff fallback)
|
||||
- Empty scope check (skip if no files)
|
||||
- Agent spawning (gsd-code-reviewer)
|
||||
- Result presentation (inline summary + next steps)
|
||||
</process>
|
||||
142
skills/gsd-complete-milestone/SKILL.md
Normal file
142
skills/gsd-complete-milestone/SKILL.md
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
name: gsd-complete-milestone
|
||||
description: "Archive completed milestone and prepare for next version"
|
||||
argument-hint: "<version>"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
|
||||
|
||||
Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
|
||||
Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
**Load these files NOW (before proceeding):**
|
||||
|
||||
- @~/.claude/gsd-core/workflows/complete-milestone.md (main workflow)
|
||||
- @~/.claude/gsd-core/templates/milestone-archive.md (archive template)
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Project files:**
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/REQUIREMENTS.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/PROJECT.md`
|
||||
|
||||
**User input:**
|
||||
|
||||
- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
**Follow complete-milestone.md workflow:**
|
||||
|
||||
0. **Check for audit:**
|
||||
|
||||
- Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
|
||||
- If missing or stale: recommend `/gsd-audit-milestone` first
|
||||
- If audit status is `gaps_found`: recommend closing the gaps inline
|
||||
(the audit output already enumerates them — insert closure phases
|
||||
via `/gsd-phase --insert <N>` plus the standard
|
||||
discuss/plan/execute chain) before proceeding.
|
||||
- If audit status is `passed`: proceed to step 1
|
||||
|
||||
```markdown
|
||||
## Pre-flight Check
|
||||
|
||||
{If no v{{version}}-MILESTONE-AUDIT.md:}
|
||||
⚠ No milestone audit found. Run `/gsd-audit-milestone` first to verify
|
||||
requirements coverage, cross-phase integration, and E2E flows.
|
||||
|
||||
{If audit has gaps:}
|
||||
⚠ Milestone audit found gaps. The audit output already enumerates the
|
||||
unsatisfied requirements, cross-phase issues, and broken flows — insert
|
||||
a closure phase per gap with `/gsd-phase --insert <N>` and run the
|
||||
standard `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase`
|
||||
chain. Or proceed anyway to accept the gaps as tech debt.
|
||||
|
||||
{If audit passed:}
|
||||
✓ Milestone audit passed. Proceeding with completion.
|
||||
```
|
||||
|
||||
1. **Verify readiness:**
|
||||
|
||||
- Check all phases in milestone have completed plans (SUMMARY.md exists)
|
||||
- Present milestone scope and stats
|
||||
- Wait for confirmation
|
||||
|
||||
2. **Gather stats:**
|
||||
|
||||
- Count phases, plans, tasks
|
||||
- Calculate git range, file changes, LOC
|
||||
- Extract timeline from git log
|
||||
- Present summary, confirm
|
||||
|
||||
3. **Extract accomplishments:**
|
||||
|
||||
- Read all phase SUMMARY.md files in milestone range
|
||||
- Extract 4-6 key accomplishments
|
||||
- Present for approval
|
||||
|
||||
4. **Archive milestone:**
|
||||
|
||||
- Create `.planning/milestones/v{{version}}-ROADMAP.md`
|
||||
- Extract full phase details from ROADMAP.md
|
||||
- Fill milestone-archive.md template
|
||||
- Update ROADMAP.md to one-line summary with link
|
||||
|
||||
5. **Archive requirements:**
|
||||
|
||||
- Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
|
||||
- Mark all v1 requirements as complete (checkboxes checked)
|
||||
- Note requirement outcomes (validated, adjusted, dropped)
|
||||
- Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
|
||||
|
||||
6. **Update PROJECT.md:**
|
||||
|
||||
- Add "Current State" section with shipped version
|
||||
- Add "Next Milestone Goals" section
|
||||
- Archive previous content in `<details>` (if v1.1+)
|
||||
|
||||
7. **Commit and tag:**
|
||||
|
||||
- Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
|
||||
- Commit: `chore: archive v{{version}} milestone`
|
||||
- Tag: `git tag -a v{{version}} -m "[milestone summary]"`
|
||||
- Ask about pushing tag
|
||||
|
||||
8. **Offer next steps:**
|
||||
- `/gsd-new-milestone` — start next milestone (questioning → research → requirements → roadmap)
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
|
||||
- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
|
||||
- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
|
||||
- ROADMAP.md collapsed to one-line entry
|
||||
- PROJECT.md updated with current state
|
||||
- Git tag v{{version}} created (if `git.create_tag` enabled)
|
||||
- Commit successful
|
||||
- User knows next steps (including need for fresh requirements)
|
||||
</success_criteria>
|
||||
|
||||
<critical_rules>
|
||||
|
||||
- **Load workflow first:** Read complete-milestone.md before executing
|
||||
- **Verify completion:** All phases must have SUMMARY.md files
|
||||
- **User confirmation:** Wait for approval at verification gates
|
||||
- **Archive before deleting:** Always create archive files before updating/deleting originals
|
||||
- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
|
||||
- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
|
||||
- **Fresh requirements:** Next milestone starts with `/gsd-new-milestone` which includes requirements definition
|
||||
</critical_rules>
|
||||
56
skills/gsd-config/SKILL.md
Normal file
56
skills/gsd-config/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: gsd-config
|
||||
description: "Configure GSD settings — workflow toggles, advanced knobs, integrations, and model profile"
|
||||
argument-hint: "[--advanced | --integrations | --profile <name>]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Configure GSD settings interactively with a single consolidated command.
|
||||
|
||||
Mode routing:
|
||||
- **default** (no flag): Common-case toggles (model, research, plan_check, verifier, branching) → settings workflow
|
||||
- **--advanced**: Power-user knobs (planning tuning, timeouts, branch templates, cross-AI execution) → settings-advanced workflow
|
||||
- **--integrations**: Third-party API keys, code-review CLI routing, agent-skill injection → settings-integrations workflow
|
||||
- **--profile <name>**: Switch model profile (quality|balanced|budget|inherit) → set-profile (inline)
|
||||
</objective>
|
||||
|
||||
<routing>
|
||||
|
||||
| Flag | Action | Workflow |
|
||||
|------|--------|----------|
|
||||
| (none) | Interactive 5-question common-case config prompt | settings |
|
||||
| --advanced | Power-user knobs: planning, execution, discussion, cross-AI, git, runtime | settings-advanced |
|
||||
| --integrations | API keys (Brave/Firecrawl/Exa), review CLI routing, agent skills | settings-integrations |
|
||||
| --profile <name> | Switch model profile without interactive prompt | gsd-tools query config-set-model-profile |
|
||||
|
||||
</routing>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/settings.md
|
||||
@~/.claude/gsd-core/workflows/settings-advanced.md
|
||||
@~/.claude/gsd-core/workflows/settings-integrations.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Arguments: $ARGUMENTS
|
||||
|
||||
Parse the first token of $ARGUMENTS:
|
||||
- If it is `--advanced`: strip the flag, execute settings-advanced workflow
|
||||
- If it is `--integrations`: strip the flag, execute settings-integrations workflow
|
||||
- If it starts with `--profile`: extract the profile name (remainder after `--profile`), then:
|
||||
1. Verify `gsd-tools` is on PATH via `command -v gsd-tools`; if absent, emit the install hint `Install GSD via 'npm i -g @opengsd/gsd-core'` and stop.
|
||||
2. Run: `gsd-tools query config-set-model-profile <profile-name> --raw` and display the output verbatim.
|
||||
- Otherwise: execute settings workflow (no argument needed)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Parse the leading flag (if any) from $ARGUMENTS.
|
||||
2. Load and execute the appropriate workflow end-to-end, or run the inline SDK command for --profile.
|
||||
3. Preserve all workflow gates from the target workflow.
|
||||
</process>
|
||||
53
skills/gsd-debug/SKILL.md
Normal file
53
skills/gsd-debug/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: gsd-debug
|
||||
description: "Systematic debugging with persistent state across context resets"
|
||||
argument-hint: "[list | status <slug> | continue <slug> | --diagnose] [issue description]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Debug issues using scientific method with subagent isolation.
|
||||
|
||||
**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
|
||||
|
||||
**Flags:**
|
||||
- `--diagnose` — Diagnose only. Returns a Root Cause Report without applying a fix.
|
||||
|
||||
**Subcommands:** `list` · `status <slug>` · `continue <slug>`
|
||||
</objective>
|
||||
|
||||
<available_agent_types>
|
||||
Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
|
||||
- gsd-debug-session-manager — manages debug checkpoint/continuation loop in isolated context
|
||||
- gsd-debugger — investigates bugs using scientific method
|
||||
</available_agent_types>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/debug.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
User's input: $ARGUMENTS
|
||||
|
||||
Parse subcommands and flags from $ARGUMENTS BEFORE the active-session check:
|
||||
- If $ARGUMENTS starts with "list": SUBCMD=list, no further args
|
||||
- If $ARGUMENTS starts with "status ": SUBCMD=status, SLUG=remainder (trim whitespace)
|
||||
- If $ARGUMENTS starts with "continue ": SUBCMD=continue, SLUG=remainder (trim whitespace)
|
||||
- If $ARGUMENTS contains `--diagnose`: SUBCMD=debug, diagnose_only=true, strip `--diagnose` from description
|
||||
- Otherwise: SUBCMD=debug, diagnose_only=false
|
||||
|
||||
Check for active sessions (used for non-list/status/continue flows):
|
||||
```bash
|
||||
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
|
||||
```
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
</process>
|
||||
77
skills/gsd-discuss-phase/SKILL.md
Normal file
77
skills/gsd-discuss-phase/SKILL.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: gsd-discuss-phase
|
||||
description: "Gather phase context through adaptive questioning before planning."
|
||||
argument-hint: "<phase> [--all] [--auto] [--chain] [--batch] [--analyze] [--text] [--power] [--assumptions]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
- Agent
|
||||
- mcp__context7__resolve-library-id
|
||||
- mcp__context7__query-docs
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
|
||||
|
||||
**How it works:**
|
||||
1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
|
||||
2. Scout codebase for reusable assets and patterns
|
||||
3. Analyze phase — skip gray areas already decided in prior phases
|
||||
4. Present remaining gray areas — user selects which to discuss
|
||||
5. Deep-dive each selected area until satisfied
|
||||
6. Create CONTEXT.md with decisions that guide research and planning
|
||||
|
||||
**Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
Workflow files are loaded on-demand in the <process> section below — not upfront.
|
||||
Do not pre-load any workflow files before reading the mode routing instructions.
|
||||
</execution_context>
|
||||
|
||||
<runtime_note>
|
||||
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
|
||||
</runtime_note>
|
||||
|
||||
<context>
|
||||
Phase number: $ARGUMENTS (required)
|
||||
|
||||
Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
**Mode routing:**
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
DISCUSS_MODE=$(gsd_run query config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
|
||||
```
|
||||
|
||||
If `--assumptions` is in $ARGUMENTS:
|
||||
Read and execute `~/.claude/gsd-core/workflows/list-phase-assumptions.md` end-to-end.
|
||||
Stop here.
|
||||
|
||||
Otherwise, if `DISCUSS_MODE` is `"assumptions"`:
|
||||
Read and execute `~/.claude/gsd-core/workflows/discuss-phase-assumptions.md` end-to-end.
|
||||
|
||||
Otherwise (`"discuss"` / unset / any other value):
|
||||
Read and execute `~/.claude/gsd-core/workflows/discuss-phase.md` end-to-end.
|
||||
|
||||
**MANDATORY:** Read the appropriate workflow file BEFORE taking any action. The objective and success_criteria sections in this command file are summaries — the workflow file contains the complete step-by-step process with all required behaviors, config checks, and interaction patterns. Do not improvise from the summary.
|
||||
|
||||
**Lazy loading:** `templates/context.md` is loaded inside the `write_context` step of the active workflow. `discuss-phase-power.md` is loaded inside `discuss-phase.md` when `--power` is detected. Do not load either here.
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Prior context loaded and applied (no re-asking decided questions)
|
||||
- Gray areas identified through intelligent analysis
|
||||
- User chose which areas to discuss
|
||||
- Each selected area explored until satisfied
|
||||
- Scope creep redirected to deferred ideas
|
||||
- CONTEXT.md captures decisions, not vague vision
|
||||
- User knows next steps
|
||||
</success_criteria>
|
||||
49
skills/gsd-docs-update/SKILL.md
Normal file
49
skills/gsd-docs-update/SKILL.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: gsd-docs-update
|
||||
description: "Generate or update project documentation verified against the codebase"
|
||||
argument-hint: "[--force] [--verify-only]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Generate and update up to 9 documentation files for the current project. Each doc type is written by a gsd-doc-writer subagent that explores the codebase directly — no hallucinated paths, phantom endpoints, or stale signatures.
|
||||
|
||||
Flag handling rule:
|
||||
- The optional flags documented below are available behaviors, not implied active behaviors
|
||||
- A flag is active only when its literal token appears in `$ARGUMENTS`
|
||||
- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
|
||||
- `--force`: skip preservation prompts, regenerate all docs regardless of existing content or GSD markers
|
||||
- `--verify-only`: check existing docs for accuracy against codebase, no generation (full verification requires Phase 4 verifier)
|
||||
- If `--force` and `--verify-only` both appear in `$ARGUMENTS`, `--force` takes precedence
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/docs-update.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Arguments: $ARGUMENTS
|
||||
|
||||
**Available optional flags (documentation only — not automatically active):**
|
||||
- `--force` — Regenerate all docs. Overwrites hand-written and GSD docs alike. No preservation prompts.
|
||||
- `--verify-only` — Check existing docs for accuracy against the codebase. No files are written. Reports VERIFY marker count. Full codebase fact-checking requires the gsd-doc-verifier agent (Phase 4).
|
||||
|
||||
**Active flags must be derived from `$ARGUMENTS`:**
|
||||
- `--force` is active only if the literal `--force` token is present in `$ARGUMENTS`
|
||||
- `--verify-only` is active only if the literal `--verify-only` token is present in `$ARGUMENTS`
|
||||
- If neither token appears, run the standard full-phase generation flow
|
||||
- Do not infer that a flag is active just because it is documented in this prompt
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates (preservation_check, flag handling, wave execution, monorepo dispatch, commit, reporting).
|
||||
</process>
|
||||
33
skills/gsd-eval-review/SKILL.md
Normal file
33
skills/gsd-eval-review/SKILL.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: gsd-eval-review
|
||||
description: "Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan."
|
||||
argument-hint: "[phase number]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Conduct a retroactive evaluation coverage audit of a completed AI phase.
|
||||
Checks whether the evaluation strategy from AI-SPEC.md was implemented.
|
||||
Produces EVAL-REVIEW.md with score, verdict, gaps, and remediation plan.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/eval-review.md
|
||||
@~/.claude/gsd-core/references/ai-evals.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Phase: $ARGUMENTS — optional, defaults to last completed phase.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates.
|
||||
</process>
|
||||
65
skills/gsd-execute-phase/SKILL.md
Normal file
65
skills/gsd-execute-phase/SKILL.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: gsd-execute-phase
|
||||
description: "Execute all plans in a phase with wave-based parallelization"
|
||||
argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
|
||||
effort: max
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Glob
|
||||
- Grep
|
||||
- Bash
|
||||
- Agent
|
||||
- TodoWrite
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Execute all plans in a phase using wave-based parallel execution.
|
||||
|
||||
Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
|
||||
|
||||
Optional wave filter:
|
||||
- `--wave N` executes only Wave `N` for pacing, quota management, or staged rollout
|
||||
- phase verification/completion still only happens when no incomplete plans remain after the selected wave finishes
|
||||
|
||||
Flag handling rule:
|
||||
- The optional flags documented below are available behaviors, not implied active behaviors
|
||||
- A flag is active only when its literal token appears in `$ARGUMENTS`
|
||||
- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
|
||||
|
||||
Context budget: ~15% orchestrator, 100% fresh per subagent.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/execute-phase.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<runtime_note>
|
||||
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
|
||||
</runtime_note>
|
||||
|
||||
<context>
|
||||
Phase: $ARGUMENTS
|
||||
|
||||
**Available optional flags (documentation only — not automatically active):**
|
||||
- `--wave N` — Execute only Wave `N` in the phase. Use when you want to pace execution or stay inside usage limits.
|
||||
- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
|
||||
- `--interactive` — Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gaps.
|
||||
|
||||
**Active flags must be derived from `$ARGUMENTS`:**
|
||||
- `--wave N` is active only if the literal `--wave` token is present in `$ARGUMENTS`
|
||||
- `--gaps-only` is active only if the literal `--gaps-only` token is present in `$ARGUMENTS`
|
||||
- `--interactive` is active only if the literal `--interactive` token is present in `$ARGUMENTS`
|
||||
- If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering
|
||||
- Do not infer that a flag is active just because it is documented in this prompt
|
||||
|
||||
Context files are resolved inside the workflow via `gsd-tools query init.execute-phase` and per-subagent `<files_to_read>` blocks.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
|
||||
</process>
|
||||
28
skills/gsd-explore/SKILL.md
Normal file
28
skills/gsd-explore/SKILL.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: gsd-explore
|
||||
description: "Socratic ideation and idea routing — think through ideas before committing to plans"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Open-ended Socratic ideation session. Guides the developer through exploring an idea via
|
||||
probing questions, optionally spawns research, then routes outputs to the appropriate GSD
|
||||
artifacts (notes, todos, seeds, research questions, requirements, or new phases).
|
||||
|
||||
Accepts an optional topic argument: `/gsd-explore authentication strategy`
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/explore.md
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
</process>
|
||||
22
skills/gsd-extract-learnings/SKILL.md
Normal file
22
skills/gsd-extract-learnings/SKILL.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: gsd-extract-learnings
|
||||
description: "Extract decisions, lessons, patterns, and surprises from completed phase artifacts"
|
||||
argument-hint: "<phase-number>"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
- Agent
|
||||
---
|
||||
|
||||
<objective>
|
||||
Extract structured learnings from completed phase artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md, UAT.md, STATE.md) into a LEARNINGS.md file that captures decisions, lessons learned, patterns discovered, and surprises encountered.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/extract-learnings.md
|
||||
</execution_context>
|
||||
|
||||
Execute the extract-learnings workflow from @~/.claude/gsd-core/workflows/extract-learnings.md end-to-end.
|
||||
31
skills/gsd-fast/SKILL.md
Normal file
31
skills/gsd-fast/SKILL.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: gsd-fast
|
||||
description: "Execute a trivial task inline — no subagents, no planning overhead"
|
||||
argument-hint: "[task description]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Execute a trivial task directly in the current context without spawning subagents
|
||||
or generating PLAN.md files. For tasks too small to justify planning overhead:
|
||||
typo fixes, config changes, small refactors, forgotten commits, simple additions.
|
||||
|
||||
This is NOT a replacement for /gsd-quick — use /gsd-quick for anything that
|
||||
needs research, multi-step planning, or verification. /gsd-fast is for tasks
|
||||
you could describe in one sentence and execute in under 2 minutes.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/fast.md
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
</process>
|
||||
56
skills/gsd-forensics/SKILL.md
Normal file
56
skills/gsd-forensics/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: gsd-forensics
|
||||
description: "Post-mortem investigation for failed GSD workflows — diagnoses what went wrong."
|
||||
argument-hint: "[problem description]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Investigate what went wrong during a GSD workflow execution. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies and generate a structured diagnostic report.
|
||||
|
||||
Purpose: Diagnose failed or stuck workflows so the user can understand root cause and take corrective action.
|
||||
Output: Forensic report saved to `.planning/forensics/`, presented inline, with optional issue creation.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/forensics.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Data sources:**
|
||||
- `git log` (recent commits, patterns, time gaps)
|
||||
- `git status` / `git diff` (uncommitted work, conflicts)
|
||||
- `.planning/STATE.md` (current position, session history)
|
||||
- `.planning/ROADMAP.md` (phase scope and progress)
|
||||
- `.planning/phases/*/` (PLAN.md, SUMMARY.md, VERIFICATION.md, CONTEXT.md)
|
||||
- `.planning/reports/SESSION_REPORT.md` (last session outcomes)
|
||||
|
||||
**User input:**
|
||||
- Problem description: $ARGUMENTS (optional — will ask if not provided)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Evidence gathered from all available data sources
|
||||
- At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption)
|
||||
- Structured forensic report written to `.planning/forensics/report-{timestamp}.md`
|
||||
- Report presented inline with findings, anomalies, and recommendations
|
||||
- Interactive investigation offered for deeper analysis
|
||||
- GitHub issue creation offered if actionable findings exist
|
||||
</success_criteria>
|
||||
|
||||
<critical_rules>
|
||||
- **Read-only investigation:** Do not modify project source files during forensics. Only write the forensic report and update STATE.md session tracking.
|
||||
- **Redact sensitive data:** Strip absolute paths, API keys, tokens from reports and issues.
|
||||
- **Ground findings in evidence:** Every anomaly must cite specific commits, files, or state data.
|
||||
- **No speculation without evidence:** If data is insufficient, say so — do not fabricate root causes.
|
||||
</critical_rules>
|
||||
204
skills/gsd-graphify/SKILL.md
Normal file
204
skills/gsd-graphify/SKILL.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
name: gsd-graphify
|
||||
description: "Build, query, and inspect the project knowledge graph in .planning/graphs/"
|
||||
argument-hint: "[build|query <term>|status|diff]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
---
|
||||
|
||||
|
||||
**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
|
||||
|
||||
**CJS-only (graphify):** `graphify` subcommands are not registered on `gsd-tools query`. Use the `gsd_run` launcher shim (defined in each bash block below) or invoke the binary directly: `node <runtime-home>/gsd-core/bin/gsd-tools.cjs graphify …` where `<runtime-home>` is your runtime's config directory (e.g. `~/.claude`, `~/.hermes`, `~/.cursor`). See `docs/CLI-TOOLS.md` for details. Other tooling may still use `gsd-tools query` where a handler exists.
|
||||
|
||||
## Step 0 -- Banner
|
||||
|
||||
**Before ANY tool calls**, display this banner:
|
||||
|
||||
```
|
||||
GSD > GRAPHIFY
|
||||
```
|
||||
|
||||
Then proceed to Step 1.
|
||||
|
||||
## Step 1 -- Config Gate
|
||||
|
||||
Check if graphify is enabled by reading `.planning/config.json` directly using the Read tool.
|
||||
|
||||
**DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
|
||||
|
||||
1. Read `.planning/config.json` using the Read tool
|
||||
2. If the file does not exist: display the disabled message below and **STOP**
|
||||
3. Parse the JSON content. Check if `config.graphify && config.graphify.enabled === true`
|
||||
4. If `graphify.enabled` is NOT explicitly `true`: display the disabled message below and **STOP**
|
||||
5. If `graphify.enabled` is `true`: proceed to Step 2
|
||||
|
||||
**Disabled message:**
|
||||
|
||||
```
|
||||
GSD > GRAPHIFY
|
||||
|
||||
Knowledge graph is disabled. To activate:
|
||||
|
||||
node <runtime-home>/gsd-core/bin/gsd-tools.cjs config-set graphify.enabled true
|
||||
|
||||
Then run /gsd-graphify build to create the initial graph.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2 -- Parse Argument
|
||||
|
||||
Parse `$ARGUMENTS` to determine the operation mode:
|
||||
|
||||
| Argument | Action |
|
||||
|----------|--------|
|
||||
| `build` | Run inline build (Step 3) |
|
||||
| `query <term>` | Run inline query (Step 2a) |
|
||||
| `status` | Run inline status check (Step 2b) |
|
||||
| `diff` | Run inline diff check (Step 2c) |
|
||||
| No argument or unknown | Show usage message |
|
||||
|
||||
**Usage message** (shown when no argument or unrecognized argument):
|
||||
|
||||
```
|
||||
GSD > GRAPHIFY
|
||||
|
||||
Usage: /gsd-graphify <mode>
|
||||
|
||||
Modes:
|
||||
build Build or rebuild the knowledge graph
|
||||
query <term> Search the graph for a term
|
||||
status Show graph freshness and statistics
|
||||
diff Show changes since last build
|
||||
```
|
||||
|
||||
### Step 2a -- Query
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
gsd_run graphify query <term>
|
||||
```
|
||||
|
||||
Parse the JSON output and display results:
|
||||
- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
|
||||
- If the output contains `"error"` field, display the error message and **STOP**
|
||||
- If no nodes found, display: `No graph matches for '<term>'. Try /gsd-graphify build to create or rebuild the graph.`
|
||||
- Otherwise, display matched nodes grouped by type, with edge relationships and confidence tiers (EXTRACTED/INFERRED/AMBIGUOUS)
|
||||
|
||||
**STOP** after displaying results. Do not spawn an agent.
|
||||
|
||||
### Step 2b -- Status
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
gsd_run graphify status
|
||||
```
|
||||
|
||||
Parse the JSON output and display:
|
||||
- If `exists: false`, display the message field
|
||||
- Otherwise show last build time, node/edge/hyperedge counts, and STALE or FRESH indicator
|
||||
- If `built_at_commit` is non-null, also display a `Source commit:` line:
|
||||
- `commit_stale === false` (rebuilt at HEAD): `Source commit: <built_at_commit> (current)`
|
||||
- `commit_stale === true` (graph behind HEAD): `Source commit: <built_at_commit> (<commits_behind> commits behind HEAD)`
|
||||
- `commit_stale === null` (unreachable commit / no git): `Source commit: <built_at_commit> (freshness unknown)`
|
||||
- If `built_at_commit` is null (pre-graphify-v0.7 graph), omit the source-commit line entirely — do not render "Source commit: unknown"
|
||||
|
||||
The mtime-based STALE/FRESH flag and the commit-based `commit_stale` measure
|
||||
different things and can disagree (e.g., a CI-built graph rebuilt minutes ago
|
||||
against an old checkout reads as FRESH on mtime but `commit_stale: true`).
|
||||
Surface both so the agent can choose.
|
||||
|
||||
**STOP** after displaying status. Do not spawn an agent.
|
||||
|
||||
### Step 2c -- Diff
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
gsd_run graphify diff
|
||||
```
|
||||
|
||||
Parse the JSON output and display:
|
||||
- If `no_baseline: true`, display the message field
|
||||
- Otherwise show node and edge change counts (added/removed/changed)
|
||||
|
||||
If no snapshot exists, suggest running `build` twice (first to create, second to generate a diff baseline).
|
||||
|
||||
**STOP** after displaying diff. Do not spawn an agent.
|
||||
|
||||
---
|
||||
|
||||
## Step 3 -- Build (Inline)
|
||||
|
||||
Run the pre-flight check first:
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
gsd_run graphify build
|
||||
```
|
||||
|
||||
Parse the JSON output:
|
||||
- If `disabled: true`: display the disabled message from Step 1 and **STOP**
|
||||
- If `error`: display the error message and **STOP**
|
||||
- If `action: "spawn_agent"`: pre-flight passed -- proceed with the inline build below
|
||||
|
||||
(The `spawn_agent` action name is historical. The skill now performs the build inline because graphify v0.7+ split the build into a fast AST-extraction phase and a separate clustering + report-write phase. Sub-agent isolation kept the cached extraction phase alive but SIGTERM'd the post-extraction phase when the agent exited, leaving the cache populated but no `graph.json` artifacts written. The CLI still emits the `spawn_agent` signal so external callers and tests keep working.)
|
||||
|
||||
Display:
|
||||
|
||||
```text
|
||||
GSD > Building knowledge graph...
|
||||
```
|
||||
|
||||
Run the build, copy artifacts, write the diff snapshot, and report the summary in a single foreground Bash call so the whole pipeline survives to completion. Use a `timeout` of `600000` ms (10 minutes), which covers the `graphify.build_timeout` ceiling (default 300 s) with margin:
|
||||
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
graphify update . \
|
||||
&& cp graphify-out/graph.json .planning/graphs/graph.json \
|
||||
&& { [ -f graphify-out/graph.html ] && cp graphify-out/graph.html .planning/graphs/graph.html || true; } \
|
||||
&& cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md \
|
||||
&& gsd_run graphify build snapshot \
|
||||
&& gsd_run graphify status
|
||||
```
|
||||
|
||||
Do NOT pass `run_in_background: true`. Typical builds complete in 15-60 seconds and the entire chain must run foreground.
|
||||
|
||||
If the chain fails (non-zero exit):
|
||||
- Display: `## GRAPHIFY BUILD FAILED` followed by the captured stderr
|
||||
- Do NOT delete `.planning/graphs/` -- the prior valid graph remains available
|
||||
- **STOP**
|
||||
|
||||
If the chain succeeds:
|
||||
- Parse the trailing `graphify status` JSON
|
||||
- Display: `## GRAPHIFY BUILD COMPLETE` with the node, edge, and hyperedge counts
|
||||
|
||||
---
|
||||
|
||||
## MVP-Mode Node Rendering
|
||||
|
||||
**MVP-mode rendering.** When a phase has `**Mode:** mvp` in ROADMAP.md (resolved via `gsd-tools query roadmap.get-phase --pick mode`), render its graph node with two distinct visual signals:
|
||||
|
||||
1. **Distinct fill color.** Use `#22c55e` (green) for MVP-mode phase nodes. Standard phases keep the default fill color. Two-channel signaling (color + label) handles color-blind and grayscale renders.
|
||||
2. **`MVP` label suffix.** Append ` (MVP)` to the node's label text. Example: a phase originally labeled `Phase 1: User Auth` renders as `Phase 1: User Auth (MVP)`.
|
||||
|
||||
Both signals fire together — never just one. Per PRD Q5 decision, the goal is unambiguous visual distinction in any render context.
|
||||
|
||||
When the phase mode is null/absent, render with the standard color and label — no behavioral change for non-MVP phases.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
1. DO NOT spawn an agent for any operation -- build, query, status, and diff all run inline. Sub-agent isolation terminates background bash when the agent exits, which previously truncated graphify builds mid-write and left only the cache populated (#3166).
|
||||
2. DO NOT pass `run_in_background: true` for the build chain -- the operation is fast and must complete in the foreground.
|
||||
3. DO NOT modify graph files directly -- always go through `graphify update .` and the snapshot CLI.
|
||||
4. DO NOT skip the config gate check.
|
||||
5. DO NOT use `gsd-tools config get-value` for the config gate -- it exits on missing keys.
|
||||
31
skills/gsd-health/SKILL.md
Normal file
31
skills/gsd-health/SKILL.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: gsd-health
|
||||
description: "Diagnose planning directory health and optionally repair issues"
|
||||
argument-hint: "[--repair] [--context]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Write
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
|
||||
|
||||
`--context` runs an orthogonal check: the running session's context utilization. The workflow asks for the model's tokensUsed + contextWindow, calls `gsd-tools query validate.context`, and renders one of three states:
|
||||
|
||||
| Utilization | State | Action |
|
||||
|-------------|----------|-------------------------------------------------------|
|
||||
| < 60% | healthy | no action — context is comfortable |
|
||||
| 60% – 70% | warning | recommend `/gsd-thread` to start fresh |
|
||||
| ≥ 70% | critical | reasoning quality may degrade past the fracture point |
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/health.md
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Parse `--repair` and `--context` flags from arguments and pass to workflow.
|
||||
</process>
|
||||
29
skills/gsd-help/SKILL.md
Normal file
29
skills/gsd-help/SKILL.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: gsd-help
|
||||
description: "Show available GSD commands and usage guide"
|
||||
argument-hint: "[--brief | --full | <topic> | --brief <topic>]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
---
|
||||
|
||||
<objective>
|
||||
Display GSD help at the tier the user asked for: brief (one-line refresher), default (one-page tour), full (complete reference), a single topic section, or a compact scoped lookup of one topic (`--brief <topic>`: signature + one-line summary).
|
||||
|
||||
Output ONLY the reference content of the chosen tier. Do NOT add:
|
||||
- Project-specific analysis
|
||||
- Git status or file context
|
||||
- Next-step suggestions
|
||||
- Any commentary beyond the reference
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/help.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Arguments: $ARGUMENTS
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Follow ~/.claude/gsd-core/workflows/help.md with $ARGUMENTS.
|
||||
</process>
|
||||
46
skills/gsd-import/SKILL.md
Normal file
46
skills/gsd-import/SKILL.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
name: gsd-import
|
||||
description: "Ingest external plans with conflict detection against project decisions before writing anything."
|
||||
argument-hint: "--from <filepath> | --from-gsd2"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
- Agent
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Import external plan files into the GSD planning system with conflict detection against PROJECT.md decisions.
|
||||
|
||||
- **--from**: Import an external plan file, detect conflicts, write as GSD PLAN.md, validate via gsd-plan-checker.
|
||||
- **--from-gsd2**: Reverse-migrate a GSD-2 project (`.gsd/` directory) back to GSD v1 (`.planning/`) format. Runs `gsd-tools.cjs from-gsd2`. Pass `--path <dir>` to migrate a project at a different path.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/import.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
@~/.claude/gsd-core/references/gate-prompts.md
|
||||
@~/.claude/gsd-core/references/doc-conflict-engine.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
$ARGUMENTS
|
||||
</context>
|
||||
|
||||
<process>
|
||||
If `--from-gsd2` is in $ARGUMENTS:
|
||||
Run the reverse-migration (append `--path <dir>` if provided):
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
|
||||
gsd_run from-gsd2
|
||||
```
|
||||
Present the migration result to the user.
|
||||
Stop here (do not run the standard import workflow).
|
||||
|
||||
Otherwise, execute the import workflow end-to-end.
|
||||
</process>
|
||||
39
skills/gsd-inbox/SKILL.md
Normal file
39
skills/gsd-inbox/SKILL.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: gsd-inbox
|
||||
description: "Triage and review open GitHub issues and PRs against project templates and contribution guidelines."
|
||||
argument-hint: "[--issues] [--prs] [--label] [--close-incomplete] [--repo owner/repo]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Write
|
||||
- Grep
|
||||
- Glob
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<objective>
|
||||
One-command triage of the project's GitHub inbox. Fetches all open issues and PRs,
|
||||
reviews each against the corresponding template requirements (feature, enhancement,
|
||||
bug, chore, fix PR, enhancement PR, feature PR), reports completeness and compliance,
|
||||
and optionally applies labels or closes non-compliant submissions.
|
||||
|
||||
**Flow:** Detect repo → Fetch open issues + PRs → Classify each by type → Review against template → Report findings → Optionally act (label, comment, close)
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/inbox.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Flags:**
|
||||
- `--issues` — Review only issues (skip PRs)
|
||||
- `--prs` — Review only PRs (skip issues)
|
||||
- `--label` — Auto-apply recommended labels after review
|
||||
- `--close-incomplete` — Close issues/PRs that fail template compliance (with comment explaining why)
|
||||
- `--repo owner/repo` — Override auto-detected repository (defaults to current git remote)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Parse flags from arguments and pass to workflow.
|
||||
</process>
|
||||
43
skills/gsd-ingest-docs/SKILL.md
Normal file
43
skills/gsd-ingest-docs/SKILL.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: gsd-ingest-docs
|
||||
description: "Bootstrap or merge a .planning/ setup from existing ADRs, PRDs, SPECs, and docs in a repo."
|
||||
argument-hint: "[path] [--mode new|merge] [--manifest <file>] [--resolve auto|interactive]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
- Agent
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Build the full `.planning/` setup (or merge into an existing one) from multiple pre-existing planning documents — ADRs, PRDs, SPECs, DOCs — in one pass.
|
||||
|
||||
- **Net-new bootstrap** (`--mode new`, default when `.planning/` is absent): produces PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md from synthesized doc content, delegating final generation to `gsd-roadmapper`.
|
||||
- **Merge into existing** (`--mode merge`, default when `.planning/` is present): appends phases and requirements derived from the ingested docs; hard-blocks any contradiction with existing locked decisions.
|
||||
|
||||
Auto-synthesizes most conflicts using the precedence rule `ADR > SPEC > PRD > DOC` (overridable via manifest). Surfaces unresolved cases in `.planning/INGEST-CONFLICTS.md` with three buckets: auto-resolved, competing-variants, unresolved-blockers. The BLOCKER gate from the shared conflict engine prevents any destination file from being written when unresolved contradictions exist.
|
||||
|
||||
**Inputs:** directory-convention discovery (`docs/adr/`, `docs/prd/`, `docs/specs/`, `docs/rfc/`, root-level `{ADR,PRD,SPEC,RFC}-*.md`), or an explicit `--manifest <file>` YAML listing `{path, type, precedence?}` per doc.
|
||||
|
||||
**v1 constraints:** hard cap of 50 docs per invocation; `--resolve interactive` is reserved for a future release.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/ingest-docs.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
@~/.claude/gsd-core/references/gate-prompts.md
|
||||
@~/.claude/gsd-core/references/doc-conflict-engine.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
$ARGUMENTS
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute the ingest-docs workflow end-to-end. Preserve all approval gates (discovery, conflict report, routing) and the BLOCKER safety rule.
|
||||
</process>
|
||||
45
skills/gsd-manager/SKILL.md
Normal file
45
skills/gsd-manager/SKILL.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: gsd-manager
|
||||
description: "Interactive command center for managing multiple phases from one terminal"
|
||||
argument-hint: "[--analyze-deps]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- AskUserQuestion
|
||||
- Skill
|
||||
- Agent
|
||||
---
|
||||
|
||||
<objective>
|
||||
Single-terminal command center for managing a milestone. Shows a dashboard of all phases with visual status indicators, recommends optimal next actions, and dispatches work — discuss runs inline, plan/execute run as background agents.
|
||||
|
||||
Designed for power users who want to parallelize work across phases from one terminal: discuss a phase while another plans or executes in the background.
|
||||
|
||||
**Creates/Updates:**
|
||||
- No files created directly — dispatches to existing GSD commands via Skill() and background Task agents.
|
||||
- Reads `.planning/STATE.md`, `.planning/ROADMAP.md`, phase directories for status.
|
||||
|
||||
**After:** User exits when done managing, or all phases complete and milestone lifecycle is suggested.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/manager.md
|
||||
@~/.claude/gsd-core/references/ui-brand.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
No arguments required. Requires an active milestone with ROADMAP.md and STATE.md.
|
||||
|
||||
Project context, phase list, dependencies, and recommendations are resolved inside the workflow using `gsd-tools query init.manager`. No upfront context loading needed.
|
||||
</context>
|
||||
|
||||
<process>
|
||||
If `--analyze-deps` is in $ARGUMENTS:
|
||||
Read and execute `~/.claude/gsd-core/workflows/analyze-dependencies.md` end-to-end.
|
||||
|
||||
Execute end-to-end.
|
||||
Maintain the dashboard refresh loop until the user exits or all phases complete.
|
||||
</process>
|
||||
83
skills/gsd-map-codebase/SKILL.md
Normal file
83
skills/gsd-map-codebase/SKILL.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
name: gsd-map-codebase
|
||||
description: "Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents"
|
||||
argument-hint: "[--fast [--focus tech|arch|quality|concerns]] [--query <term>|status|diff|refresh] [area]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Write
|
||||
- Agent
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Analyze existing codebase using parallel gsd-codebase-mapper agents to produce structured codebase documents.
|
||||
|
||||
Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
|
||||
|
||||
Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/map-codebase.md
|
||||
</execution_context>
|
||||
|
||||
<flags>
|
||||
- **--fast**: Lightweight scan mode — spawns one mapper agent instead of four. Accepts an optional `--focus` value: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default). Faster and lower-context than the full map.
|
||||
- **--query**: Codebase intelligence query mode. Sub-commands: `query <term>`, `status`, `diff`, `refresh`. Requires intel to be enabled in config (`intel.enabled: true`). Runs inline for query/status/diff; spawns an agent for refresh.
|
||||
- **(no flag)**: Full parallel map — spawns 4 mapper agents to produce all 7 codebase documents.
|
||||
</flags>
|
||||
|
||||
<context>
|
||||
Arguments: $ARGUMENTS
|
||||
|
||||
Parse the first token of $ARGUMENTS:
|
||||
- If it is `--fast`: strip the flag, run the scan workflow (passing remaining args including optional --focus).
|
||||
- If it is `--query`: strip the flag, run the intel workflow (passing remaining args as the subcommand).
|
||||
- Otherwise: pass all of $ARGUMENTS as focus area to the map-codebase workflow.
|
||||
|
||||
**Load project state if exists:**
|
||||
Check for .planning/STATE.md - loads context if project already initialized
|
||||
|
||||
**This command can run:**
|
||||
- Before /gsd-new-project (brownfield codebases) - creates codebase map first
|
||||
- After /gsd-new-project (greenfield codebases) - updates codebase map as code evolves
|
||||
- Anytime to refresh codebase understanding
|
||||
</context>
|
||||
|
||||
<when_to_use>
|
||||
**Use map-codebase for:**
|
||||
- Brownfield projects before initialization (understand existing code first)
|
||||
- Refreshing codebase map after significant changes
|
||||
- Onboarding to an unfamiliar codebase
|
||||
- Before major refactoring (understand current state)
|
||||
- When STATE.md references outdated codebase info
|
||||
|
||||
**Skip map-codebase for:**
|
||||
- Greenfield projects with no code yet (nothing to map)
|
||||
- Trivial codebases (<5 files)
|
||||
</when_to_use>
|
||||
|
||||
<process>
|
||||
1. Check if .planning/codebase/ already exists (offer to refresh or skip)
|
||||
2. Create .planning/codebase/ directory structure
|
||||
3. Spawn 4 parallel gsd-codebase-mapper agents:
|
||||
- Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
|
||||
- Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
|
||||
- Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
|
||||
- Agent 4: concerns focus → writes CONCERNS.md
|
||||
4. Wait for agents to complete, collect confirmations (NOT document contents)
|
||||
5. Verify all 7 documents exist with line counts
|
||||
6. Commit codebase map
|
||||
7. Offer next steps (typically: /gsd-new-project or /gsd-plan-phase)
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] .planning/codebase/ directory created
|
||||
- [ ] All 7 codebase documents written by mapper agents
|
||||
- [ ] Documents follow template structure
|
||||
- [ ] Parallel agents completed without errors
|
||||
- [ ] User knows next steps
|
||||
</success_criteria>
|
||||
71
skills/gsd-mempalace-capture/SKILL.md
Normal file
71
skills/gsd-mempalace-capture/SKILL.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: gsd-mempalace-capture
|
||||
description: "File a phase artifact into MemPalace; mirror decision facts into its temporal KG"
|
||||
argument-hint: "[CONTEXT.md|PLAN.md|SUMMARY.md]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
---
|
||||
|
||||
|
||||
**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
|
||||
|
||||
## Step 0 -- Banner
|
||||
|
||||
**Before ANY tool calls**, display this banner:
|
||||
|
||||
```
|
||||
GSD > MEMPALACE CAPTURE
|
||||
```
|
||||
|
||||
Then proceed to Step 1.
|
||||
|
||||
## Step 1 -- Config Gate
|
||||
|
||||
Check whether the MemPalace capability is enabled by reading `.planning/config.json` directly with the Read tool.
|
||||
|
||||
1. Read `.planning/config.json` with the Read tool.
|
||||
2. If the file does not exist, or `config.mempalace` is absent, or `config.mempalace.enabled !== true`, or `config.mempalace.capture_artifacts !== true`: display the disabled message and **STOP**.
|
||||
3. Otherwise proceed to Step 2.
|
||||
|
||||
**Disabled message:**
|
||||
|
||||
```
|
||||
GSD > MEMPALACE CAPTURE
|
||||
|
||||
MemPalace capture is disabled (mempalace.enabled / mempalace.capture_artifacts).
|
||||
Nothing was filed; the loop proceeds normally.
|
||||
```
|
||||
|
||||
This step is `onError: skip` at `discuss:post` / `plan:post` / `verify:post` -- capture never fails a phase.
|
||||
|
||||
## Step 2 -- Resolve target
|
||||
|
||||
1. **Artifact.** Take the artifact from `$ARGUMENTS`. If absent, infer from the loop point: `discuss:post` → `CONTEXT.md`, `plan:post` → `PLAN.md`, `verify:post` → `SUMMARY.md`.
|
||||
2. **Room.** Map artifact → room:
|
||||
- `CONTEXT.md` → `decisions`
|
||||
- `PLAN.md` → `planning`
|
||||
- `SUMMARY.md` → `milestones`
|
||||
(Confirmed problem→fix pairs go to `problems` — see the `capture-problems` fragment used at `execute:wave:post`.)
|
||||
3. **Wing.** `config.mempalace.wing` if non-empty, else `config.project_code`, else the repo directory name.
|
||||
4. **Mode / transport.** Read `config.mempalace.memory_mode`. Prefer MCP (`mempalace_*`) when your MemPalace MCP server is registered and your runtime permits those tools; otherwise use the `mempalace` CLI (covered by this skill's `Bash` allow-tool), as in `mempalace-recall`.
|
||||
|
||||
## Step 3 -- File verbatim (idempotent)
|
||||
|
||||
On any error or timeout, stop and let the phase continue -- capture is best-effort.
|
||||
|
||||
1. **Dedup first.** Interactive: `mempalace_check_duplicate` on the artifact's deterministic drawer id. Headless: rely on `mempalace mine`'s content-hash idempotency.
|
||||
2. **Add the drawer (verbatim).** File the exact artifact text into `room: <room>` of `wing: <wing>` with provenance (`source_file`, phase id). Interactive: `mempalace_add_drawer`. Headless: `mempalace mine <path> --wing <wing> --room <room>`.
|
||||
3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Only `augment` is currently wired, so these are an *additive* mirror of `.planning/graphs/`. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
|
||||
4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
|
||||
|
||||
## Step 4 -- Report
|
||||
|
||||
Print a one-line summary: `Filed <artifact> → <wing>/<room> (<n> KG facts)` or `MemPalace unavailable — capture skipped`.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
1. DO NOT let any MemPalace error fail the step -- capture is `onError: skip`.
|
||||
2. DO NOT write lossy summaries -- store the verbatim artifact text (AAAK compression is a separate, optional index).
|
||||
3. DO NOT prune or delete drawers here -- pruning (`sync --apply`) is the curator agent's job at `ship:post`, wing-scoped only.
|
||||
4. DO NOT skip the config gate or the dedup check.
|
||||
102
skills/gsd-mempalace-recall/SKILL.md
Normal file
102
skills/gsd-mempalace-recall/SKILL.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: gsd-mempalace-recall
|
||||
description: "Recall decisions, patterns, and surprises from MemPalace before planning"
|
||||
argument-hint: "[phase-slug]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
---
|
||||
|
||||
|
||||
**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
|
||||
|
||||
## Step 0 -- Banner
|
||||
|
||||
**Before ANY tool calls**, display this banner:
|
||||
|
||||
```
|
||||
GSD > MEMPALACE RECALL
|
||||
```
|
||||
|
||||
Then proceed to Step 1.
|
||||
|
||||
## Step 1 -- Config Gate
|
||||
|
||||
Check whether the MemPalace capability is enabled by reading `.planning/config.json` directly with the Read tool.
|
||||
|
||||
**DO NOT use `gsd-tools config get-value`** -- it hard-exits on missing keys.
|
||||
|
||||
1. Read `.planning/config.json` with the Read tool.
|
||||
2. If the file does not exist: write the "unavailable" stub (Step 4) and **STOP**.
|
||||
3. Parse the JSON. Proceed to Step 2 only if `config.mempalace && config.mempalace.enabled === true` **and** `config.mempalace.recall_on_plan !== false`. Otherwise display the disabled message and **STOP** (`recall_on_plan: false` turns plan-time recall off while leaving the rest of the capability enabled).
|
||||
|
||||
**Disabled message:**
|
||||
|
||||
```
|
||||
GSD > MEMPALACE RECALL
|
||||
|
||||
MemPalace memory is disabled. To activate:
|
||||
|
||||
node <runtime-home>/gsd-core/bin/gsd-tools.cjs config-set mempalace.enabled true
|
||||
|
||||
Recall is opt-in; the loop proceeds normally without it.
|
||||
```
|
||||
|
||||
This step is `onError: skip` at `plan:pre` -- recall never blocks planning.
|
||||
|
||||
## Step 2 -- Resolve wing, mode, and transport
|
||||
|
||||
1. **Wing.** Use `config.mempalace.wing` if non-empty; otherwise derive from `config.project_code`; otherwise fall back to the repository directory name.
|
||||
2. **Mode.** Read `config.mempalace.memory_mode` (`augment` | `kg_backend` | `replace`, default `augment`). Only `augment` is wired today, so recall always treats the palace as additive; `kg_backend`/`replace` are forward-declared and behave as `augment`.
|
||||
3. **Transport.** Prefer the **MCP tools** (`mempalace_*`) in interactive runs *when your MemPalace MCP server is registered and your runtime permits those tools*. Otherwise — headless/cron/autonomous runs, or runtimes that don't grant the MemPalace MCP tools — use the **CLI** (`mempalace wake-up`, `mempalace search`), which this skill's `Bash` allow-tool always covers. If neither is reachable, go to Step 4.
|
||||
4. **Topic.** Read the phase `CONTEXT.md` (the consumed artifact). Derive a short search query from its title, goal, and key decisions.
|
||||
|
||||
## Step 3 -- Retrieve (read-only)
|
||||
|
||||
All calls in this step are side-effect-free. On any error or timeout, stop retrieving and write whatever was gathered (or the stub) -- never raise.
|
||||
|
||||
1. **Wake up** (cheap, ~600--900 tokens):
|
||||
- Interactive: read the wing identity/summary, then `mempalace_search`.
|
||||
- Headless: `mempalace wake-up --wing <wing>`.
|
||||
2. **Targeted search:**
|
||||
- Interactive: `mempalace_search(query=<topic>, wing=<wing>)`.
|
||||
- Headless: `mempalace search "<topic>" --wing <wing>`.
|
||||
3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Only `augment` is currently wired, so the palace KG *supplements* GSD's native `.planning/graphs/` — do not treat it as the sole source. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
|
||||
4. **Dedup** the returned drawers/facts; keep the top results.
|
||||
|
||||
## Step 4 -- Write MEMORY-RECALL.md
|
||||
|
||||
Write `MEMORY-RECALL.md` in the current phase directory. The planner consumes it.
|
||||
|
||||
When recall succeeded, structure it as:
|
||||
|
||||
```markdown
|
||||
# Memory Recall (MemPalace)
|
||||
|
||||
_Wing: <wing> · Mode: <mode> · Transport: <mcp|cli>_
|
||||
|
||||
## Prior decisions
|
||||
- <decision> — <provenance: drawer id / kg fact, valid_from>
|
||||
|
||||
## Patterns
|
||||
- <pattern> — <provenance>
|
||||
|
||||
## Surprises / gotchas
|
||||
- <surprise> — <provenance>
|
||||
```
|
||||
|
||||
When MemPalace is unreachable, write the stub and continue:
|
||||
|
||||
```markdown
|
||||
# Memory Recall (MemPalace)
|
||||
|
||||
_MemPalace unavailable at recall time — proceeding without recalled memory._
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
1. DO NOT let any MemPalace error fail the step -- recall is `onError: skip`.
|
||||
2. DO NOT write to the palace from this skill -- recall is read-only; capture is a separate skill.
|
||||
3. DO NOT paste raw search output into the file -- distil to decisions/patterns/surprises with provenance.
|
||||
4. DO NOT skip the config gate.
|
||||
51
skills/gsd-milestone-summary/SKILL.md
Normal file
51
skills/gsd-milestone-summary/SKILL.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: gsd-milestone-summary
|
||||
description: "Generate a comprehensive project summary from milestone artifacts for team onboarding and review"
|
||||
argument-hint: "[version]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Grep
|
||||
- Glob
|
||||
---
|
||||
|
||||
|
||||
<objective>
|
||||
Generate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why.
|
||||
|
||||
Purpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions.
|
||||
Output: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/gsd-core/workflows/milestone-summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Project files:**
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/PROJECT.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/RETROSPECTIVE.md`
|
||||
- `.planning/milestones/v{version}-ROADMAP.md` (if archived)
|
||||
- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived)
|
||||
- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md)
|
||||
|
||||
**User input:**
|
||||
- Version: $ARGUMENTS (optional — defaults to current/latest milestone)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Milestone version resolved (from args, STATE.md, or archive scan)
|
||||
- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE)
|
||||
- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md`
|
||||
- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started)
|
||||
- Summary presented inline to user
|
||||
- Interactive Q&A offered
|
||||
- STATE.md updated
|
||||
</success_criteria>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user