* feat(sdk): golden parity harness and query handler CJS alignment (#2302 Track A) Golden/read-only parity tests and registry alignment, query handler fixes (check-completion, state-mutation, commit, validate, summary, etc.), and WAITING.json dual-write for .gsd/.planning readers. Refs gsd-build/get-shit-done#2341 * fix(sdk): getMilestoneInfo matches GSD ROADMAP (🟡, last bold, STATE fallback) - Recognize in-flight 🟡 milestone bullets like 🚧. - Derive from last **vX.Y Title** before ## Phases when emoji absent. - Fall back to STATE.md milestone when ROADMAP is missing; use last bare vX.Y in cleaned text instead of first (avoids v1.0 from shipped list). - Fixes init.execute-phase milestone_version and buildStateFrontmatter after state.begin-phase (syncStateFrontmatter). * feat(sdk): phase list, plan task structure, requirements extract handlers - Register phase.list-plans, phase.list-artifacts, plan.task-structure, requirements.extract-from-plans (SDK-only; golden-policy exceptions). - Add unit tests; document in QUERY-HANDLERS.md. - writeProfile: honor --output, render dimensions, return profile_path and dimensions_scored. * feat(sdk): centralize getGsdAgentsDir in query helpers Extract agent directory resolution to helpers (GSD_AGENTS_DIR, primary ~/.claude/agents, legacy path). Use from init and docs-init init bundles. docs(15): add 15-CONTEXT for autonomous phase-15 run. * feat(sdk): query CLI CJS fallback and session correlation - createRegistry(eventStream, sessionId) threads correlation into mutation events - gsd-sdk query falls back to gsd-tools.cjs when no native handler matches (disable with GSD_QUERY_FALLBACK=off); stderr bridge warnings - Export createRegistry from @gsd-build/sdk; add sdk/README.md - Update QUERY-HANDLERS.md and registry module docs for fallback + sessionId - Agents: prefer node dist/cli.js query over cat/grep for STATE and plans * fix(sdk): init phase_found parity, docs-init agents path, state field extract - Normalize findPhase not-found to null before roadmap fallback (matches findPhaseInternal) - docs-init: use detectRuntime + resolveAgentsDir for checkAgentsInstalled - state.cjs stateExtractField: horizontal whitespace only after colon (YAML progress guard) - Tests: commit_docs default true; config-get golden uses temp config; golden integration green Refs: #2302 * refactor(sdk): share SessionJsonlRecord in profile-extract-messages CodeRabbit nit: dedupe JSONL record shape for isGenuineUserMessage and streamExtractMessages. * fix(sdk): address CodeRabbit major threads (paths, gates, audit, verify) - Resolve @file: and CLI JSON indirection relative to projectDir; guard empty normalized query command - plan.task-structure + intel extract/patch-meta: resolvePathUnderProject containment - check.config-gates: safe string booleans; plan_checker alias precedence over plan_check default - state.validate/sync: phaseTokenMatches + comparePhaseNum ordering - verify.schema-drift: token match phase dirs; files_modified from parsed frontmatter - audit-open: has_scan_errors, unreadable rows, human report when scans fail - requirements PLANNED key PLAN for root PLAN.md; gsd-tools timeout note - ingest-docs: repo-root path containment; classifier output slug-hash Golden parity test strips has_scan_errors until CJS adds field. * fix: Resolve CodeRabbit security and quality findings - Secure intel.ts and cli.ts against path traversal - Catch and validate git add status in commit.ts - Expand roadmap milestone marker extraction - Fix parsing array-of-objects in frontmatter YAML - Fix unhandled config evaluations - Improve coverage test parity mapping * docs(sdk): registry docs and gsd-sdk query call sites (#2302 Track B) Update CHANGELOG, architecture and user guides, workflow call sites, and read-guard tests for gsd-sdk query; sync ARCHITECTURE.md command/workflow counts and directory-tree totals with the repo (80 commands, 77 workflows). Address CodeRabbit: fix markdown tables and emphasis; align CLI-TOOLS GSDTools and state.read docs with implementation; correct roadmap handler name in universal-anti-patterns; resolve settings workflow config path without relying on config_path from state.load. Refs gsd-build/get-shit-done#2340 * test: raise planner character extraction limit to 48K * fix(sdk): resolve build TS error and doc conflict markers
This commit is contained in:
Rezolv
831
CHANGELOG.md
831
CHANGELOG.md
File diff suppressed because it is too large
Load Diff
@@ -76,6 +76,7 @@ Every agent spawned by an orchestrator gets a clean context window (up to 200K t
|
||||
### 2. Thin Orchestrators
|
||||
|
||||
Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:
|
||||
|
||||
- Load context via `gsd-sdk query init.<workflow>` (or legacy `gsd-tools.cjs init <workflow>`)
|
||||
- Spawn specialized agents with focused prompts
|
||||
- Collect results and route to the next step
|
||||
@@ -84,6 +85,7 @@ Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They:
|
||||
### 3. File-Based State
|
||||
|
||||
All state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means:
|
||||
|
||||
- State survives context resets (`/clear`)
|
||||
- State is inspectable by both humans and agents
|
||||
- State can be committed to git for team visibility
|
||||
@@ -95,6 +97,7 @@ Workflow feature flags follow the **absent = enabled** pattern. If a key is miss
|
||||
### 5. Defense in Depth
|
||||
|
||||
Multiple layers prevent common failure modes:
|
||||
|
||||
- Plans are verified before execution (plan-checker agent)
|
||||
- Execution produces atomic commits per task
|
||||
- Post-execution verification checks against phase goals
|
||||
@@ -107,6 +110,7 @@ Multiple layers prevent common failure modes:
|
||||
### Commands (`commands/gsd/*.md`)
|
||||
|
||||
User-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as:
|
||||
|
||||
- **Claude Code:** Custom slash commands (`/gsd-command-name`)
|
||||
- **OpenCode / Kilo:** Slash commands (`/gsd-command-name`)
|
||||
- **Codex:** Skills (`$gsd-command-name`)
|
||||
@@ -118,6 +122,7 @@ User-facing entry points. Each file contains YAML frontmatter (name, description
|
||||
### Workflows (`get-shit-done/workflows/*.md`)
|
||||
|
||||
Orchestration logic that commands reference. Contains the step-by-step process including:
|
||||
|
||||
- Context loading via `gsd-sdk query` init handlers (or legacy `gsd-tools.cjs init`)
|
||||
- Agent spawn instructions with model resolution
|
||||
- Gate/checkpoint definitions
|
||||
@@ -129,6 +134,7 @@ Orchestration logic that commands reference. Contains the step-by-step process i
|
||||
### Agents (`agents/*.md`)
|
||||
|
||||
Specialized agent definitions with frontmatter specifying:
|
||||
|
||||
- `name` — Agent identifier
|
||||
- `description` — Role and purpose
|
||||
- `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)
|
||||
@@ -141,6 +147,7 @@ Specialized agent definitions with frontmatter specifying:
|
||||
Shared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster):
|
||||
|
||||
**Core references:**
|
||||
|
||||
- `checkpoints.md` — Checkpoint type definitions and interaction patterns
|
||||
- `gates.md` — 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier
|
||||
- `model-profiles.md` — Per-agent model tier assignments
|
||||
@@ -156,6 +163,7 @@ Shared knowledge documents that workflows and agents `@-reference` (see [`docs/I
|
||||
- `common-bug-patterns.md` — Common bug patterns for code review and verification
|
||||
|
||||
**Workflow references:**
|
||||
|
||||
- `agent-contracts.md` — Formal interface between orchestrators and agents
|
||||
- `context-budget.md` — Context window budget allocation rules
|
||||
- `continuation-format.md` — Session continuation/resume format
|
||||
@@ -190,7 +198,7 @@ The planner agent (`agents/gsd-planner.md`) was decomposed from a single monolit
|
||||
|
||||
### Templates (`get-shit-done/templates/`)
|
||||
|
||||
Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template fill` and `scaffold` commands to create pre-structured files:
|
||||
Markdown templates for all planning artifacts. Used by `gsd-sdk query template.fill` / `phase.scaffold` (and legacy `gsd-tools.cjs template fill` / top-level `scaffold`) to create pre-structured files:
|
||||
- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files
|
||||
- `phase-prompt.md` — Phase execution prompt template
|
||||
- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates
|
||||
@@ -224,27 +232,29 @@ See [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 1
|
||||
|
||||
Node.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-24-shipped) for the authoritative roster):
|
||||
|
||||
| Module | Responsibility |
|
||||
|--------|---------------|
|
||||
| `core.cjs` | Error handling, output formatting, shared utilities |
|
||||
| `state.cjs` | STATE.md parsing, updating, progression, metrics |
|
||||
| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |
|
||||
| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |
|
||||
| `config.cjs` | config.json read/write, section initialization |
|
||||
| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |
|
||||
| `template.cjs` | Template selection and filling with variable substitution |
|
||||
| `frontmatter.cjs` | YAML frontmatter CRUD operations |
|
||||
| `init.cjs` | Compound context loading for each workflow type |
|
||||
| `milestone.cjs` | Milestone archival, requirements marking |
|
||||
| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |
|
||||
| `model-profiles.cjs` | Model profile resolution table |
|
||||
| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
|
||||
| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |
|
||||
| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
|
||||
| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |
|
||||
| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
|
||||
| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
|
||||
| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
|
||||
|
||||
| Module | Responsibility |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `core.cjs` | Error handling, output formatting, shared utilities |
|
||||
| `state.cjs` | STATE.md parsing, updating, progression, metrics |
|
||||
| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing |
|
||||
| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |
|
||||
| `config.cjs` | config.json read/write, section initialization |
|
||||
| `verify.cjs` | Plan structure, phase completeness, reference, commit validation |
|
||||
| `template.cjs` | Template selection and filling with variable substitution |
|
||||
| `frontmatter.cjs` | YAML frontmatter CRUD operations |
|
||||
| `init.cjs` | Compound context loading for each workflow type |
|
||||
| `milestone.cjs` | Milestone archival, requirements marking |
|
||||
| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) |
|
||||
| `model-profiles.cjs` | Model profile resolution table |
|
||||
| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation |
|
||||
| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support |
|
||||
| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
|
||||
| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer |
|
||||
| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
|
||||
| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning |
|
||||
| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation |
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -255,10 +265,10 @@ Node.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit
|
||||
```
|
||||
Orchestrator (workflow .md)
|
||||
│
|
||||
├── Load context: gsd-tools.cjs init <workflow> <phase>
|
||||
├── Load context: gsd-sdk query init.<workflow> <phase> (or legacy gsd-tools.cjs init)
|
||||
│ Returns JSON with: project info, config, state, phase details
|
||||
│
|
||||
├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
|
||||
├── Resolve model: gsd-sdk query resolve-model <agent-name>
|
||||
│ Returns: opus | sonnet | haiku | inherit
|
||||
│
|
||||
├── Spawn Agent (Task/SubAgent call)
|
||||
@@ -269,27 +279,29 @@ Orchestrator (workflow .md)
|
||||
│
|
||||
├── Collect result
|
||||
│
|
||||
└── Update state: gsd-tools.cjs state update/patch/advance-plan
|
||||
└── Update state: gsd-sdk query state.update / state.patch / state.advance-plan (or legacy gsd-tools.cjs)
|
||||
```
|
||||
|
||||
### Primary Agent Spawn Categories
|
||||
|
||||
Conceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).
|
||||
|
||||
| Category | Agents | Parallelism |
|
||||
|----------|--------|-------------|
|
||||
| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
|
||||
| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |
|
||||
| **Planners** | gsd-planner, gsd-roadmapper | Sequential |
|
||||
| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |
|
||||
| **Executors** | gsd-executor | Parallel within waves, sequential across waves |
|
||||
| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |
|
||||
| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |
|
||||
| **Debuggers** | gsd-debugger | Sequential (interactive) |
|
||||
| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |
|
||||
| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |
|
||||
| **Profilers** | gsd-user-profiler | Sequential |
|
||||
| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |
|
||||
|
||||
| Category | Agents | Parallelism |
|
||||
| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase |
|
||||
| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) |
|
||||
| **Planners** | gsd-planner, gsd-roadmapper | Sequential |
|
||||
| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) |
|
||||
| **Executors** | gsd-executor | Parallel within waves, sequential across waves |
|
||||
| **Verifiers** | gsd-verifier | Sequential (after all executors complete) |
|
||||
| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) |
|
||||
| **Debuggers** | gsd-debugger | Sequential (interactive) |
|
||||
| **Auditors** | gsd-ui-auditor, gsd-security-auditor | Sequential |
|
||||
| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | Sequential (writer then verifier) |
|
||||
| **Profilers** | gsd-user-profiler | Sequential |
|
||||
| **Analyzers** | gsd-assumptions-analyzer | Sequential (during discuss-phase) |
|
||||
|
||||
|
||||
### Wave Execution Model
|
||||
|
||||
@@ -305,6 +317,7 @@ Wave Analysis:
|
||||
```
|
||||
|
||||
Each executor gets:
|
||||
|
||||
- Fresh 200K context window (or up to 1M for models that support it)
|
||||
- The specific PLAN.md to execute
|
||||
- Project context (PROJECT.md, STATE.md)
|
||||
@@ -317,14 +330,13 @@ When the context window is 500K+ tokens (1M-class models like Opus 4.6, Sonnet 4
|
||||
- **Executor agents** receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md, enabling cross-plan awareness within a phase
|
||||
- **Verifier agents** receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md, enabling history-aware verification
|
||||
|
||||
The orchestrator reads `context_window` from config (`gsd-tools.cjs config-get context_window`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.
|
||||
The orchestrator reads `context_window` from config (`gsd-sdk query config-get context_window`, or legacy `gsd-tools.cjs config-get`) and conditionally includes richer context when the value is >= 500,000. For standard 200K windows, prompts use truncated versions with cache-friendly ordering to maximize context efficiency.
|
||||
|
||||
#### Parallel Commit Safety
|
||||
|
||||
When multiple executors run within the same wave, two mechanisms prevent conflicts:
|
||||
|
||||
1. **`--no-verify` commits** — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.
|
||||
|
||||
1. `--no-verify` commits — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.
|
||||
2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.
|
||||
|
||||
---
|
||||
@@ -430,6 +442,7 @@ UI-SPEC.md (per phase) ───────────────────
|
||||
```
|
||||
|
||||
Equivalent paths for other runtimes:
|
||||
|
||||
- **OpenCode:** `~/.config/opencode/` or `~/.opencode/`
|
||||
- **Kilo:** `~/.config/kilo/` or `~/.kilo/`
|
||||
- **Gemini CLI:** `~/.gemini/`
|
||||
@@ -499,16 +512,16 @@ The installer (`bin/install.js`, ~3,000 lines) handles:
|
||||
2. **Location selection** — Global (`--global`) or local (`--local`)
|
||||
3. **File deployment** — Copies commands, workflows, references, templates, agents, hooks
|
||||
4. **Runtime adaptation** — Transforms file content per runtime:
|
||||
- Claude Code: Uses as-is
|
||||
- OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
|
||||
- Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
|
||||
- Codex: Generates TOML config + skills from commands
|
||||
- Copilot: Maps tool names (Read→read, Bash→execute, etc.)
|
||||
- Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
|
||||
- Antigravity: Skills-first with Google model equivalents
|
||||
- Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
|
||||
- Cline: Writes `.clinerules` for rule-based integration
|
||||
- Augment Code: Skills-first with full skill conversion and config management
|
||||
- Claude Code: Uses as-is
|
||||
- OpenCode: Converts commands/agents to OpenCode-compatible flat command + subagent format
|
||||
- Kilo: Reuses the OpenCode conversion pipeline with Kilo config paths
|
||||
- Codex: Generates TOML config + skills from commands
|
||||
- Copilot: Maps tool names (Read→read, Bash→execute, etc.)
|
||||
- Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`)
|
||||
- Antigravity: Skills-first with Google model equivalents
|
||||
- Trae: Skills-first install to `~/.trae` / `./.trae` with no `settings.json` or hook integration
|
||||
- Cline: Writes `.clinerules` for rule-based integration
|
||||
- Augment Code: Skills-first with full skill conversion and config management
|
||||
5. **Path normalization** — Replaces `~/.claude/` paths with runtime-specific paths
|
||||
6. **Settings integration** — Registers hooks in runtime's `settings.json`
|
||||
7. **Patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-reapply-patches`
|
||||
@@ -545,11 +558,13 @@ Runtime Engine (Claude Code / Gemini CLI)
|
||||
|
||||
### Context Monitor Thresholds
|
||||
|
||||
| Remaining Context | Level | Agent Behavior |
|
||||
|-------------------|-------|----------------|
|
||||
| > 35% | Normal | No warning injected |
|
||||
| ≤ 35% | WARNING | "Avoid starting new complex work" |
|
||||
| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" |
|
||||
|
||||
| Remaining Context | Level | Agent Behavior |
|
||||
| ----------------- | -------- | --------------------------------------- |
|
||||
| > 35% | Normal | No warning injected |
|
||||
| ≤ 35% | WARNING | "Avoid starting new complex work" |
|
||||
| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" |
|
||||
|
||||
|
||||
Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce.
|
||||
|
||||
@@ -564,12 +579,14 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→
|
||||
### Security Hooks (v1.27)
|
||||
|
||||
**Prompt Guard** (`gsd-prompt-guard.js`):
|
||||
|
||||
- Triggers on Write/Edit to `.planning/` files
|
||||
- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection)
|
||||
- Advisory-only — logs detection, does not block
|
||||
- Patterns are inlined (subset of `security.cjs`) for hook independence
|
||||
|
||||
**Workflow Guard** (`gsd-workflow-guard.js`):
|
||||
|
||||
- Triggers on Write/Edit to non-`.planning/` files
|
||||
- Detects edits outside GSD workflow context (no active `/gsd-` command or Task subagent)
|
||||
- Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes
|
||||
@@ -581,18 +598,20 @@ Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→
|
||||
|
||||
GSD supports multiple AI coding runtimes through a unified command/workflow architecture:
|
||||
|
||||
| Runtime | Command Format | Agent System | Config Location |
|
||||
|---------|---------------|--------------|-----------------|
|
||||
| Claude Code | `/gsd-command` | Task spawning | `~/.claude/` |
|
||||
| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` |
|
||||
| Kilo | `/gsd-command` | Subagent mode | `~/.config/kilo/` |
|
||||
| Gemini CLI | `/gsd-command` | Task spawning | `~/.gemini/` |
|
||||
| Codex | `$gsd-command` | Skills | `~/.codex/` |
|
||||
| Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
|
||||
| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
|
||||
| Trae | Skills | Skills | `~/.trae/` |
|
||||
| Cline | Rules | Rules | `.clinerules` |
|
||||
| Augment Code | Skills | Skills | Augment config |
|
||||
|
||||
| Runtime | Command Format | Agent System | Config Location |
|
||||
| ------------ | -------------- | ---------------- | ------------------------ |
|
||||
| Claude Code | `/gsd-command` | Task spawning | `~/.claude/` |
|
||||
| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` |
|
||||
| Kilo | `/gsd-command` | Subagent mode | `~/.config/kilo/` |
|
||||
| Gemini CLI | `/gsd-command` | Task spawning | `~/.gemini/` |
|
||||
| Codex | `$gsd-command` | Skills | `~/.codex/` |
|
||||
| Copilot | `/gsd-command` | Agent delegation | `~/.github/` |
|
||||
| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
|
||||
| Trae | Skills | Skills | `~/.trae/` |
|
||||
| Cline | Rules | Rules | `.clinerules` |
|
||||
| Augment Code | Skills | Skills | Augment config |
|
||||
|
||||
|
||||
### Abstraction Points
|
||||
|
||||
|
||||
@@ -1,29 +1,71 @@
|
||||
# GSD CLI Tools Reference
|
||||
|
||||
> Programmatic API reference for `gsd-tools.cjs`. Used by workflows and agents internally. For user-facing commands, see [Command Reference](COMMANDS.md).
|
||||
> Surface-area reference for `get-shit-done/bin/gsd-tools.cjs` (legacy Node CLI). Workflows and agents should prefer `gsd-sdk query` or `@gsd-build/sdk` where a handler exists — see [SDK and programmatic access](#sdk-and-programmatic-access). For slash commands and user flows, see [Command Reference](COMMANDS.md).
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
`gsd-tools.cjs` is a Node.js CLI utility that replaces repetitive inline bash patterns across GSD's ~50 command, workflow, and agent files. It centralizes: config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations.
|
||||
`gsd-tools.cjs` centralizes config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations across GSD commands, workflows, and agents.
|
||||
|
||||
**Preferred for new orchestration:** Many of the same operations are available as `gsd-sdk query <command>` (see `sdk/src/query/index.ts` and `docs/QUERY-HANDLERS.md`). Use that in workflows and examples where the handler exists; keep `node … gsd-tools.cjs` for commands not yet in the registry (for example graphify) or when you need CJS-only flags.
|
||||
|
||||
**Location:** `get-shit-done/bin/gsd-tools.cjs`
|
||||
**Modules:** see the [Module Architecture](#module-architecture) table; the `get-shit-done/bin/lib/` directory is authoritative.
|
||||
| | |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Shipped path** | `get-shit-done/bin/gsd-tools.cjs` |
|
||||
| **Implementation** | 20 domain modules under `get-shit-done/bin/lib/` (the directory is authoritative) |
|
||||
| **Status** | Maintained for parity tests and CJS-only entrypoints; `gsd-sdk query` / SDK registry are the supported path for new orchestration (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). |
|
||||
|
||||
|
||||
**Usage (CJS):**
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
||||
```
|
||||
|
||||
**Global Flags:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--raw` | Machine-readable output (JSON or plain text, no formatting) |
|
||||
| `--cwd <path>` | Override working directory (for sandboxed subagents) |
|
||||
| `--ws <name>` | Target a specific workstream context (SDK only) |
|
||||
**Global flags (CJS):**
|
||||
|
||||
|
||||
| Flag | Description |
|
||||
| -------------- | ---------------------------------------------------------------------------- |
|
||||
| `--raw` | Machine-readable output (JSON or plain text, no formatting) |
|
||||
| `--cwd <path>` | Override working directory (for sandboxed subagents) |
|
||||
| `--ws <name>` | Workstream context (also honored when the SDK spawns this binary; see below) |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## SDK and programmatic access
|
||||
|
||||
Use this when authoring workflows, not when you only need the command list below.
|
||||
|
||||
**1. CLI — `gsd-sdk query <argv…>`**
|
||||
|
||||
- Resolves argv with the same **longest-prefix** rules as the typed registry (`resolveQueryArgv` in `sdk/src/query/registry.ts`). Unregistered commands **fail fast** — use `node …/gsd-tools.cjs` only for handlers not in the registry.
|
||||
- Full matrix (CJS command → registry key, CLI-only tools, aliases, golden tiers): [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
|
||||
|
||||
**2. TypeScript — `@gsd-build/sdk` (`GSDTools`, `createRegistry`)**
|
||||
|
||||
- `GSDTools` (used by `PhaseRunner`, `InitRunner`, and `GSD.createTools()`) always shells out to `gsd-tools.cjs` via `execFile` — there is no in-process registry path on this class. For typed, in-process dispatch use `createRegistry()` from `sdk/src/query/index.ts`, or invoke `gsd-sdk query` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)).
|
||||
- Conventions: mutation event wiring, `GSDError` vs `{ data: { error } }`, locks, and stubs — [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
|
||||
|
||||
**CJS → SDK examples (same project directory):**
|
||||
|
||||
|
||||
| Legacy CJS | Preferred `gsd-sdk query` (examples) |
|
||||
| ---------------------------------------- | ------------------------------------ |
|
||||
| `node gsd-tools.cjs init phase-op 12` | `gsd-sdk query init phase-op 12` |
|
||||
| `node gsd-tools.cjs phase-plan-index 12` | `gsd-sdk query phase-plan-index 12` |
|
||||
| `node gsd-tools.cjs state json` | `gsd-sdk query state json` |
|
||||
| `node gsd-tools.cjs roadmap analyze` | `gsd-sdk query roadmap analyze` |
|
||||
|
||||
|
||||
**SDK state reads:** `gsd-sdk query state json` / `state.json` and `gsd-sdk query state load` / `state.load` currently share one native handler (rebuilt STATE.md frontmatter — CJS `cmdStateJson`). The legacy CJS `state load` payload (`config`, `state_raw`, existence flags) is still **CLI-only** via `node …/gsd-tools.cjs state load` until a separate registry handler exists. Full routing and golden rules: [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
|
||||
|
||||
**CLI-only (not in registry):** e.g. **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` until registered.
|
||||
|
||||
**Mutation events (SDK):** `QUERY_MUTATION_COMMANDS` in `sdk/src/query/index.ts` lists commands that may emit structured events after a successful dispatch. Exceptions called out in QUERY-HANDLERS: `state validate` (read-only), `skill-manifest` (writes only with `--write`), `intel update` (stub).
|
||||
|
||||
**Golden parity:** Policy and CJS↔SDK test categories are documented under **Golden parity** in [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -373,7 +415,7 @@ node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
|
||||
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]
|
||||
```
|
||||
|
||||
> **`--no-verify`**: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally.
|
||||
> `--no-verify`: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally.
|
||||
|
||||
# Web search (requires Brave API key)
|
||||
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
|
||||
@@ -430,3 +472,11 @@ User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gs
|
||||
| Audit | `lib/audit.cjs` | Phase/milestone audit queue handlers; `audit-open` helper |
|
||||
| GSD2 Import | `lib/gsd2-import.cjs` | Reverse-migration importer from GSD-2 projects (backs `/gsd-from-gsd2`) |
|
||||
| Intel | `lib/intel.cjs` | Queryable codebase intelligence index (backs `/gsd-intel`) |
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md) — registry matrix, routing, golden parity, intentional CJS differences
|
||||
- [Architecture](ARCHITECTURE.md) — where `gsd-sdk query` fits in orchestration
|
||||
- [Command Reference](COMMANDS.md) — user-facing `/gsd:` commands
|
||||
|
||||
@@ -247,7 +247,7 @@ Any GSD agent type can receive skills. Common types:
|
||||
|
||||
### How It Works
|
||||
|
||||
At spawn time, workflows call `node gsd-tools.cjs agent-skills <type>` to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the Task() prompt:
|
||||
At spawn time, workflows call `gsd-sdk query agent-skills <type>` (or legacy `node gsd-tools.cjs agent-skills <type>`) to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the Task() prompt:
|
||||
|
||||
```xml
|
||||
<agent_skills>
|
||||
@@ -264,7 +264,7 @@ If no skills are configured, the block is omitted (zero overhead).
|
||||
Set skills via the CLI:
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set agent_skills.gsd-executor '["skills/my-skill"]'
|
||||
gsd-sdk query config-set agent_skills.gsd-executor '["skills/my-skill"]'
|
||||
```
|
||||
|
||||
---
|
||||
@@ -292,10 +292,10 @@ Toggle optional capabilities via the `features.*` config namespace. Feature flag
|
||||
|
||||
```bash
|
||||
# Enable a feature
|
||||
node gsd-tools.cjs config-set features.global_learnings true
|
||||
gsd-sdk query config-set features.global_learnings true
|
||||
|
||||
# Disable a feature
|
||||
node gsd-tools.cjs config-set features.thinking_partner false
|
||||
gsd-sdk query config-set features.thinking_partner false
|
||||
```
|
||||
|
||||
The `features.*` namespace is a dynamic key pattern — new feature flags can be added without modifying `VALID_CONFIG_KEYS`. Any key matching `features.<name>` is accepted by the config system.
|
||||
|
||||
@@ -165,12 +165,14 @@ By default, `/gsd-discuss-phase` asks open-ended questions about your implementa
|
||||
**Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`.
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Reads PROJECT.md, codebase mapping, and existing conventions
|
||||
2. Generates a structured list of assumptions (tech choices, patterns, file locations)
|
||||
3. Presents assumptions for you to confirm, correct, or expand
|
||||
4. Writes CONTEXT.md from confirmed assumptions
|
||||
|
||||
**When to use:**
|
||||
|
||||
- Experienced developers who already know their codebase well
|
||||
- Rapid iteration where open-ended questions slow you down
|
||||
- Projects where patterns are well-established and predictable
|
||||
@@ -189,16 +191,19 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
|
||||
|
||||
### Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
|
||||
| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
|
||||
|
||||
| Command | Description |
|
||||
| -------------------- | -------------------------------------------------------- |
|
||||
| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
|
||||
| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
|
||||
|
||||
|
||||
### Workflow: `/gsd-ui-phase`
|
||||
|
||||
**When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work.
|
||||
|
||||
**Flow:**
|
||||
|
||||
1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
|
||||
2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
|
||||
3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
|
||||
@@ -216,6 +221,7 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
|
||||
**Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.
|
||||
|
||||
**6 Pillars (scored 1-4 each):**
|
||||
|
||||
1. Copywriting — CTA labels, empty states, error states
|
||||
2. Visuals — focal points, visual hierarchy, icon accessibility
|
||||
3. Color — accent usage discipline, 60/30/10 compliance
|
||||
@@ -227,10 +233,12 @@ AI-generated frontends are visually inconsistent not because Claude Code is bad
|
||||
|
||||
### Configuration
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
|
||||
| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
|
||||
|
||||
| Setting | Default | Description |
|
||||
| ------------------------- | ------- | ----------------------------------------------------------- |
|
||||
| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
|
||||
| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
|
||||
|
||||
|
||||
Both follow the absent=enabled pattern. Disable via `/gsd-settings`.
|
||||
|
||||
@@ -248,6 +256,7 @@ The preset string becomes a first-class GSD planning artifact, reproducible acro
|
||||
### Registry Safety Gate
|
||||
|
||||
Third-party shadcn registries can inject arbitrary code. The safety gate requires:
|
||||
|
||||
- `npx shadcn view {component}` — inspect before installing
|
||||
- `npx shadcn diff {component}` — compare against official
|
||||
|
||||
@@ -365,12 +374,14 @@ Workstreams let you work on multiple milestone areas concurrently without state
|
||||
|
||||
### Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/gsd-workstreams create <name>` | Create a new workstream with isolated planning state |
|
||||
| `/gsd-workstreams switch <name>` | Switch active context to a different workstream |
|
||||
| `/gsd-workstreams list` | Show all workstreams and which is active |
|
||||
| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state |
|
||||
|
||||
| Command | Purpose |
|
||||
| ---------------------------------- | ---------------------------------------------------- |
|
||||
| `/gsd-workstreams create <name>` | Create a new workstream with isolated planning state |
|
||||
| `/gsd-workstreams switch <name>` | Switch active context to a different workstream |
|
||||
| `/gsd-workstreams list` | Show all workstreams and which is active |
|
||||
| `/gsd-workstreams complete <name>` | Mark a workstream as done and archive its state |
|
||||
|
||||
|
||||
### How It Works
|
||||
|
||||
@@ -393,6 +404,7 @@ All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve w
|
||||
The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
|
||||
|
||||
**Runtime Hooks:**
|
||||
|
||||
- `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
|
||||
- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
|
||||
|
||||
@@ -598,11 +610,13 @@ claude --dangerously-skip-permissions
|
||||
|
||||
### Speed vs Quality Presets
|
||||
|
||||
| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
|
||||
|----------|------|-------|---------|----------|------------|----------|
|
||||
| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
|
||||
| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
|
||||
| Production | `interactive` | `fine` | `quality` | on | on | on |
|
||||
|
||||
| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
|
||||
| ----------- | ------------- | ----------- | ---------- | -------- | ---------- | -------- |
|
||||
| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
|
||||
| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
|
||||
| Production | `interactive` | `fine` | `quality` | on | on | on |
|
||||
|
||||
|
||||
**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.
|
||||
|
||||
@@ -637,6 +651,7 @@ cd ~/gsd-workspaces/feature-b
|
||||
```
|
||||
|
||||
Each workspace gets:
|
||||
|
||||
- Its own `.planning/` directory (fully independent from source repos)
|
||||
- Git worktrees (default) or clones of specified repos
|
||||
- A `WORKSPACE.md` manifest tracking member repos
|
||||
@@ -647,9 +662,9 @@ Each workspace gets:
|
||||
|
||||
### Programmatic CLI (`gsd-sdk query` vs `gsd-tools.cjs`)
|
||||
|
||||
For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md](CLI-TOOLS.md) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy **`node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs`** CLI remains supported for dual-mode operation.
|
||||
For automation and copy-paste from docs, prefer **`gsd-sdk query`** with a registered subcommand (see [CLI-TOOLS.md — SDK and programmatic access](CLI-TOOLS.md#sdk-and-programmatic-access) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI remains supported for dual-mode operation.
|
||||
|
||||
**Not yet on `gsd-sdk query` (use CJS):** `state validate`, `state sync`, `audit-open`, `graphify`, `from-gsd2`, and any subcommand not listed in the registry.
|
||||
**CLI-only (not in the query registry):** **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). **Two different `state` JSON shapes in the legacy CLI:** `state json` (frontmatter rebuild) vs `state load` (`config` + `state_raw` + flags). **`gsd-sdk query` today:** both `state.json` and `state.load` resolve to the frontmatter-rebuild handler — use `node …/gsd-tools.cjs state load` when you need the CJS `state load` shape. See [CLI-TOOLS.md](CLI-TOOLS.md#sdk-and-programmatic-access) and QUERY-HANDLERS.
|
||||
|
||||
### STATE.md Out of Sync
|
||||
|
||||
@@ -782,6 +797,7 @@ If `npx get-shit-done-cc` fails due to npm outages or network restrictions, see
|
||||
When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd-forensics` to generate a diagnostic report.
|
||||
|
||||
**What it checks:**
|
||||
|
||||
- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
|
||||
- Artifact integrity (missing or malformed planning files, broken cross-references)
|
||||
- State inconsistencies (ROADMAP status vs. actual file presence, config drift)
|
||||
@@ -916,22 +932,24 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo
|
||||
|
||||
## Recovery Quick Reference
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
|
||||
| Phase went wrong | `git revert` the phase commits, then re-plan |
|
||||
| Need to change scope | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase` |
|
||||
| Milestone audit found gaps | `/gsd-plan-milestone-gaps` |
|
||||
| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
|
||||
| STATE.md out of sync | `state validate` then `state sync` |
|
||||
| Workflow state seems corrupted | `/gsd-forensics` |
|
||||
| Quick targeted fix | `/gsd-quick` |
|
||||
| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
|
||||
| Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off |
|
||||
| Update broke local changes | `/gsd-reapply-patches` |
|
||||
| Want session summary for stakeholder | `/gsd-session-report` |
|
||||
| Don't know what step is next | `/gsd-next` |
|
||||
| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
|
||||
|
||||
| Problem | Solution |
|
||||
| ------------------------------------ | ------------------------------------------------------------------------ |
|
||||
| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
|
||||
| Phase went wrong | `git revert` the phase commits, then re-plan |
|
||||
| Need to change scope | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase` |
|
||||
| Milestone audit found gaps | `/gsd-plan-milestone-gaps` |
|
||||
| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
|
||||
| STATE.md out of sync | `state validate` then `state sync` |
|
||||
| Workflow state seems corrupted | `/gsd-forensics` |
|
||||
| Quick targeted fix | `/gsd-quick` |
|
||||
| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
|
||||
| Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off |
|
||||
| Update broke local changes | `/gsd-reapply-patches` |
|
||||
| Want session summary for stakeholder | `/gsd-session-report` |
|
||||
| Don't know what step is next | `/gsd-next` |
|
||||
| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -975,3 +993,4 @@ For reference, here is what GSD creates in your project:
|
||||
XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
|
||||
ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
|
||||
```
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Copy-paste friendly for Discord and GitHub comments.
|
||||
|
||||
---
|
||||
|
||||
**@gsd-build/sdk** replaces the untyped, monolithic `gsd-tools.cjs` subprocess with a typed, tested, registry-based query system and **`gsd-sdk query`**, giving GSD structured results, classified errors (`GSDQueryError`), and golden-verified parity with the old CLI. That gives the framework one stable contract instead of a fragile, very large CLI that every workflow had to spawn and parse by hand.
|
||||
**@gsd-build/sdk** replaces the untyped, monolithic `gsd-tools.cjs` subprocess with a typed, tested, registry-based query system and **`gsd-sdk query`**, giving GSD structured results, classified errors (`GSDError` with `ErrorClassification`), and golden-verified parity with the old CLI. That gives the framework one stable contract instead of a fragile, very large CLI that every workflow had to spawn and parse by hand.
|
||||
|
||||
**What users can expect**
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Get Shit Done（GSD）フレームワークの包括的なドキュメントで
|
||||
| [機能リファレンス](FEATURES.md) | 全ユーザー | 全機能の詳細ドキュメントと要件 |
|
||||
| [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 |
|
||||
| [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ |
|
||||
| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | `gsd-tools.cjs` のプログラマティック API（ワークフローおよびエージェント向け） |
|
||||
| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | CJS `gsd-tools.cjs` と **`gsd-sdk query` / SDK** のガイド |
|
||||
| [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全18種の専門エージェント — 役割、ツール、スポーンパターン |
|
||||
| [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー |
|
||||
| [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ |
|
||||
|
||||
@@ -12,7 +12,7 @@ Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩
|
||||
| [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 |
|
||||
| [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
|
||||
| [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
|
||||
| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | 워크플로우 및 에이전트를 위한 `gsd-tools.cjs` 프로그래매틱 API |
|
||||
| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | CJS `gsd-tools.cjs` + **`gsd-sdk query`/SDK** 안내 |
|
||||
| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 18개 전문 에이전트의 역할, 도구, 스폰 패턴 |
|
||||
| [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
|
||||
| [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Referência de Ferramentas CLI
|
||||
|
||||
Resumo em Português das ferramentas CLI do GSD.
|
||||
Para API completa (assinaturas, argumentos e comportamento detalhado), consulte [CLI-TOOLS.md em inglês](../CLI-TOOLS.md).
|
||||
Para API completa (assinaturas, argumentos e comportamento detalhado), consulte [CLI-TOOLS.md em inglês](../CLI-TOOLS.md) — inclui a secção **SDK and programmatic access** (`gsd-sdk query`, `@gsd-build/sdk`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Documentação abrangente do framework Get Shit Done (GSD) — um sistema de met
|
||||
| [Referência de configuração](CONFIGURATION.md) | Todos os usuários | Schema completo de configuração, toggles e perfis |
|
||||
| [Referência de recursos](FEATURES.md) | Todos os usuários | Recursos e requisitos detalhados |
|
||||
| [Referência de agentes](AGENTS.md) | Contribuidores, usuários avançados | Agentes especializados, papéis e padrões de orquestração |
|
||||
| [Ferramentas CLI](CLI-TOOLS.md) | Contribuidores, autores de agentes | API programática `gsd-tools.cjs` |
|
||||
| [Ferramentas CLI](CLI-TOOLS.md) | Contribuidores, autores de agentes | Superfície CJS `gsd-tools.cjs` + guia **`gsd-sdk query`/SDK** |
|
||||
| [Monitor de contexto](context-monitor.md) | Todos os usuários | Arquitetura de monitoramento da janela de contexto |
|
||||
| [Discuss Mode](workflow-discuss-mode.md) | Todos os usuários | Modo suposições vs entrevista no `discuss-phase` |
|
||||
| [Referências](references/) | Todos os usuários | Guias complementares de decisão, verificação e padrões |
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
为紧急插入计算下一个小数阶段编号。
|
||||
|
||||
## 使用 gsd-tools
|
||||
## 使用 gsd-sdk query
|
||||
|
||||
```bash
|
||||
# 获取阶段 6 之后的下一个小数阶段
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
|
||||
gsd-sdk query phase.next-decimal 6
|
||||
```
|
||||
|
||||
输出：
|
||||
@@ -32,14 +32,13 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6
|
||||
## 提取值
|
||||
|
||||
```bash
|
||||
DECIMAL_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}")
|
||||
DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
|
||||
BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
|
||||
DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick next)
|
||||
BASE_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
|
||||
```
|
||||
|
||||
或使用 --raw 标志：
|
||||
```bash
|
||||
DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
|
||||
DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
|
||||
# 返回: 06.1
|
||||
```
|
||||
|
||||
@@ -57,7 +56,7 @@ DECIMAL_PHASE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-
|
||||
小数阶段目录使用完整的小数编号：
|
||||
|
||||
```bash
|
||||
SLUG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
|
||||
SLUG=$(gsd-sdk query generate-slug "$DESCRIPTION" --raw)
|
||||
PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
|
||||
mkdir -p "$PHASE_DIR"
|
||||
```
|
||||
|
||||
@@ -51,7 +51,7 @@ Phases:
|
||||
提交内容：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
|
||||
gsd-sdk query commit "docs: initialize [project-name] ([N] phases)" .planning/
|
||||
```
|
||||
|
||||
</format>
|
||||
@@ -129,7 +129,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
|
||||
提交内容：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
|
||||
gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
|
||||
```
|
||||
|
||||
**注意：** 代码文件不包含 - 已按任务提交。
|
||||
@@ -149,7 +149,7 @@ Current: [task name]
|
||||
提交内容：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
|
||||
gsd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" .planning/
|
||||
```
|
||||
|
||||
</format>
|
||||
|
||||
@@ -1,13 +1,15 @@
|
||||
# Git 规划提交
|
||||
|
||||
使用 gsd-tools CLI 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态。
|
||||
通过 `gsd-sdk query commit` 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态（与旧版 `gsd-tools.cjs commit` 行为相同）。
|
||||
|
||||
## 通过 CLI 提交
|
||||
|
||||
始终使用 `gsd-tools.cjs commit` 处理 `.planning/` 文件 — 它会自动处理 `commit_docs` 和 gitignore 检查：
|
||||
先传提交说明，再传文件路径（位置参数）。`commit` 不要使用 `--files`（该标志仅用于 `commit-to-subrepo`）。
|
||||
|
||||
对 `.planning/` 文件始终使用此方式 —— 它会自动处理 `commit_docs` 与 gitignore 检查：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
|
||||
gsd-sdk query commit "docs({scope}): {description}" .planning/STATE.md .planning/ROADMAP.md
|
||||
```
|
||||
|
||||
如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。
|
||||
@@ -17,7 +19,7 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {des
|
||||
将 `.planning/` 文件变更合并到上次提交：
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
|
||||
gsd-sdk query commit "" .planning/codebase/*.md --amend
|
||||
```
|
||||
|
||||
## 提交消息模式
|
||||
|
||||
@@ -36,19 +36,19 @@
|
||||
- 用户必须将 `.planning/` 添加到 `.gitignore`
|
||||
- 适用于：OSS 贡献、客户项目、保持规划私有
|
||||
|
||||
**使用 gsd-tools.cjs（推荐）：**
|
||||
**使用 `gsd-sdk query`（推荐）：**
|
||||
|
||||
```bash
|
||||
# 提交时自动检查 commit_docs + gitignore：
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
|
||||
gsd-sdk query commit "docs: update state" .planning/STATE.md
|
||||
|
||||
# 通过 state load 加载配置（返回 JSON）：
|
||||
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
|
||||
INIT=$(gsd-sdk query state.load)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
# commit_docs 在 JSON 输出中可用
|
||||
|
||||
# 或使用包含 commit_docs 的 init 命令：
|
||||
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
|
||||
INIT=$(gsd-sdk query init.execute-phase "1")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
# commit_docs 包含在所有 init 命令输出中
|
||||
```
|
||||
@@ -58,7 +58,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
**通过 CLI 提交（自动处理检查）：**
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md
|
||||
gsd-sdk query commit "docs: update state" .planning/STATE.md
|
||||
```
|
||||
|
||||
CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。
|
||||
@@ -146,14 +146,14 @@ CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动
|
||||
|
||||
使用 `init execute-phase` 返回所有配置为 JSON：
|
||||
```bash
|
||||
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1")
|
||||
INIT=$(gsd-sdk query init.execute-phase "1")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template
|
||||
```
|
||||
|
||||
或使用 `state load` 获取配置值：
|
||||
```bash
|
||||
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
|
||||
INIT=$(gsd-sdk query state.load)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template
|
||||
```
|
||||
|
||||
@@ -54,7 +54,7 @@ Configuration options for `.planning/` directory behavior.
|
||||
- User must add `.planning/` to `.gitignore`
|
||||
- Useful for: OSS contributions, client projects, keeping planning private
|
||||
|
||||
**Using gsd-tools.cjs (preferred):**
|
||||
**Using `gsd-sdk query` (preferred):**
|
||||
|
||||
```bash
|
||||
# Commit with automatic commit_docs + gitignore checks:
|
||||
|
||||
@@ -34,7 +34,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
|
||||
|
||||
## State Management Anti-Patterns
|
||||
|
||||
15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
|
||||
15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-sdk query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
|
||||
|
||||
## Behavioral Rules
|
||||
|
||||
@@ -53,7 +53,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
|
||||
## GSD-Specific Rules
|
||||
|
||||
24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
|
||||
25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
|
||||
25. **Prefer `gsd-sdk query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
|
||||
26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
|
||||
27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
|
||||
|
||||
|
||||
@@ -40,10 +40,8 @@ When a milestone completes:
|
||||
<step name="pre_close_artifact_audit">
|
||||
Before proceeding with milestone close, run the comprehensive open artifact audit.
|
||||
|
||||
`audit-open` is not registered on `gsd-sdk query` yet; use the installed CJS CLI:
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" audit-open 2>/dev/null
|
||||
gsd-sdk query audit-open 2>/dev/null
|
||||
```
|
||||
|
||||
If the output contains open items (any section with count > 0):
|
||||
@@ -59,7 +57,7 @@ These items are open. Choose an action:
|
||||
```
|
||||
|
||||
If user chooses [A] (Acknowledge):
|
||||
1. Re-run `audit-open --json` to get structured data
|
||||
1. Re-run `gsd-sdk query audit-open --json` to get structured data
|
||||
2. Write acknowledged items to STATE.md under `## Deferred Items` section:
|
||||
```markdown
|
||||
## Deferred Items
|
||||
@@ -78,7 +76,7 @@ If user chooses [A] (Acknowledge):
|
||||
|
||||
If output shows all clear (no open items): print `All artifact types clear.` and proceed.
|
||||
|
||||
SECURITY: Audit JSON output is structured data from `audit-open` (gsd-tools.cjs) — validated and sanitized at source. When writing to STATE.md, item slugs and descriptions are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
|
||||
SECURITY: Audit JSON output is structured data from the `audit-open` query handler (same JSON contract as legacy `gsd-tools.cjs audit-open`) — validated and sanitized at source. When writing to STATE.md, item slugs and descriptions are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
|
||||
</step>
|
||||
|
||||
<step name="verify_readiness">
|
||||
|
||||
@@ -622,21 +622,20 @@ Check for auto-advance trigger:
|
||||
gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read chain flag and user preference:
|
||||
3. Read consolidated auto-mode (`active` = chain flag OR user preference):
|
||||
```bash
|
||||
AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` flag present AND `AUTO_CHAIN` is not true:**
|
||||
**If `--auto` flag present AND `AUTO_MODE` is not true:**
|
||||
```bash
|
||||
gsd-sdk query config-set workflow._auto_chain_active true
|
||||
```
|
||||
|
||||
**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
|
||||
**If `--auto` flag present OR `AUTO_MODE` is true:**
|
||||
|
||||
Display banner:
|
||||
```
|
||||
```text
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► AUTO-ADVANCING TO PLAN
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
@@ -1223,18 +1223,17 @@ Check for auto-advance trigger:
|
||||
gsd-sdk query config-set workflow._auto_chain_active false 2>/dev/null
|
||||
fi
|
||||
```
|
||||
3. Read both the chain flag and user preference:
|
||||
3. Read consolidated auto-mode (`active` = chain flag OR user preference):
|
||||
```bash
|
||||
AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` or `--chain` flag present AND `AUTO_CHAIN` is not true:** Persist chain flag to config (handles direct usage without new-project):
|
||||
**If `--auto` or `--chain` flag present AND `AUTO_MODE` is not true:** Persist chain flag to config (handles direct usage without new-project):
|
||||
```bash
|
||||
gsd-sdk query config-set workflow._auto_chain_active true
|
||||
```
|
||||
|
||||
**If `--auto` flag present OR `--chain` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
|
||||
**If `--auto` flag present OR `--chain` flag present OR `AUTO_MODE` is true:**
|
||||
|
||||
Display banner:
|
||||
```
|
||||
|
||||
@@ -865,13 +865,12 @@ Plans with `autonomous: false` require user interaction.
|
||||
|
||||
**Auto-mode checkpoint handling:**
|
||||
|
||||
Read auto-advance config (chain flag + user preference):
|
||||
Read auto-advance config (chain flag OR user preference — same boolean as `check.auto-mode`):
|
||||
```bash
|
||||
AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
When executor returns a checkpoint AND (`AUTO_CHAIN` is `"true"` OR `AUTO_CFG` is `"true"`):
|
||||
When executor returns a checkpoint AND `AUTO_MODE` is `true`:
|
||||
- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
|
||||
- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
|
||||
- **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
|
||||
@@ -1484,13 +1483,12 @@ STOP. Do not proceed to auto-advance or transition.
|
||||
**Auto-advance detection:**
|
||||
|
||||
1. Parse `--auto` flag from $ARGUMENTS
|
||||
2. Read both the chain flag and user preference (chain flag already synced in init step):
|
||||
2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
|
||||
```bash
|
||||
AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CFG=$(gsd-sdk query config-get workflow.auto_advance 2>/dev/null || echo "false")
|
||||
AUTO_MODE=$(gsd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true (AND verification passed with no gaps):**
|
||||
**If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════╗
|
||||
@@ -1503,7 +1501,7 @@ Execute the transition workflow inline (do NOT use Task — orchestrator context
|
||||
|
||||
Read and follow `~/.claude/get-shit-done/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
|
||||
|
||||
**If none of `--auto`, `AUTO_CHAIN`, or `AUTO_CFG` is true:**
|
||||
**If neither `--auto` nor `AUTO_MODE` is true:**
|
||||
|
||||
**STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
|
||||
|
||||
|
||||
@@ -475,9 +475,9 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
|
||||
|
||||
**If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:**
|
||||
|
||||
Read auto-chain state:
|
||||
Read ephemeral chain flag (same field as `check.auto-mode` → `auto_chain_active`):
|
||||
```bash
|
||||
AUTO_CHAIN=$(gsd-sdk query config-get workflow._auto_chain_active 2>/dev/null || echo "false")
|
||||
AUTO_CHAIN=$(gsd-sdk query check auto-mode --pick auto_chain_active 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
**If `AUTO_CHAIN` is `true` (running inside a `--chain` or `--auto` pipeline):**
|
||||
|
||||
@@ -13,13 +13,21 @@ Ensure config exists and load current state:
|
||||
|
||||
```bash
|
||||
gsd-sdk query config-ensure-section
|
||||
GSD_CONFIG_PATH=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-path)
|
||||
INIT=$(gsd-sdk query state.load)
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
# `state.load` returns STATE frontmatter JSON from the SDK — it does not include `config_path`. Orchestrators may set `GSD_CONFIG_PATH` from init phase-op JSON; otherwise resolve the same path gsd-tools uses for flat vs active workstream (#2282).
|
||||
if [[ -z "${GSD_CONFIG_PATH:-}" ]]; then
|
||||
if [[ -f .planning/active-workstream ]]; then
|
||||
WS=$(tr -d '\n\r' < .planning/active-workstream)
|
||||
GSD_CONFIG_PATH=".planning/workstreams/${WS}/config.json"
|
||||
else
|
||||
GSD_CONFIG_PATH=".planning/config.json"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
Creates config.json (at the workstream-aware path) with defaults if missing and loads current config values.
|
||||
Store `$GSD_CONFIG_PATH` — all subsequent reads and writes use this path, not the hardcoded `.planning/config.json`, so active-workstream installs write to the correct location (#2282).
|
||||
Creates `config.json` (at the resolved path) with defaults if missing. `INIT` still holds `state.load` output for any step that needs STATE fields.
|
||||
Store `$GSD_CONFIG_PATH` — all subsequent reads and writes use this path, not a hardcoded `.planning/config.json`, so active-workstream installs target the correct file (#2282).
|
||||
</step>
|
||||
|
||||
<step name="read_current">
|
||||
|
||||
@@ -53,9 +53,7 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")
|
||||
|
||||
**Otherwise:**
|
||||
|
||||
**Text mode:** If TEXT_MODE is enabled (set in the banner step), replace AskUserQuestion calls with plain-text numbered lists — emit the options and ask the user to type the number of their choice.
|
||||
|
||||
Before sketching anything, explore the design intent through conversation. Ask one question at a time — using AskUserQuestion in normal mode, or a plain-text numbered list if TEXT_MODE is active — with a paragraph of context and reasoning for each.
|
||||
Before sketching anything, explore the design intent through conversation. Ask one question at a time using AskUserQuestion, with a paragraph of context and reasoning for each.
|
||||
|
||||
**Questions to cover (adapt to what the user has already shared):**
|
||||
|
||||
|
||||
@@ -388,8 +388,9 @@ installer does not know about and will delete during the wipe.
|
||||
**Do not use bash path-stripping (`${filepath#$RUNTIME_DIR/}`) or `node -e require()`
|
||||
inline** — those patterns fail when `$RUNTIME_DIR` is unset and the stripped
|
||||
relative path may not match manifest key format, which causes CUSTOM_COUNT=0
|
||||
even when custom files exist (bug #1997). Use `gsd-tools detect-custom-files`
|
||||
instead, which resolves paths reliably with Node.js `path.relative()`.
|
||||
even when custom files exist (bug #1997). Use `gsd-sdk query detect-custom-files`
|
||||
when `gsd-sdk` is on `PATH`, or the bundled `gsd-tools.cjs detect-custom-files`
|
||||
otherwise — both resolve paths reliably with Node.js `path.relative()`.
|
||||
|
||||
First, resolve the config directory (`RUNTIME_DIR`) from the install scope
|
||||
detected in `get_installed_version`:
|
||||
@@ -410,17 +411,20 @@ fi
|
||||
If `RUNTIME_DIR` is empty or does not exist, skip this step (no config dir to
|
||||
inspect).
|
||||
|
||||
Otherwise, resolve the path to `gsd-tools.cjs` and run:
|
||||
Otherwise run `detect-custom-files` (prefer SDK when available):
|
||||
|
||||
```bash
|
||||
GSD_TOOLS="$RUNTIME_DIR/get-shit-done/bin/gsd-tools.cjs"
|
||||
if [ -f "$GSD_TOOLS" ] && [ -n "$RUNTIME_DIR" ]; then
|
||||
CUSTOM_JSON=''
|
||||
if [ -n "$RUNTIME_DIR" ] && command -v gsd-sdk >/dev/null 2>&1; then
|
||||
CUSTOM_JSON=$(gsd-sdk query detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
|
||||
elif [ -f "$GSD_TOOLS" ] && [ -n "$RUNTIME_DIR" ]; then
|
||||
CUSTOM_JSON=$(node "$GSD_TOOLS" detect-custom-files --config-dir "$RUNTIME_DIR" 2>/dev/null)
|
||||
CUSTOM_COUNT=$(echo "$CUSTOM_JSON" | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).custom_count);}catch{console.log(0);}})" 2>/dev/null || echo "0")
|
||||
else
|
||||
CUSTOM_COUNT=0
|
||||
fi
|
||||
if [ -z "$CUSTOM_JSON" ]; then
|
||||
CUSTOM_JSON='{"custom_files":[],"custom_count":0}'
|
||||
fi
|
||||
CUSTOM_COUNT=$(echo "$CUSTOM_JSON" | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).custom_count);}catch{console.log(0);}})" 2>/dev/null || echo "0")
|
||||
```
|
||||
|
||||
**If `CUSTOM_COUNT` > 0:**
|
||||
|
||||
@@ -464,7 +464,7 @@ Run phase artifact scan to surface any open items before marking phase verified:
|
||||
`audit-open` is CJS-only until registered on `gsd-sdk query`:
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" audit-open --json 2>/dev/null
|
||||
gsd-sdk query audit-open --json 2>/dev/null
|
||||
```
|
||||
|
||||
Parse the JSON output. For the CURRENT PHASE ONLY, surface:
|
||||
|
||||
@@ -28,7 +28,7 @@ const HOOK_PATH = path.join(__dirname, '..', 'hooks', 'gsd-read-guard.js');
|
||||
*/
|
||||
function runHook(payload, envOverrides = {}) {
|
||||
const input = JSON.stringify(payload);
|
||||
// Sanitize Claude Code env vars so positive-path tests work inside Claude Code sessions
|
||||
// Sanitize CLAUDE_SESSION_ID so positive-path tests work inside Claude Code sessions
|
||||
const env = { ...process.env, CLAUDE_SESSION_ID: '', CLAUDECODE: '', ...envOverrides };
|
||||
try {
|
||||
const stdout = execFileSync(process.execPath, [HOOK_PATH], {
|
||||
|
||||
Reference in New Issue
Block a user