docs: audit and update docs/ for v1.40.0 release (#3048)
* docs(en): update FEATURES/USER-GUIDE/COMMANDS for v1.40.0 surface - FEATURES.md: append v1.40.0 section (#122 skill consolidation, #123 namespace meta-skills, #124 context-window guard, #125 phase-lifecycle status-line read-side); add to TOC. - USER-GUIDE.md: add slash-command form (hyphen vs colon) primer and namespace routing primer; replace deleted slash forms in walkthroughs (`/gsd-add-backlog`, `/gsd-plant-seed`, `/gsd-add-phase`, `/gsd-set-profile`, `/gsd-list-workspaces`, etc.) with consolidated forms (`/gsd-capture --backlog`, `/gsd-phase --insert`, `/gsd-config --profile`, `/gsd-workspace --list`, etc.); fix `/gsd-spike-wrap-up` and `/gsd-sketch-wrap-up` to flag form. - COMMANDS.md: clarify Command Syntax (Gemini = colon form, others = hyphen form); add Namespace Meta-Skills section with all six routers; add `--context` to /gsd-health flag table. Refs #3047 * docs(en): refresh INVENTORY/CLI-TOOLS/STATE-MD-LIFECYCLE for v1.40.0 - INVENTORY.md: workflow-row "Invoked by" column updated to point at consolidated commands (`/gsd-phase` family, `/gsd-workspace --list`, `/gsd-config --advanced/--integrations/--profile`, `/gsd-sketch --wrap-up`, `/gsd-spike --wrap-up`); CLI-modules row for `secrets.cjs` updated to `/gsd-config --integrations`. Command count and namespace meta-skills section already reflect 65 shipped (= 59 consolidated sub-skills + 6 ns-* routers). - CLI-TOOLS.md: add `validate context` row under Validation Commands with the 60 %/70 % threshold envelope used by `/gsd-health --context`. - STATE-MD-LIFECYCLE.md: flip status header from "proposed" to "shipped in v1.40.0" since `parseStateMd()` and `formatGsdState()` now read and render `active_phase`, `next_action`, `next_phases`, and `progress`. `docs/AGENTS.md` audited and verified clean — `gsd-code-fixer` row already lists the correct `/gsd-code-review --fix` spawner; no deleted-skill references found. `docs/INVENTORY-MANIFEST.json` audited and verified clean — already enumerates the 65 commands (including six ns-* routers) and contains no deleted slash forms. Refs #3047 * docs(en): cleanup ARCHITECTURE/CONFIGURATION for v1.40.0 - ARCHITECTURE.md: split Commands install-target list to call out the Gemini colon form (`/gsd:command-name`) vs hyphen form for every other runtime. Add a new subsection covering two-stage hierarchical routing via the six namespace meta-skills (#2792) and a paired note on the MCP token-budget interaction so readers see the two big per-turn cost levers in one place. - CONFIGURATION.md: rewrite three references to the deleted `/gsd-settings-advanced` and `/gsd-settings-integrations` slash forms to use the consolidated `/gsd-config --advanced` / `/gsd-config --integrations` invocations. Add a new "STATE.md Frontmatter (Phase Lifecycle)" section documenting the four optional fields (`active_phase`, `next_action`, `next_phases`, `progress`) read by the v1.40 status-line, with a pointer to STATE-MD-LIFECYCLE.md for the full reference. `docs/manual-update.md` audited and verified clean — already documents `/gsd-update --reapply` (the consolidated form), no reference to the deleted `/gsd-reapply-patches`. Refs #3047 * docs(i18n): mirror v1.40.0 slash-command rename into ja-JP/ko-KR/zh-CN/pt-BR Mechanical token-level renames only — every reference to a deleted micro-skill slash form is rewritten to the consolidated form on the matching parent skill. No prose was machine-translated; new prose sections (slash-form primer, namespace routing primer, v1.40 feature entries, STATE.md frontmatter) were left for human translator follow-up. Renames applied uniformly across all four trees: /gsd-add-todo, /gsd-add-note, /gsd-add-backlog, /gsd-plant-seed, /gsd-check-todos → /gsd-capture[ --note| --backlog|--seed|--list] /gsd-add-phase, /gsd-insert-phase, /gsd-remove-phase, /gsd-edit-phase → /gsd-phase[ --insert| --remove|--edit] /gsd-new-workspace, /gsd-list-workspaces, /gsd-remove-workspace → /gsd-workspace[ --new| --list|--remove] /gsd-settings-advanced, /gsd-settings-integrations, /gsd-set-profile → /gsd-config[ --advanced| --integrations|--profile] /gsd-sketch-wrap-up → /gsd-sketch --wrap-up /gsd-spike-wrap-up → /gsd-spike --wrap-up /gsd-reapply-patches → /gsd-update --reapply /gsd-code-review-fix → /gsd-code-review --fix /gsd-plan-milestone-gaps → /gsd-audit-milestone Refs #3047 * docs(changelog): regroup [Unreleased] under Feature/Enhancement/Fix Replace the existing Keep-a-Changelog \`Added\` / \`Changed\` / \`Performance\` / \`Removed\` / \`Fixed\` sub-headers in the [Unreleased] block with the issue/PR template taxonomy: Added → Feature Changed / Performance → Enhancement Removed → Enhancement Fixed → Fix Order within the release: Feature → Enhancement → Fix. Every bullet preserved verbatim — only headers and grouping changed; the awkward inline-versioned headers (\`### Added — 1.40.0-rc.1\`, \`### Changed — 1.40.0-rc.1\`, \`### Fixed — 1.40.0-rc.1\`) folded into the same buckets with the \`— 1.40.0-rc.1\` suffix dropped, since the [Unreleased] block IS 1.40.0-rc.1. The [1.39.2] hotfix block called out in #3047's spec does not yet exist in CHANGELOG.md (the previously released hotfix is [1.39.1]), so this commit only regroups [Unreleased]. Older release blocks ([1.39.1] and earlier) are frozen and untouched. Refs #3047 * docs(changeset): add fragment for v1.40.0 doc audit Refs #3047 * docs(en): strip leading / from deleted slash-command tokens in FEATURES REQ-CONSOLIDATE-03 and REQ-CONSOLIDATE-04 listed deleted commands by their `/gsd-foo` form for the historical record. The docs-parity tests in bug-3010, bug-3029-3034, and bug-3042-3044 use the regex `/\/gsd-[a-z0-9][a-z0-9-]*/g` to scan user-facing surfaces for any remaining mention of removed slash forms — they cannot tell prose about a deleted command from a live recommendation. Strip the leading slash from the bare-name references (preserve the historical text otherwise). Tests now require a `/` prefix to match, so `gsd-add-todo` reads identically to a human but no longer trips the parser. Verified locally: 65/65 tests pass across the three docs-parity suites that were red on CI run 25270072600. Refs #3047 * docs(en): fix CR feedback + drop literal /gsd:plan-phase from USER-GUIDE CI: tests/bug-2543-gsd-slash-namespace.test.cjs flagged docs/USER-GUIDE.md:35 for embedding the literal `/gsd:plan-phase` token in the parenthetical Gemini-form example. The test scans every .md under docs/ for `/gsd:<live-cmd>` because non-Gemini surfaces must not advertise the colon form. Replaced the literal example with a prose substitution rule. CR: docs/ARCHITECTURE.md:125 — the namespace meta-skills were listed by file-prefix (`gsd-ns-workflow`) but the invocable frontmatter `name:` is the bare form (`gsd-workflow`). Verified against the six `commands/gsd/ns-*.md` files. Replaced with the canonical names and noted the file/name disagreement in-line. CR: docs/COMMANDS.md:723 — `v1.40` aligned to canonical `v1.40.0`. CR: docs/FEATURES.md:2679 — REQ-CTX-GUARD-02 advertised the wrong invocation (`gsd-tools validate context`). The shipped handler is exposed via `gsd-sdk query validate.context` and requires explicit `--tokens-used <int>` + `--context-window <int>` flags (verified against sdk/src/query/validate.ts:849-882 and get-shit-done/bin/lib/validate-command-router.cjs:19-36). CR: docs/zh-CN/README.md:533 — added `inherit` to the profile-options parenthetical to match the canonical set (verified against model-profiles.cjs:29 `VALID_PROFILES = […MODEL_PROFILES['gsd-planner'], 'inherit']`). Verified locally: 74/74 tests pass across the four docs-parity suites that were red on CI runs 25270072600 and 25270182903. Refs #3047
This commit is contained in:
Tom Boucher
5
.changeset/docs-1-40-0-audit.md
Normal file
5
.changeset/docs-1-40-0-audit.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 0
|
||||
---
|
||||
**Documentation refreshed for v1.40.0** — full audit of `docs/` against the 1.40.0-rc.1 release surface. Updates command lists, walkthroughs, and inventory rows for the 86→59 skill consolidation (#2790), the six namespace meta-skills with two-stage routing (#2792), the `/gsd-health --context` guard, the phase-lifecycle status-line read-side (#2833), and the Gemini colon-form / non-Gemini hyphen-form slash-command split. Translations in ja-JP/ko-KR/zh-CN/pt-BR mirror the structural changes; new English prose is marked with `<!-- TODO i18n -->` for human translator follow-up. CHANGELOG.md `[Unreleased]` section regrouped under Feature/Enhancement/Fix headers.
|
||||
114
CHANGELOG.md
114
CHANGELOG.md
@@ -6,20 +6,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
## [Unreleased](https://github.com/gsd-build/get-shit-done/compare/v1.39.1...HEAD)
|
||||
|
||||
### Changed
|
||||
### Feature
|
||||
|
||||
- **Test suite for `config-schema.cjs` is now mutation-resistant** — Stryker measured a 4.62% mutation score on `get-shit-done/bin/lib/config-schema.cjs` (6 killed, 124 survived out of 130). Surviving mutants flagged that existing tests were exercising paths but not verifying outputs: a polarity flip (`return true` → `return false`), a predicate swap (`.some` → `.every`), or a guard removal (`if (VALID_CONFIG_KEYS.has(...)) return true;` → unguarded fallthrough) all passed every test. New `tests/bug-2986-config-schema-mutation-killers.test.cjs` adds 95 tests across four suites that target each surviving mutant class: (1) parameterized `isValidConfigKey('${key}') === true` for every member of `VALID_CONFIG_KEYS` (kills the static-key-fast-path mutation), (2) representative dynamic-pattern keys that match exactly one pattern (kills the `.some` → `.every` mutation, with an inline mutual-exclusivity invariant check), (3) `strictEqual` against the literal boolean `true`/`false` instead of `assert.ok` truthy checks (kills polarity-flip mutations), (4) anchor-tightening cases that differ from valid keys by one character beyond the documented shape (kills regex-loosening mutations on `^`, `$`, and character-class boundaries). Tests use the lib's public surface (typed boolean assertions on `isValidConfigKey` return values), no source-grep. (#2986)
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`gsd-pristine/` is now populated by the installer when local patches are detected** — `saveLocalPatches` declared a `pristineDir` variable and JSDoc'd "saves pristine copies (from manifest) to gsd-pristine/ to enable three-way merge during reapply-patches", but no code ever wrote to that directory. Effect: the `/gsd-reapply-patches` Step 5 verifier (#2972) silently degraded to its over-broad fallback heuristic ("every significant backup line"), exactly the silent-success-on-lost-content failure mode #2969 was designed to prevent. Fix: new `populatePristineDir({ packageSrc, pristineDir, modified, runtime, pathPrefix, isGlobal })` helper runs the install transform pipeline (`copyWithPathReplacement`) into a tmp staging dir, then copies out only the modified-file paths into `gsd-pristine/`. `saveLocalPatches` now accepts a `pristineCtx` and calls the helper when local patches are detected; the install entry point passes the package source root, runtime, pathPrefix, and isGlobal so transforms produce byte-identical output to what `copyWithPathReplacement` would have written under normal install. Soft-fails on transform errors (logs a warning, continues with empty pristine — no worse than pre-fix behavior). Pristine reflects the about-to-install version's content, which is what the verifier needs as the "what would survive without the user's modifications" baseline. Regression covered by `tests/bug-2998-pristine-dir-populated.test.cjs` (6 tests across two suites): asserts the helper is exported, returns 0 for empty modified list, writes one pristine file per source-existing path, skips ghost paths without corrupting pristine, and produces deterministic output (two runs with same inputs yield byte-identical pristine — the property `pristine_hashes` in `backup-meta.json` depends on). (#2998)
|
||||
|
||||
|
||||
- **`release-sdk` hotfix re-run no longer fails at `Dry-run publish validation` when the version is already on npm** — the `Detect prior publish (reconciliation mode)` step sets `skip_publish=true` when the package version is already on the registry, and the actual publish step honors that gate. The `Dry-run publish validation` step was missing the same guard, so any operator re-run of an already-published hotfix (the typical recovery path when later steps fail mid-flight) hit `npm publish --dry-run` first and got `npm error You cannot publish over the previously published versions: X.Y.Z` — `npm publish --dry-run` contacts the registry and rejects existing-version targets even though it doesn't actually publish. The dry-run validation step is now gated on the same `steps.prior_publish.outputs.skip_publish != 'true'` condition as the publish step. The rehearsal still runs on first publishes (where it has value); it skips only in the specific reconciliation case where the publish itself would be skipped. Trigger run: [25233855236](https://github.com/gsd-build/get-shit-done/actions/runs/25233855236/job/73995605643). Regression covered by `tests/bug-2987-dry-run-validation-skip-on-reconciliation.test.cjs`. (#2987)
|
||||
- **`release-sdk` hotfix flow hardened against silent classifier failures, missing-classifier-at-base-tag, and a vestigial merge-back PR step** — three issues surfaced by CodeRabbit's post-merge review of #2981 plus a production failure on the v1.39.1 release run. **(1)** `scripts/diff-touches-shipped-paths.cjs` reused exit code `1` for both the legitimate "no shipped paths" classifier result and Node's default uncaught-throw exit, so any tooling failure was indistinguishable from a normal skip. The script now uses `0` (shipped), `1` (not shipped), `2` (classifier error) with `try`/`catch` + `uncaughtException`/`unhandledRejection` handlers routing all failure paths to exit `2`. **(2)** The workflow's `git checkout -b "$BRANCH" "$BASE_TAG"` overwrote the working tree with the base tag's contents *before* the cherry-pick loop ran the classifier — but base tags predating the classifier's introduction (notably v1.39.0) don't have the file in their tree, so `node scripts/diff-touches-shipped-paths.cjs` would exit non-zero and silently drop every commit, producing an empty hotfix release. The classifier is now staged into `$RUNNER_TEMP` at the top of `Prepare hotfix branch` (before any working-tree-mutating git command), and the loop references that staged copy. The cherry-pick loop snapshots `$PIPESTATUS` into a local array (`PIPE_RC=("${PIPESTATUS[@]}")`) immediately after the classifier pipeline — under bracketed `set +e`/`set -e` — and dispatches via explicit `case`: `0` proceeds, `1` skips into `NON_SHIPPED_SKIPPED`, anything else emits `::error::shipped-paths classifier failed for $SHA (exit N)` and fails the workflow. CodeRabbit on PR #2984 caught a subtler bug in the first iteration: `pipeline \|\| true; RC=${PIPESTATUS[1]}` is broken because `\|\| true` runs `true` as its own one-command pipeline on the failure paths, overwriting `PIPESTATUS` to `(0)` and leaving `${PIPESTATUS[1]}` unset. The array-snapshot form is invariant against this. The same hardening also surfaces `git diff-tree`'s exit code (via `PIPE_RC[0]`); a non-zero diff-tree result now also fails the workflow rather than feeding partial input to the classifier. **(3)** Removed the `Open merge-back PR (hotfix only)` step. The auto-cherry-pick hotfix flow only picks commits already on main (`git cherry HEAD origin/main` outputs the unmerged ones), so by construction every code commit on the hotfix branch is already on main. The only hotfix-branch-only commit is the version-bump chore, which would either no-op against main or rewind main's in-progress version. The step also failed in production with `GitHub Actions is not permitted to create or approve pull requests (createPullRequest)` (org policy) on run [25232968975](https://github.com/gsd-build/get-shit-done/actions/runs/25232968975). The `pull-requests: write` permission previously granted to the release job has been dropped in line with least-privilege. The run-summary line that previously echoed `Merge-back PR opened against main` has been replaced with `No merge-back PR (auto-picked commits are already on main)` so operators reading the summary see an accurate non-action statement (CodeRabbit on PR #2984). Regression covered by `tests/bug-2983-classifier-exit-codes-and-base-tag-staging.test.cjs` (15 assertions across exit-code semantics, classifier staging, error dispatch, PIPESTATUS-snapshot hardening, diff-tree fail-fast, merge-back removal, and run-summary accuracy). (#2983)
|
||||
- **`release-sdk` hotfix only cherry-picks commits that change what actually ships** — the `fix:`/`chore:` filter in `Prepare hotfix branch` was too broad: it picked any commit with that conventional-commit type regardless of whether the diff could affect the published npm package. CI-only fixes (release-sdk.yml itself, hotfix tooling, test-only commits) were getting cherry-picked into hotfix branches even though they cannot change the tarball — and the subset touching `.github/workflows/*` then caused the prepare job's `git push` to be rejected by GitHub because the default `GITHUB_TOKEN` lacks the `workflow` scope, aborting the run. v1.39.1 hit this on PR #2977 (run [25232010071](https://github.com/gsd-build/get-shit-done/actions/runs/25232010071)). The loop now pre-skips any candidate commit whose `git diff-tree` output doesn't intersect the npm tarball's shipped paths (entries in `package.json` `files`, plus `package.json` itself, which `npm pack` always includes). Skipped commits land in a new `NON_SHIPPED_SKIPPED` summary bucket framed as informational — non-shipping commits cannot affect the package, so the skip needs no operator action. The shipped-paths classifier lives in `scripts/diff-touches-shipped-paths.cjs` so its rules (file-OR-directory prefix matching `npm pack` semantics, the always-shipped rule for `package.json`, the lockfile-not-shipped rule) are unit-testable. Regression covered by `tests/bug-2980-hotfix-only-picks-shipping-changes.test.cjs`. (#2980)
|
||||
- **`release-sdk` hotfix workflow fails on real run with `npm error Version not changed`** — the `release` job's `Bump in-tree version (not committed)` step ran `npm version "$VERSION"` without `--allow-same-version`, so it errored on real (non-dry-run) hotfix runs because `prepare` had already committed the bump on the hotfix branch. The release job's checkout `ref` is asymmetric — `BRANCH` (already bumped) on real runs vs `BASE_TAG` (older version) on dry-runs — which is why dry-run never caught the bug. Both `npm version` calls in that step now pass `--allow-same-version`, matching the existing pattern in `release.yml:326`. (#2976)
|
||||
### Added — 1.40.0-rc.1
|
||||
- **Six namespace meta-skills with keyword-tag descriptions** — replace the flat 86-skill
|
||||
listing with two-stage hierarchical routing. Model sees 6 namespace routers
|
||||
(`gsd:workflow`, `gsd:project`, `gsd:review`, `gsd:context`, `gsd:manage`,
|
||||
@@ -37,49 +25,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
in-flight, idle, and progress display. All fields default to undefined so existing
|
||||
STATE.md files keep rendering. Write-side and status-line wiring follow in a later
|
||||
RC. (#2833)
|
||||
|
||||
### Changed — 1.40.0-rc.1
|
||||
- **Hotfix release flow now auto-incorporates fixes from `main` and bundles the SDK** — `hotfix.yml create` auto-cherry-picks every `fix:`/`chore:` commit on `origin/main` not yet shipped (oldest-first; patch-equivalents skipped via `git cherry`; `feat:`/`refactor:` excluded; conflicts halt with the offending SHA; run summary lists every included SHA). `hotfix.yml finalize` adds the `install-smoke` cross-platform gate, bundles `sdk-bundle/gsd-sdk.tgz` inside the CC tarball (parity with `release-sdk.yml`), tightens the `next` dist-tag re-point, and marks the GitHub Release `--latest`. `release-sdk.yml` gains `action: publish | hotfix` plus an `auto_cherry_pick` toggle, with a new `prepare` job that branches `hotfix/X.YY.Z` from the highest existing `vX.YY.*` tag and runs the same cherry-pick logic — idempotent if the branch was pre-prepared via `hotfix.yml`. Hotfix `vX.YY.Z` is now defined as everything in `vX.YY.{Z-1}` plus every `fix:`/`chore:` since that base, so each tag is the cumulative-fix anchor for the next. (#2955)
|
||||
- **Planning workspace seam extracted from `core.cjs` into `planning-workspace.cjs`** — path/workstream/lock behavior now lives in a dedicated module (`planningDir`, `planningPaths`, `planningRoot`, active-workstream routing, `withPlanningLock`). `core.cjs` keeps compatibility re-exports while call-sites migrate to direct imports, improving locality and reducing coupling. (#2900)
|
||||
- **Skill surface consolidated 86 → 59 `commands/gsd/*.md` entries** — four new
|
||||
grouped skills (`capture`, `phase`, `config`, `workspace`) replace clusters of
|
||||
micro-skills. Six existing parents absorb wrap-up and sub-operations as flags:
|
||||
`update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`,
|
||||
`map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Zero
|
||||
functional loss; 31 micro-skills deleted. `autonomous.md` corrected to call
|
||||
`gsd:code-review --fix` (was invoking deleted `gsd:code-review-fix`). (#2790)
|
||||
- **PRs missing `Closes #NNN` are auto-closed** — the `Issue link required` workflow
|
||||
now auto-closes PRs opened without a closing keyword that links a tracking issue,
|
||||
posting a comment that points to the contribution guide. (#2872)
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Stale deleted command references updated across workflow files** — `help.md`, `do.md`, `settings.md`, `discuss-phase.md`, `new-project.md`, `plan-phase.md`, `spike.md`, and `sketch.md` referenced command names removed in #2790; updated to new consolidated equivalents. (#2950)
|
||||
|
||||
### Fixed — 1.40.0-rc.1
|
||||
- **`spike --wrap-up` now dispatches correctly** — `/gsd-spike --wrap-up` was silently no-oping because the flag dispatch wiring was omitted when the micro-skill entry point was absorbed in #2790. (#2948)
|
||||
- **`config-get context_window` returns `200000` when key absent** — querying an unset `context_window` previously exited 1 with "Key not found", surfacing a confusing error in planning logs even though the workflow fallback worked correctly. `cmdConfigGet` now consults a `SCHEMA_DEFAULTS` map and returns the documented default (`200000`, exit 0) for absent schema-defaulted keys; unknown absent keys still error as before. (#2943)
|
||||
- **`gap-analysis` now parses non-`REQ-` requirement IDs and ignores traceability table headers** — `parseRequirements()` no longer hard-codes the `REQ-` prefix and now accepts uppercase prefixed IDs such as `TST-01`, `BACK-07`, and `INSP-04`; markdown table header rows (for example `| REQ-ID | ... |`) are excluded so header tokens are not reported as phantom uncovered requirements. Added regression coverage for mixed-prefix REQUIREMENTS files with traceability tables. (#2897)
|
||||
- **Gemini slash commands namespaced as `/gsd:<cmd>` instead of `/gsd-<cmd>`** —
|
||||
Gemini CLI namespaces commands under `gsd:`, so `/gsd-plan-phase` was unexecutable.
|
||||
Body-text references in commands, agents, banners, and patch-reapply hints are now
|
||||
converted via a roster-checked regex (boundary lookbehind + extension-aware
|
||||
lookahead + roster lookup, defense-in-depth). The roster fail-loud guard prevents
|
||||
silent no-op'ing if `commands/gsd/` is ever missing. (#2768, #2783)
|
||||
- **`SKILL.md` description quoted for Copilot / Antigravity / Trae / CodeBuddy** —
|
||||
descriptions starting with a YAML 1.2 flow indicator (`[BETA]`, `{`, `*`, `&`, `!`,
|
||||
`|`, `>`, `%`, `@`, backtick) crashed gh-copilot's strict YAML loader. Six emission
|
||||
sites now wrap descriptions in `yamlQuote(...)` (= `JSON.stringify`, a valid YAML
|
||||
1.2 double-quoted scalar). (#2876)
|
||||
- **`gsd-tools` invocations use the absolute installed path** — bare `gsd-tools …`
|
||||
calls inside skill bodies relied on PATH resolution that is not guaranteed in every
|
||||
runtime; replaced with the absolute path emitted at install time. (#2851)
|
||||
- **Codex installer preserves trailing newline when stripping legacy hooks** — the
|
||||
legacy-hook strip in the Codex installer ran against files with no terminating
|
||||
newline at EOF and emitted a config that lost the newline, breaking downstream
|
||||
parsers. (#2866)
|
||||
|
||||
### Added
|
||||
- `--minimal` install flag (alias `--core-only`) writes only the main-loop core skills
|
||||
(`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) and
|
||||
zero `gsd-*` subagents. Cuts cold-start system-prompt overhead from ~12k tokens to
|
||||
@@ -108,7 +53,21 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
on every push to main was rejected because submission rate is too high). Includes an
|
||||
optional `dry_run` boolean and the same publish-verification gate as `release.yml`. (#2828)
|
||||
|
||||
### Changed
|
||||
### Enhancement
|
||||
|
||||
- **Test suite for `config-schema.cjs` is now mutation-resistant** — Stryker measured a 4.62% mutation score on `get-shit-done/bin/lib/config-schema.cjs` (6 killed, 124 survived out of 130). Surviving mutants flagged that existing tests were exercising paths but not verifying outputs: a polarity flip (`return true` → `return false`), a predicate swap (`.some` → `.every`), or a guard removal (`if (VALID_CONFIG_KEYS.has(...)) return true;` → unguarded fallthrough) all passed every test. New `tests/bug-2986-config-schema-mutation-killers.test.cjs` adds 95 tests across four suites that target each surviving mutant class: (1) parameterized `isValidConfigKey('${key}') === true` for every member of `VALID_CONFIG_KEYS` (kills the static-key-fast-path mutation), (2) representative dynamic-pattern keys that match exactly one pattern (kills the `.some` → `.every` mutation, with an inline mutual-exclusivity invariant check), (3) `strictEqual` against the literal boolean `true`/`false` instead of `assert.ok` truthy checks (kills polarity-flip mutations), (4) anchor-tightening cases that differ from valid keys by one character beyond the documented shape (kills regex-loosening mutations on `^`, `$`, and character-class boundaries). Tests use the lib's public surface (typed boolean assertions on `isValidConfigKey` return values), no source-grep. (#2986)
|
||||
- **Hotfix release flow now auto-incorporates fixes from `main` and bundles the SDK** — `hotfix.yml create` auto-cherry-picks every `fix:`/`chore:` commit on `origin/main` not yet shipped (oldest-first; patch-equivalents skipped via `git cherry`; `feat:`/`refactor:` excluded; conflicts halt with the offending SHA; run summary lists every included SHA). `hotfix.yml finalize` adds the `install-smoke` cross-platform gate, bundles `sdk-bundle/gsd-sdk.tgz` inside the CC tarball (parity with `release-sdk.yml`), tightens the `next` dist-tag re-point, and marks the GitHub Release `--latest`. `release-sdk.yml` gains `action: publish | hotfix` plus an `auto_cherry_pick` toggle, with a new `prepare` job that branches `hotfix/X.YY.Z` from the highest existing `vX.YY.*` tag and runs the same cherry-pick logic — idempotent if the branch was pre-prepared via `hotfix.yml`. Hotfix `vX.YY.Z` is now defined as everything in `vX.YY.{Z-1}` plus every `fix:`/`chore:` since that base, so each tag is the cumulative-fix anchor for the next. (#2955)
|
||||
- **Planning workspace seam extracted from `core.cjs` into `planning-workspace.cjs`** — path/workstream/lock behavior now lives in a dedicated module (`planningDir`, `planningPaths`, `planningRoot`, active-workstream routing, `withPlanningLock`). `core.cjs` keeps compatibility re-exports while call-sites migrate to direct imports, improving locality and reducing coupling. (#2900)
|
||||
- **Skill surface consolidated 86 → 59 `commands/gsd/*.md` entries** — four new
|
||||
grouped skills (`capture`, `phase`, `config`, `workspace`) replace clusters of
|
||||
micro-skills. Six existing parents absorb wrap-up and sub-operations as flags:
|
||||
`update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`,
|
||||
`map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Zero
|
||||
functional loss; 31 micro-skills deleted. `autonomous.md` corrected to call
|
||||
`gsd:code-review --fix` (was invoking deleted `gsd:code-review-fix`). (#2790)
|
||||
- **PRs missing `Closes #NNN` are auto-closed** — the `Issue link required` workflow
|
||||
now auto-closes PRs opened without a closing keyword that links a tracking issue,
|
||||
posting a comment that points to the contribution guide. (#2872)
|
||||
- **Canary release workflow now publishes from `dev` branch only** — `.github/workflows/canary.yml`
|
||||
swaps its four publish-step guards from `refs/heads/main` to `refs/heads/dev`. Aligns the
|
||||
workflow with the new branch→dist-tag policy (`dev` → `@canary`, `main` → `@next`/`@latest`).
|
||||
@@ -122,8 +81,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
- **`scripts/lint-descriptions.cjs` added** — CI lint gate that fails if any
|
||||
`commands/gsd/*.md` description exceeds 100 chars. Run via `npm run lint:descriptions`.
|
||||
(#2789)
|
||||
|
||||
### Changed
|
||||
- **Skill surface consolidated from 86 → 59 `commands/gsd/*.md` entries** — four new
|
||||
grouped skills replace clusters of micro-skills: `capture` (add-todo, note, add-backlog,
|
||||
plant-seed, check-todos), `phase` (add-phase, insert-phase, remove-phase, edit-phase),
|
||||
@@ -134,8 +91,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
`progress --do/--next`. Zero functional loss. (#2790)
|
||||
- **`autonomous.md` corrected** — was invoking deleted `gsd:code-review-fix`; now calls
|
||||
`gsd:code-review --fix`. (#2790)
|
||||
|
||||
### Removed
|
||||
- **31 micro-skills deleted** — absorbed into consolidated parents or removed outright:
|
||||
add-todo, note, add-backlog, plant-seed, check-todos, add-phase, insert-phase,
|
||||
remove-phase, edit-phase, settings-advanced, settings-integrations, set-profile,
|
||||
@@ -144,8 +99,39 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
join-discord, research-phase, session-report, from-gsd2, analyze-dependencies,
|
||||
list-phase-assumptions, plan-milestone-gaps. All functionality preserved via flags on
|
||||
consolidated skills. (#2790)
|
||||
- **`discuss-phase` lazy file loading** — entry-point `@file` directives replaced with
|
||||
on-demand `Read()` calls gated behind mode routing. Tokens loaded at skill entry drop
|
||||
from ~13k to near zero; only the branch actually invoked is loaded. (#2606)
|
||||
|
||||
### Fixed
|
||||
### Fix
|
||||
|
||||
- **`gsd-pristine/` is now populated by the installer when local patches are detected** — `saveLocalPatches` declared a `pristineDir` variable and JSDoc'd "saves pristine copies (from manifest) to gsd-pristine/ to enable three-way merge during reapply-patches", but no code ever wrote to that directory. Effect: the `/gsd-reapply-patches` Step 5 verifier (#2972) silently degraded to its over-broad fallback heuristic ("every significant backup line"), exactly the silent-success-on-lost-content failure mode #2969 was designed to prevent. Fix: new `populatePristineDir({ packageSrc, pristineDir, modified, runtime, pathPrefix, isGlobal })` helper runs the install transform pipeline (`copyWithPathReplacement`) into a tmp staging dir, then copies out only the modified-file paths into `gsd-pristine/`. `saveLocalPatches` now accepts a `pristineCtx` and calls the helper when local patches are detected; the install entry point passes the package source root, runtime, pathPrefix, and isGlobal so transforms produce byte-identical output to what `copyWithPathReplacement` would have written under normal install. Soft-fails on transform errors (logs a warning, continues with empty pristine — no worse than pre-fix behavior). Pristine reflects the about-to-install version's content, which is what the verifier needs as the "what would survive without the user's modifications" baseline. Regression covered by `tests/bug-2998-pristine-dir-populated.test.cjs` (6 tests across two suites): asserts the helper is exported, returns 0 for empty modified list, writes one pristine file per source-existing path, skips ghost paths without corrupting pristine, and produces deterministic output (two runs with same inputs yield byte-identical pristine — the property `pristine_hashes` in `backup-meta.json` depends on). (#2998)
|
||||
- **`release-sdk` hotfix re-run no longer fails at `Dry-run publish validation` when the version is already on npm** — the `Detect prior publish (reconciliation mode)` step sets `skip_publish=true` when the package version is already on the registry, and the actual publish step honors that gate. The `Dry-run publish validation` step was missing the same guard, so any operator re-run of an already-published hotfix (the typical recovery path when later steps fail mid-flight) hit `npm publish --dry-run` first and got `npm error You cannot publish over the previously published versions: X.Y.Z` — `npm publish --dry-run` contacts the registry and rejects existing-version targets even though it doesn't actually publish. The dry-run validation step is now gated on the same `steps.prior_publish.outputs.skip_publish != 'true'` condition as the publish step. The rehearsal still runs on first publishes (where it has value); it skips only in the specific reconciliation case where the publish itself would be skipped. Trigger run: [25233855236](https://github.com/gsd-build/get-shit-done/actions/runs/25233855236/job/73995605643). Regression covered by `tests/bug-2987-dry-run-validation-skip-on-reconciliation.test.cjs`. (#2987)
|
||||
- **`release-sdk` hotfix flow hardened against silent classifier failures, missing-classifier-at-base-tag, and a vestigial merge-back PR step** — three issues surfaced by CodeRabbit's post-merge review of #2981 plus a production failure on the v1.39.1 release run. **(1)** `scripts/diff-touches-shipped-paths.cjs` reused exit code `1` for both the legitimate "no shipped paths" classifier result and Node's default uncaught-throw exit, so any tooling failure was indistinguishable from a normal skip. The script now uses `0` (shipped), `1` (not shipped), `2` (classifier error) with `try`/`catch` + `uncaughtException`/`unhandledRejection` handlers routing all failure paths to exit `2`. **(2)** The workflow's `git checkout -b "$BRANCH" "$BASE_TAG"` overwrote the working tree with the base tag's contents *before* the cherry-pick loop ran the classifier — but base tags predating the classifier's introduction (notably v1.39.0) don't have the file in their tree, so `node scripts/diff-touches-shipped-paths.cjs` would exit non-zero and silently drop every commit, producing an empty hotfix release. The classifier is now staged into `$RUNNER_TEMP` at the top of `Prepare hotfix branch` (before any working-tree-mutating git command), and the loop references that staged copy. The cherry-pick loop snapshots `$PIPESTATUS` into a local array (`PIPE_RC=("${PIPESTATUS[@]}")`) immediately after the classifier pipeline — under bracketed `set +e`/`set -e` — and dispatches via explicit `case`: `0` proceeds, `1` skips into `NON_SHIPPED_SKIPPED`, anything else emits `::error::shipped-paths classifier failed for $SHA (exit N)` and fails the workflow. CodeRabbit on PR #2984 caught a subtler bug in the first iteration: `pipeline \|\| true; RC=${PIPESTATUS[1]}` is broken because `\|\| true` runs `true` as its own one-command pipeline on the failure paths, overwriting `PIPESTATUS` to `(0)` and leaving `${PIPESTATUS[1]}` unset. The array-snapshot form is invariant against this. The same hardening also surfaces `git diff-tree`'s exit code (via `PIPE_RC[0]`); a non-zero diff-tree result now also fails the workflow rather than feeding partial input to the classifier. **(3)** Removed the `Open merge-back PR (hotfix only)` step. The auto-cherry-pick hotfix flow only picks commits already on main (`git cherry HEAD origin/main` outputs the unmerged ones), so by construction every code commit on the hotfix branch is already on main. The only hotfix-branch-only commit is the version-bump chore, which would either no-op against main or rewind main's in-progress version. The step also failed in production with `GitHub Actions is not permitted to create or approve pull requests (createPullRequest)` (org policy) on run [25232968975](https://github.com/gsd-build/get-shit-done/actions/runs/25232968975). The `pull-requests: write` permission previously granted to the release job has been dropped in line with least-privilege. The run-summary line that previously echoed `Merge-back PR opened against main` has been replaced with `No merge-back PR (auto-picked commits are already on main)` so operators reading the summary see an accurate non-action statement (CodeRabbit on PR #2984). Regression covered by `tests/bug-2983-classifier-exit-codes-and-base-tag-staging.test.cjs` (15 assertions across exit-code semantics, classifier staging, error dispatch, PIPESTATUS-snapshot hardening, diff-tree fail-fast, merge-back removal, and run-summary accuracy). (#2983)
|
||||
- **`release-sdk` hotfix only cherry-picks commits that change what actually ships** — the `fix:`/`chore:` filter in `Prepare hotfix branch` was too broad: it picked any commit with that conventional-commit type regardless of whether the diff could affect the published npm package. CI-only fixes (release-sdk.yml itself, hotfix tooling, test-only commits) were getting cherry-picked into hotfix branches even though they cannot change the tarball — and the subset touching `.github/workflows/*` then caused the prepare job's `git push` to be rejected by GitHub because the default `GITHUB_TOKEN` lacks the `workflow` scope, aborting the run. v1.39.1 hit this on PR #2977 (run [25232010071](https://github.com/gsd-build/get-shit-done/actions/runs/25232010071)). The loop now pre-skips any candidate commit whose `git diff-tree` output doesn't intersect the npm tarball's shipped paths (entries in `package.json` `files`, plus `package.json` itself, which `npm pack` always includes). Skipped commits land in a new `NON_SHIPPED_SKIPPED` summary bucket framed as informational — non-shipping commits cannot affect the package, so the skip needs no operator action. The shipped-paths classifier lives in `scripts/diff-touches-shipped-paths.cjs` so its rules (file-OR-directory prefix matching `npm pack` semantics, the always-shipped rule for `package.json`, the lockfile-not-shipped rule) are unit-testable. Regression covered by `tests/bug-2980-hotfix-only-picks-shipping-changes.test.cjs`. (#2980)
|
||||
- **`release-sdk` hotfix workflow fails on real run with `npm error Version not changed`** — the `release` job's `Bump in-tree version (not committed)` step ran `npm version "$VERSION"` without `--allow-same-version`, so it errored on real (non-dry-run) hotfix runs because `prepare` had already committed the bump on the hotfix branch. The release job's checkout `ref` is asymmetric — `BRANCH` (already bumped) on real runs vs `BASE_TAG` (older version) on dry-runs — which is why dry-run never caught the bug. Both `npm version` calls in that step now pass `--allow-same-version`, matching the existing pattern in `release.yml:326`. (#2976)
|
||||
- **Stale deleted command references updated across workflow files** — `help.md`, `do.md`, `settings.md`, `discuss-phase.md`, `new-project.md`, `plan-phase.md`, `spike.md`, and `sketch.md` referenced command names removed in #2790; updated to new consolidated equivalents. (#2950)
|
||||
- **`spike --wrap-up` now dispatches correctly** — `/gsd-spike --wrap-up` was silently no-oping because the flag dispatch wiring was omitted when the micro-skill entry point was absorbed in #2790. (#2948)
|
||||
- **`config-get context_window` returns `200000` when key absent** — querying an unset `context_window` previously exited 1 with "Key not found", surfacing a confusing error in planning logs even though the workflow fallback worked correctly. `cmdConfigGet` now consults a `SCHEMA_DEFAULTS` map and returns the documented default (`200000`, exit 0) for absent schema-defaulted keys; unknown absent keys still error as before. (#2943)
|
||||
- **`gap-analysis` now parses non-`REQ-` requirement IDs and ignores traceability table headers** — `parseRequirements()` no longer hard-codes the `REQ-` prefix and now accepts uppercase prefixed IDs such as `TST-01`, `BACK-07`, and `INSP-04`; markdown table header rows (for example `| REQ-ID | ... |`) are excluded so header tokens are not reported as phantom uncovered requirements. Added regression coverage for mixed-prefix REQUIREMENTS files with traceability tables. (#2897)
|
||||
- **Gemini slash commands namespaced as `/gsd:<cmd>` instead of `/gsd-<cmd>`** —
|
||||
Gemini CLI namespaces commands under `gsd:`, so `/gsd-plan-phase` was unexecutable.
|
||||
Body-text references in commands, agents, banners, and patch-reapply hints are now
|
||||
converted via a roster-checked regex (boundary lookbehind + extension-aware
|
||||
lookahead + roster lookup, defense-in-depth). The roster fail-loud guard prevents
|
||||
silent no-op'ing if `commands/gsd/` is ever missing. (#2768, #2783)
|
||||
- **`SKILL.md` description quoted for Copilot / Antigravity / Trae / CodeBuddy** —
|
||||
descriptions starting with a YAML 1.2 flow indicator (`[BETA]`, `{`, `*`, `&`, `!`,
|
||||
`|`, `>`, `%`, `@`, backtick) crashed gh-copilot's strict YAML loader. Six emission
|
||||
sites now wrap descriptions in `yamlQuote(...)` (= `JSON.stringify`, a valid YAML
|
||||
1.2 double-quoted scalar). (#2876)
|
||||
- **`gsd-tools` invocations use the absolute installed path** — bare `gsd-tools …`
|
||||
calls inside skill bodies relied on PATH resolution that is not guaranteed in every
|
||||
runtime; replaced with the absolute path emitted at install time. (#2851)
|
||||
- **Codex installer preserves trailing newline when stripping legacy hooks** — the
|
||||
legacy-hook strip in the Codex installer ran against files with no terminating
|
||||
newline at EOF and emitted a config that lost the newline, breaking downstream
|
||||
parsers. (#2866)
|
||||
- **GSD slash command namespace drift cleaned up across docs, workflows, and autocomplete** — remaining active `/gsd:<cmd>` references now use canonical `/gsd-<cmd>`, escaped workflow `Skill(skill=\"gsd:...\")` prompts now use hyphenated skill names, `scripts/fix-slash-commands.cjs` rewrites retired colon syntax to hyphen syntax, and the extract-learnings command file now uses `extract-learnings.md` so generated Claude/Qwen skill autocomplete exposes `gsd-extract-learnings` instead of `gsd-extract_learnings`. (#2855)
|
||||
- **`extractCurrentMilestone` no longer truncates ROADMAP.md at heading-like lines inside fenced code blocks** — the milestone-end search now scans line-by-line while tracking ` ``` ` / `~~~` fence state, so a line like `# Ops runbook (v1.0 compat)` inside a code block no longer acts as a milestone boundary. Previously, any phase defined after such a block was invisible to `roadmap analyze`, `roadmap get-phase`, `/gsd-autonomous`, and all phase-number commands. (#2787)
|
||||
- **Codex install no longer corrupts existing `~/.codex/config.toml`** — the installer
|
||||
@@ -321,10 +307,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
pre-existing sentinel force-removes the orphan worktree before starting fresh, making
|
||||
the agent self-healing across crashes. (#2839)
|
||||
|
||||
### Performance
|
||||
- **`discuss-phase` lazy file loading** — entry-point `@file` directives replaced with
|
||||
on-demand `Read()` calls gated behind mode routing. Tokens loaded at skill entry drop
|
||||
from ~13k to near zero; only the branch actually invoked is loaded. (#2606)
|
||||
|
||||
## [1.39.1] - 2026-05-01
|
||||
|
||||
|
||||
@@ -111,14 +111,25 @@ Multiple layers prevent common failure modes:
|
||||
|
||||
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`)
|
||||
- **Claude Code:** Custom slash commands (hyphen form, `/gsd-command-name`)
|
||||
- **OpenCode / Kilo:** Slash commands (hyphen form, `/gsd-command-name`)
|
||||
- **Codex:** Skills (`$gsd-command-name`)
|
||||
- **Copilot:** Slash commands (`/gsd-command-name`)
|
||||
- **Copilot:** Slash commands (hyphen form, `/gsd-command-name`)
|
||||
- **Gemini CLI:** Slash commands under the `gsd:` namespace (colon form, `/gsd:command-name`) — Gemini namespaces all custom commands under their plugin id, so the install path rewrites every body-text reference to colon form
|
||||
- **Antigravity:** Skills
|
||||
|
||||
**Total commands:** see [`docs/INVENTORY.md`](INVENTORY.md#commands) for the authoritative count and full roster.
|
||||
|
||||
#### Two-stage hierarchical routing (v1.40, [#2792](https://github.com/gsd-build/get-shit-done/issues/2792))
|
||||
|
||||
To keep the eager skill-listing token cost low, v1.40 introduces six namespace **meta-skills** (`gsd-workflow`, `gsd-project`, `gsd-review`, `gsd-context`, `gsd-manage`, `gsd-ideate` — sourced from `commands/gsd/ns-*.md`, but the invocable `name:` is the bare form shown here) layered above the concrete sub-skills. The model sees 6 namespace routers (~120 tokens) instead of a flat 86-skill listing (~2,150 tokens), selects a namespace, then routes to the concrete sub-skill via a routing table embedded in the namespace router's body. Namespace skills are **additive** — every concrete command is still directly invocable.
|
||||
|
||||
The router descriptions use pipe-separated keyword tags (≤ 60 chars) per the Tool Attention research showing keyword-dense tags outperform prose for routing at ~40 % the token cost.
|
||||
|
||||
#### MCP token-budget interaction
|
||||
|
||||
The eager skill listing is one of two recurring per-turn token costs. The other is the MCP tool schema injected by every enabled MCP server in `.claude/settings.json`. Heavyweight MCP servers (browser/playwright, Mac-tools, Windows-tools) can each cost 20 k+ tokens per turn — often dwarfing what `model_profile` tuning saves. The toggle lives in the Claude Code harness (`enabledMcpjsonServers` / `disabledMcpjsonServers` in `.claude/settings.json`) and is **not** a GSD concern. Together, the two-stage routing layer (#2792) and disciplined MCP enablement are the largest cost levers per turn. See [`docs/USER-GUIDE.md`](USER-GUIDE.md) and `references/context-budget.md` for the audit checklist.
|
||||
|
||||
### Workflows (`get-shit-done/workflows/*.md`)
|
||||
|
||||
Orchestration logic that commands reference. Contains the step-by-step process including:
|
||||
|
||||
@@ -250,8 +250,15 @@ node gsd-tools.cjs validate consistency
|
||||
|
||||
# Check .planning/ integrity, optionally repair
|
||||
node gsd-tools.cjs validate health [--repair]
|
||||
|
||||
# Probe context-window utilization for status-line / hook callers (v1.40.0)
|
||||
node gsd-tools.cjs validate context
|
||||
```
|
||||
|
||||
`validate context` emits a structured envelope with `utilization`, `status`
|
||||
(`ok` / `warn` / `critical` at the 60 % / 70 % thresholds), and a
|
||||
`suggestion` string. The same data backs `/gsd-health --context`.
|
||||
|
||||
---
|
||||
|
||||
## Template Commands
|
||||
|
||||
@@ -6,10 +6,29 @@
|
||||
|
||||
## Command Syntax
|
||||
|
||||
- **Claude Code / Gemini / Copilot:** `/gsd-command-name [args]`
|
||||
- **OpenCode / Kilo:** `/gsd-command-name [args]`
|
||||
- **Claude Code / Copilot / OpenCode / Kilo:** `/gsd-command-name [args]` (hyphen form)
|
||||
- **Gemini CLI:** `/gsd:command-name [args]` (colon form — Gemini namespaces commands under `gsd:`)
|
||||
- **Codex:** `$gsd-command-name [args]`
|
||||
|
||||
The hyphen and colon forms are *runtime-specific spellings of the same command*. Whichever runtime you're on, the installer writes the correct form into your runtime's command directory.
|
||||
|
||||
---
|
||||
|
||||
## Namespace Meta-Skills
|
||||
|
||||
Six namespace routers ship as the first-stage entry points in v1.40. They keep the eager skill-listing token cost low (~120 tokens for 6 routers vs ~2,150 for a flat 86-skill listing) while the full surface remains directly invocable. The model selects a namespace, then routes to the concrete sub-skill. See [#2792](https://github.com/gsd-build/get-shit-done/issues/2792).
|
||||
|
||||
| Command | Routes to |
|
||||
|---------|-----------|
|
||||
| `/gsd-ns-workflow` | Phase pipeline — discuss / plan / execute / verify / phase / progress |
|
||||
| `/gsd-ns-project` | Project lifecycle — milestones, audits, summary |
|
||||
| `/gsd-ns-review` | Quality gates — code review, debug, audit, security, eval, ui |
|
||||
| `/gsd-ns-context` | Codebase intelligence — map, graphify, docs, learnings |
|
||||
| `/gsd-ns-manage` | Management — config, workspace, workstreams, thread, update, ship, inbox |
|
||||
| `/gsd-ns-ideate` | Exploration & capture — explore, sketch, spike, spec, capture |
|
||||
|
||||
The namespace skills are **additive** — every existing concrete command (e.g. `/gsd-plan-phase`, `/gsd-code-review --fix`) is still invocable directly.
|
||||
|
||||
---
|
||||
|
||||
## Core Workflow Commands
|
||||
@@ -699,15 +718,19 @@ Generate a developer behavioral profile from Claude Code session analysis across
|
||||
|
||||
### `/gsd-health`
|
||||
|
||||
Validate `.planning/` directory integrity.
|
||||
Validate `.planning/` directory integrity. With `--context`, probes the
|
||||
context-window utilization guard against the 60 % / 70 % thresholds (added
|
||||
v1.40.0, [#2792](https://github.com/gsd-build/get-shit-done/issues/2792)).
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--repair` | Auto-fix recoverable issues |
|
||||
| `--context` | Probe context-window utilization; warns at 60 %, critical at 70 % |
|
||||
|
||||
```bash
|
||||
/gsd-health # Check integrity
|
||||
/gsd-health --repair # Check and fix
|
||||
/gsd-health --context # Context-utilization triage
|
||||
```
|
||||
|
||||
### `/gsd-cleanup`
|
||||
|
||||
@@ -126,7 +126,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
|
||||
| `dynamic_routing.max_escalations` | integer | `0`, `1`, `2`, … | `1` | Hard cap on retries per agent invocation. Beyond the cap the resolver returns the cap-tier model. Added in v1.40 |
|
||||
| `project_code` | string | any short string | (none) | Prefix for phase directory names (e.g., `"ABC"` produces `ABC-01-setup/`). Added in v1.31 |
|
||||
| `response_language` | string | language code | (none) | Language for agent responses (e.g., `"pt"`, `"ko"`, `"ja"`). Propagates to all spawned agents for cross-phase language consistency. Added in v1.32 |
|
||||
| `context_window` | number | any integer | `200000` | Context window size in tokens. Set `1000000` for 1M-context models (e.g., `claude-opus-4-7[1m]`). Values `>= 500000` enable adaptive context enrichment (full-body reads of prior SUMMARY.md, deeper anti-pattern reads). Configured via `/gsd-settings-advanced`. |
|
||||
| `context_window` | number | any integer | `200000` | Context window size in tokens. Set `1000000` for 1M-context models (e.g., `claude-opus-4-7[1m]`). Values `>= 500000` enable adaptive context enrichment (full-body reads of prior SUMMARY.md, deeper anti-pattern reads). Configured via `/gsd-config --advanced`. |
|
||||
| `context_profile` | string | `dev`, `research`, `review` | (none) | Execution context preset that applies a pre-configured bundle of mode, model, and workflow settings for the current type of work. Added in v1.34 |
|
||||
| `claude_md_path` | string | any file path | `./CLAUDE.md` | Custom output path for the generated CLAUDE.md file. Useful for monorepos or projects that need CLAUDE.md in a non-root location. Defaults to `./CLAUDE.md` at the project root. Added in v1.36 |
|
||||
| `claude_md_assembly.mode` | enum | `embed`, `link` | `embed` | Controls how managed sections are written into CLAUDE.md. `embed` (default) inlines content between GSD markers. `link` writes `@.planning/<source-path>` instead — Claude Code expands the reference at runtime, reducing CLAUDE.md size by ~65% on typical projects. `link` only applies to sections that have a real source file; `workflow` and fallback sections always embed. Per-block overrides: `claude_md_assembly.blocks.<section>` (e.g. `claude_md_assembly.blocks.architecture: link`). Added in v1.38 |
|
||||
@@ -143,7 +143,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
|
||||
|
||||
## Integration Settings
|
||||
|
||||
Configured interactively via [`/gsd-settings-integrations`](COMMANDS.md#gsd-settings-integrations). These are *connectivity* settings — API keys and cross-tool routing — and are intentionally kept separate from `/gsd-settings` (workflow toggles).
|
||||
Configured interactively via [`/gsd-config --integrations`](COMMANDS.md#gsd-config). These are *connectivity* settings — API keys and cross-tool routing — and are intentionally kept separate from `/gsd-settings` (workflow toggles).
|
||||
|
||||
### Search API keys
|
||||
|
||||
@@ -172,7 +172,7 @@ The `<cli>` slug is validated against `[a-zA-Z0-9_-]+`. Empty or path-containing
|
||||
|
||||
### Agent-skill injection (dynamic)
|
||||
|
||||
`agent_skills.<agent-type>` extends the `agent_skills` map documented below. Slug is validated against `[a-zA-Z0-9_-]+` — no path separators, no whitespace, no shell metacharacters. Configured interactively via `/gsd-settings-integrations`.
|
||||
`agent_skills.<agent-type>` extends the `agent_skills` map documented below. Slug is validated against `[a-zA-Z0-9_-]+` — no path separators, no whitespace, no shell metacharacters. Configured interactively via `/gsd-config --integrations`.
|
||||
|
||||
---
|
||||
|
||||
@@ -392,6 +392,21 @@ The `features.*` namespace is a dynamic key pattern — new feature flags can be
|
||||
|
||||
---
|
||||
|
||||
## STATE.md Frontmatter (Phase Lifecycle)
|
||||
|
||||
`STATE.md` carries YAML frontmatter that the status-line hook reads on every render. v1.40 adds four optional phase-lifecycle fields read by `parseStateMd()` and rendered by `formatGsdState()`:
|
||||
|
||||
| Field | Type | Purpose |
|
||||
|-------|------|---------|
|
||||
| `active_phase` | string (e.g. `"4.5"`) | Phase number when an orchestrator command is in flight |
|
||||
| `next_action` | string | Recommended next command when idle (`discuss-phase` / `plan-phase` / `execute-phase` / `verify-phase`) |
|
||||
| `next_phases` | YAML flow array | Phases the `next_action` applies to (e.g. `["4.5"]`) |
|
||||
| `progress` | block | Nested `total_phases` / `completed_phases` / `percent` for the milestone progress bar |
|
||||
|
||||
All four fields are **optional and additive** — STATE.md files without them keep rendering exactly as in v1.38.x. See [`STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference, parser constraints, and rendering scenes.
|
||||
|
||||
---
|
||||
|
||||
## Git Branching
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
|
||||
@@ -144,6 +144,11 @@
|
||||
- [Agent Size-Budget Enforcement](#119-agent-size-budget-enforcement)
|
||||
- [Shared Boilerplate Extraction](#120-shared-boilerplate-extraction)
|
||||
- [Knowledge Graph Integration](#121-knowledge-graph-integration)
|
||||
- [v1.40.0 Features](#v1400-features)
|
||||
- [Skill Surface Consolidation](#122-skill-surface-consolidation)
|
||||
- [Namespace Meta-Skills (Two-Stage Routing)](#123-namespace-meta-skills-two-stage-routing)
|
||||
- [Context-Window Utilization Guard](#124-context-window-utilization-guard)
|
||||
- [Phase-Lifecycle Status-Line Read-Side](#125-phase-lifecycle-status-line-read-side)
|
||||
- [v1.32 Features](#v132-features)
|
||||
- [STATE.md Consistency Gates](#69-statemd-consistency-gates)
|
||||
- [Autonomous `--to N` Flag](#70-autonomous---to-n-flag)
|
||||
@@ -2612,3 +2617,83 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style
|
||||
|
||||
**Configuration:** `graphify.enabled`, `graphify.build_timeout`
|
||||
**Reference files:** `commands/gsd/graphify.md`, `bin/lib/graphify.cjs`
|
||||
|
||||
---
|
||||
|
||||
## v1.40.0 Features
|
||||
|
||||
### 122. Skill Surface Consolidation
|
||||
|
||||
**Purpose:** Cut the eager skill-listing overhead by folding 31 micro-skills into 4 new grouped parents and 6 existing parents that absorb sub-operations as flags. Zero functional loss — every removed micro-skill's behavior survives via a flag on a consolidated parent. After consolidation, `commands/gsd/*.md` ships 59 sub-skills (plus 6 namespace meta-skills, see #123).
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CONSOLIDATE-01: Four new grouped skills replace clusters of micro-skills:
|
||||
- `/gsd-capture` — folds add-todo (default), note (`--note`), add-backlog (`--backlog`), plant-seed (`--seed`), check-todos (`--list`)
|
||||
- `/gsd-phase` — folds add-phase (default), insert-phase (`--insert`), remove-phase (`--remove`), edit-phase (`--edit`)
|
||||
- `/gsd-config` — folds settings-advanced (`--advanced`), settings-integrations (`--integrations`), set-profile (`--profile`)
|
||||
- `/gsd-workspace` — folds new-workspace (`--new`), list-workspaces (`--list`), remove-workspace (`--remove`)
|
||||
- REQ-CONSOLIDATE-02: Six existing parents absorb wrap-up / sub-operations as flags: `/gsd-update --sync`, `/gsd-update --reapply`, `/gsd-sketch --wrap-up`, `/gsd-spike --wrap-up`, `/gsd-map-codebase --fast`, `/gsd-map-codebase --query`, `/gsd-code-review --fix`, `/gsd-progress --do`, `/gsd-progress --next`.
|
||||
- REQ-CONSOLIDATE-03: Deleted micro-skill slash forms (the bare `gsd-add-todo`, `gsd-add-backlog`, `gsd-plant-seed`, `gsd-check-todos`, `gsd-add-phase`, `gsd-insert-phase`, `gsd-remove-phase`, `gsd-edit-phase`, `gsd-new-workspace`, `gsd-list-workspaces`, `gsd-remove-workspace`, `gsd-settings-advanced`, `gsd-settings-integrations`, `gsd-set-profile`, `gsd-sketch-wrap-up`, `gsd-spike-wrap-up`, `gsd-reapply-patches`, `gsd-code-review-fix`, …) MUST resolve to "Unknown command" — no shadow stubs.
|
||||
- REQ-CONSOLIDATE-04: `autonomous.md` invokes `/gsd-code-review --fix` (was previously calling the deleted `gsd-code-review-fix`).
|
||||
|
||||
**Reference issue:** [#2790](https://github.com/gsd-build/get-shit-done/issues/2790)
|
||||
|
||||
---
|
||||
|
||||
### 123. Namespace Meta-Skills (Two-Stage Routing)
|
||||
|
||||
**Purpose:** Replace the flat eager skill listing with a two-stage hierarchical routing layer. The model sees 6 namespace routers instead of 86 entries, selects a namespace, then routes to the sub-skill. Descriptions use pipe-separated keyword tags (≤ 60 chars) for routing density.
|
||||
|
||||
**Commands:**
|
||||
- `/gsd-ns-workflow` — phase pipeline router (discuss / plan / execute / verify / phase / progress)
|
||||
- `/gsd-ns-project` — project lifecycle (milestones, audits, summary)
|
||||
- `/gsd-ns-review` — quality gates (code review, debug, audit, security, eval, ui)
|
||||
- `/gsd-ns-context` — codebase intelligence (map, graphify, docs, learnings)
|
||||
- `/gsd-ns-manage` — config / workspace / workstreams / thread / update / ship / inbox
|
||||
- `/gsd-ns-ideate` — exploration & capture (explore, sketch, spike, spec, capture)
|
||||
|
||||
**Token cost:**
|
||||
|
||||
| | Entries | Approx tokens |
|
||||
|---|---|---|
|
||||
| Pre-1.40 full install | 86 | ~2,150 |
|
||||
| Namespace meta-skills | 6 | ~120 |
|
||||
|
||||
**Requirements:**
|
||||
- REQ-NS-01: Six `commands/gsd/ns-*.md` namespace routers ship with pipe-separated keyword-tag descriptions (≤ 60 chars).
|
||||
- REQ-NS-02: Existing sub-skills are unchanged and still invocable directly — namespace skills are additive, not a replacement for direct slash forms.
|
||||
- REQ-NS-03: The body of each namespace router contains a routing table that maps user intent to the correct concrete sub-skill on the post-#2790 consolidated surface.
|
||||
|
||||
**Reference issue:** [#2792](https://github.com/gsd-build/get-shit-done/issues/2792)
|
||||
|
||||
---
|
||||
|
||||
### 124. Context-Window Utilization Guard
|
||||
|
||||
**Command:** `/gsd-health --context`
|
||||
|
||||
**Purpose:** Quality guard against context-window saturation. Two thresholds: 60 % utilization warns ("consider `/gsd-thread`"), 70 % is critical ("reasoning quality may degrade"; matches the fracture-point per recent context-attention research).
|
||||
|
||||
**Requirements:**
|
||||
- REQ-CTX-GUARD-01: `/gsd-health --context` prints a structured status line with current utilization, threshold tier (`ok` / `warn` / `critical`), and a remediation suggestion.
|
||||
- REQ-CTX-GUARD-02: The same triage is exposed as `gsd-sdk query validate.context --tokens-used <int> --context-window <int>` — a structured envelope for status-line and hook callers (#125). Both flags are required; the handler returns the same `{ percent, state }` envelope as the pure classifier in REQ-CTX-GUARD-03.
|
||||
- REQ-CTX-GUARD-03: The classifier (`bin/lib/context-utilization.cjs`) is pure: input `(tokensUsed, contextWindow)`, output `{ percent, state }`. Easy to unit-test, easy to reuse from any caller.
|
||||
|
||||
**Reference issue:** [#2792](https://github.com/gsd-build/get-shit-done/issues/2792)
|
||||
|
||||
---
|
||||
|
||||
### 125. Phase-Lifecycle Status-Line Read-Side
|
||||
|
||||
**Purpose:** Surface phase orchestration state on the status-line. `parseStateMd()` reads four new STATE.md frontmatter fields and `formatGsdState()` renders in-flight, idle, and progress scenes. Write-side wiring follows in a later RC.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-LIFECYCLE-01: `parseStateMd()` reads four optional fields:
|
||||
- `active_phase` — phase number when an orchestrator is in flight
|
||||
- `next_action` — recommended next command when idle
|
||||
- `next_phases` — YAML flow array of next phase numbers
|
||||
- `progress` — nested `total_phases` / `completed_phases` / `percent` block
|
||||
- REQ-LIFECYCLE-02: `formatGsdState()` checks the lifecycle fields in priority order and emits the first matching scene (Phase active → Idle next-recommended → Milestone complete → Default fallback).
|
||||
- REQ-LIFECYCLE-03: All four fields default to undefined; existing STATE.md files render byte-for-byte identically.
|
||||
|
||||
**Reference issue:** [#2833](https://github.com/gsd-build/get-shit-done/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference and rendering rules.
|
||||
|
||||
@@ -168,7 +168,7 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
|
||||
|
||||
| Workflow | Role | Invoked by |
|
||||
|----------|------|------------|
|
||||
| `add-phase.md` | Add a new integer phase to the end of the current milestone in the roadmap. | `/gsd-add-phase` |
|
||||
| `add-phase.md` | Add a new integer phase to the end of the current milestone in the roadmap. | `/gsd-phase` (default) |
|
||||
| `add-tests.md` | Generate unit and E2E tests for a completed phase based on its artifacts. | `/gsd-add-tests` |
|
||||
| `add-todo.md` | Capture an idea or task that surfaces during a session as a structured todo. | `/gsd-capture` (default), `/gsd-capture --backlog` |
|
||||
| `ai-integration-phase.md` | Orchestrate framework selection → AI research → domain research → eval planning into AI-SPEC.md. | `/gsd-ai-integration-phase` |
|
||||
@@ -203,9 +203,9 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
|
||||
| `import.md` | Ingest external plans with conflict detection against existing project decisions. | `/gsd-import` |
|
||||
| `inbox.md` | Triage open GitHub issues and PRs against project contribution templates. | `/gsd-inbox` |
|
||||
| `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-insert-phase` |
|
||||
| `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-list-phase-assumptions` |
|
||||
| `list-workspaces.md` | List all GSD workspaces found in `~/gsd-workspaces/` with their status. | `/gsd-list-workspaces` |
|
||||
| `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` |
|
||||
| `milestone-summary.md` | Milestone summary synthesis — onboarding and review artifact from milestone artifacts. | `/gsd-milestone-summary` |
|
||||
@@ -224,22 +224,22 @@ Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators
|
||||
| `progress.md` | Progress rendering — project context, position, and next-action routing. | `/gsd-progress` |
|
||||
| `quick.md` | Quick-task execution with GSD guarantees (atomic commits, state tracking). | `/gsd-quick` |
|
||||
| `reapply-patches.md` | Reapply local modifications after a GSD update. | `/gsd-update --reapply` |
|
||||
| `remove-phase.md` | Remove a future phase from the roadmap and renumber subsequent phases. | `/gsd-remove-phase` |
|
||||
| `remove-workspace.md` | Remove a GSD workspace and clean up worktrees. | `/gsd-remove-workspace` |
|
||||
| `remove-phase.md` | Remove a future phase from the roadmap and renumber subsequent phases. | `/gsd-phase --remove` |
|
||||
| `remove-workspace.md` | Remove a GSD workspace and clean up worktrees. | `/gsd-workspace --remove` |
|
||||
| `resume-project.md` | Resume work — restore full context from STATE.md, HANDOFF.json, and artifacts. | `/gsd-resume-work` |
|
||||
| `review.md` | Cross-AI plan review via external CLIs; produces REVIEWS.md. | `/gsd-review` |
|
||||
| `scan.md` | Rapid single-focus codebase scan — lightweight alternative to map-codebase. | `/gsd-scan` |
|
||||
| `secure-phase.md` | Retroactive threat-mitigation audit for a completed phase. | `/gsd-secure-phase` |
|
||||
| `session-report.md` | Session report — token usage, work summary, outcomes. | `/gsd-session-report` |
|
||||
| `settings.md` | Configure GSD workflow toggles and model profile. | `/gsd-settings`, `/gsd-set-profile` |
|
||||
| `settings-advanced.md` | Configure GSD power-user knobs — plan bounce, timeouts, branch templates, cross-AI execution, runtime knobs. | `/gsd-settings-advanced` |
|
||||
| `settings-integrations.md` | Configure third-party API keys (Brave/Firecrawl/Exa), `review.models.<cli>` CLI routing, and `agent_skills.<agent-type>` injection with masked (`****<last-4>`) display. | `/gsd-settings-integrations` |
|
||||
| `settings.md` | Configure GSD workflow toggles and model profile. | `/gsd-settings`, `/gsd-config --profile` |
|
||||
| `settings-advanced.md` | Configure GSD power-user knobs — plan bounce, timeouts, branch templates, cross-AI execution, runtime knobs. | `/gsd-config --advanced` |
|
||||
| `settings-integrations.md` | Configure third-party API keys (Brave/Firecrawl/Exa), `review.models.<cli>` CLI routing, and `agent_skills.<agent-type>` injection with masked (`****<last-4>`) display. | `/gsd-config --integrations` |
|
||||
| `ship.md` | Create PR, run review, and prepare for merge after verification. | `/gsd-ship` |
|
||||
| `sketch.md` | Explore design directions through throwaway HTML mockups with 2-3 variants per sketch. | `/gsd-sketch` |
|
||||
| `sketch-wrap-up.md` | Curate sketch findings and package them as a persistent `sketch-findings-[project]` skill. | `/gsd-sketch-wrap-up` |
|
||||
| `sketch-wrap-up.md` | Curate sketch findings and package them as a persistent `sketch-findings-[project]` skill. | `/gsd-sketch --wrap-up` |
|
||||
| `spec-phase.md` | Socratic spec refinement with ambiguity scoring; produces SPEC.md. | `/gsd-spec-phase` |
|
||||
| `spike.md` | Rapid feasibility validation through focused, throwaway experiments. | `/gsd-spike` |
|
||||
| `spike-wrap-up.md` | Curate spike findings and package them as a persistent `spike-findings-[project]` skill. | `/gsd-spike-wrap-up` |
|
||||
| `spike-wrap-up.md` | Curate spike findings and package them as a persistent `spike-findings-[project]` skill. | `/gsd-spike --wrap-up` |
|
||||
| `stats.md` | Project statistics rendering — phases, plans, requirements, git metrics. | `/gsd-stats` |
|
||||
| `sync-skills.md` | Cross-runtime GSD skill sync — diff and apply `gsd-*` skill directories across runtime roots. | `/gsd-update --sync` |
|
||||
| `transition.md` | Phase-boundary transition workflow — workstream checks, state advancement. | `execute-phase.md`, `/gsd-progress --next` |
|
||||
@@ -383,7 +383,7 @@ Full listing: `get-shit-done/bin/lib/*.cjs`.
|
||||
| `roadmap-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools roadmap` |
|
||||
| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress |
|
||||
| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) |
|
||||
| `secrets.cjs` | Secret-config masking convention (`****<last-4>`) for integration keys managed by `/gsd-settings-integrations` — keeps plaintext out of `config-set` output |
|
||||
| `secrets.cjs` | Secret-config masking convention (`****<last-4>`) for integration keys managed by `/gsd-config --integrations` — keeps plaintext out of `config-set` output |
|
||||
| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON/shell helpers |
|
||||
| `state-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools state` |
|
||||
| `state.cjs` | STATE.md parsing, updating, progression, metrics |
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
# STATE.md Phase Lifecycle Frontmatter
|
||||
|
||||
> **Status:** Reference for the phase-lifecycle status-line proposed in
|
||||
> [issue #2833](https://github.com/gsd-build/get-shit-done/issues/2833).
|
||||
> The status-line hook (`hooks/gsd-statusline.js`) reads the fields below;
|
||||
> SDK write-side support to maintain them is tracked separately.
|
||||
> **Status:** Read-side shipped in v1.40.0 (issue
|
||||
> [#2833](https://github.com/gsd-build/get-shit-done/issues/2833)).
|
||||
> `parseStateMd()` reads the four frontmatter fields below and
|
||||
> `formatGsdState()` renders the in-flight / idle / progress scenes.
|
||||
> SDK write-side support to maintain the fields automatically is tracked
|
||||
> separately.
|
||||
|
||||
GSD's `STATE.md` carries YAML frontmatter that the status-line hook reads on
|
||||
every render. This document describes the **phase-lifecycle fields** and the
|
||||
|
||||
@@ -25,6 +25,32 @@ execute → verify → review → ship loop using existing GSD primitives.
|
||||
|
||||
---
|
||||
|
||||
## Slash-command forms (hyphen vs colon)
|
||||
|
||||
GSD ships **the same set of skills** to every supported runtime, but two slash-form spellings are in play:
|
||||
|
||||
- **Hyphen form** — `/gsd-command-name` — used by Claude Code, Copilot, OpenCode, Kilo, Cursor, Windsurf, Augment, Antigravity, and Trae.
|
||||
- **Colon form** — `/gsd:command-name` — used by **Gemini CLI only**. Gemini namespaces every plugin's commands under the plugin id, so the install path rewrites every body-text reference and command file to the colon form during `--gemini` install.
|
||||
|
||||
You don't need to choose — the installer writes the correct form into the command directory of each runtime you target. When following a walkthrough on a Gemini terminal, replace the hyphen after `gsd` with a colon as you read each slash command.
|
||||
|
||||
## Namespace routing primer (`gsd:<namespace>`, v1.40)
|
||||
|
||||
v1.40 ships six **namespace meta-skills** as the first-stage entry points for hierarchical routing — they keep the eager skill-listing token cost low (~120 tokens for 6 routers vs ~2,150 for a flat 86-skill listing) while every concrete sub-skill remains directly invocable. Each namespace router's body contains a routing table that maps your intent to the correct concrete sub-skill.
|
||||
|
||||
| Namespace | Router | Routes to |
|
||||
|-----------|--------|-----------|
|
||||
| Phase pipeline | `/gsd-ns-workflow` | discuss / plan / execute / verify / phase / progress |
|
||||
| Project lifecycle | `/gsd-ns-project` | milestones, audits, summary |
|
||||
| Quality gates | `/gsd-ns-review` | code review, debug, audit, security, eval, ui |
|
||||
| Codebase intelligence | `/gsd-ns-context` | map, graphify, docs, learnings |
|
||||
| Management | `/gsd-ns-manage` | config, workspace, workstreams, thread, update, ship, inbox |
|
||||
| Exploration & capture | `/gsd-ns-ideate` | explore, sketch, spike, spec, capture |
|
||||
|
||||
You almost never need to type a namespace router yourself. Their value is in the routing layer the model uses to discover the right sub-skill — they exist so the system prompt can list 6 entries instead of 86. If you already know the concrete command (e.g. `/gsd-plan-phase`), call it directly.
|
||||
|
||||
---
|
||||
|
||||
## End-to-End Walkthrough
|
||||
|
||||
This walkthrough shows how GSD phases connect for a typical single-phase project — a small Node.js REST API that validates webhook signatures. Follow it to understand what each command does, what it creates, and how the next command consumes it.
|
||||
@@ -571,7 +597,7 @@ Each spike runs 2–5 experiments. Every experiment has:
|
||||
|
||||
Results land in `.planning/spikes/NNN-name/README.md` and are indexed in `.planning/spikes/MANIFEST.md`.
|
||||
|
||||
Once you have signal, run `/gsd-spike-wrap-up` to package the findings into `.claude/skills/spike-findings-[project]/` — future sessions will load them automatically via project-skills discovery.
|
||||
Once you have signal, run `/gsd-spike --wrap-up` to package the findings into `.claude/skills/spike-findings-[project]/` — future sessions will load them automatically via project-skills discovery.
|
||||
|
||||
### When to Sketch
|
||||
|
||||
@@ -586,16 +612,16 @@ Sketch when you need to compare layout structures, interaction models, or visual
|
||||
|
||||
Each sketch answers **one design question** with 2–3 variants in a single `index.html` you open directly in a browser — no build step. Variants use tab navigation and shared CSS variables from `themes/default.css`. All interactive elements (hover, click, transitions) are functional.
|
||||
|
||||
After picking a winner, run `/gsd-sketch-wrap-up` to capture the visual decisions into `.claude/skills/sketch-findings-[project]/`.
|
||||
After picking a winner, run `/gsd-sketch --wrap-up` to capture the visual decisions into `.claude/skills/sketch-findings-[project]/`.
|
||||
|
||||
### Spike → Sketch → Phase Flow
|
||||
|
||||
```
|
||||
/gsd-spike "SSE vs WebSocket" # Validate the approach
|
||||
/gsd-spike-wrap-up # Package learnings
|
||||
/gsd-spike --wrap-up # Package learnings
|
||||
|
||||
/gsd-sketch "real-time feed UI" # Explore the design
|
||||
/gsd-sketch-wrap-up # Package decisions
|
||||
/gsd-sketch --wrap-up # Package decisions
|
||||
|
||||
/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
|
||||
/gsd-plan-phase N # Plan with confidence
|
||||
@@ -610,8 +636,8 @@ After picking a winner, run `/gsd-sketch-wrap-up` to capture the visual decision
|
||||
Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
|
||||
|
||||
```
|
||||
/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
```
|
||||
|
||||
Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999.1` to explore an idea further or `/gsd-plan-phase 999.1` when it's ready.
|
||||
@@ -623,7 +649,7 @@ Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999
|
||||
Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
|
||||
|
||||
```
|
||||
/gsd-plant-seed "Add real-time collab when WebSocket infra is in place"
|
||||
/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
Seeds preserve the full WHY and WHEN to surface. `/gsd-new-milestone` scans all seeds and presents matches.
|
||||
@@ -642,7 +668,7 @@ Threads are lightweight cross-session knowledge stores for work that spans multi
|
||||
|
||||
Threads are lighter weight than `/gsd-pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
|
||||
|
||||
Threads can be promoted to phases (`/gsd-add-phase`) or backlog items (`/gsd-add-backlog`) when they mature.
|
||||
Threads can be promoted to phases (`/gsd-phase`) or backlog items (`/gsd-capture --backlog`) when they mature.
|
||||
|
||||
**Storage:** `.planning/threads/{slug}.md`
|
||||
|
||||
@@ -918,11 +944,13 @@ The gate is non-blocking: any internal failure logs and the phase continues.
|
||||
### Mid-Milestone Scope Changes
|
||||
|
||||
```bash
|
||||
/gsd-add-phase # Append a new phase to the roadmap
|
||||
/gsd-phase # Append a new phase to the roadmap (default mode)
|
||||
# or
|
||||
/gsd-insert-phase 3 # Insert urgent work between phases 3 and 4
|
||||
/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
|
||||
# or
|
||||
/gsd-remove-phase 7 # Descope phase 7 and renumber
|
||||
/gsd-phase --remove 7 # Descope phase 7 and renumber
|
||||
# or
|
||||
/gsd-phase --edit 4 # Edit any field of phase 4 in place
|
||||
```
|
||||
|
||||
### Multi-Project Workspaces
|
||||
@@ -941,8 +969,8 @@ cd ~/gsd-workspaces/feature-b
|
||||
/gsd-new-project
|
||||
|
||||
# List and manage workspaces
|
||||
/gsd-list-workspaces
|
||||
/gsd-remove-workspace feature-b
|
||||
/gsd-workspace --list
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
Each workspace gets:
|
||||
@@ -1014,7 +1042,7 @@ Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes, or `/gs
|
||||
|
||||
### Model Costs Too High
|
||||
|
||||
Switch to budget profile: `/gsd-set-profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar to you (or to Claude).
|
||||
Switch to budget profile: `/gsd-config --profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar to you (or to Claude).
|
||||
|
||||
### Tuning model cost by phase (`models`) — added in v1.40
|
||||
|
||||
@@ -1174,7 +1202,7 @@ Skills are installed to `~/.qwen/skills/gsd-*/SKILL.md`. Use the `QWEN_CONFIG_DI
|
||||
|
||||
### Using Claude Code with Non-Anthropic Providers (OpenRouter, Local)
|
||||
|
||||
If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd-set-profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd-settings` → Model Profile → Inherit.
|
||||
If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd-config --profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd-settings` → Model Profile → Inherit.
|
||||
|
||||
### Working on a Sensitive/Private Project
|
||||
|
||||
@@ -1357,13 +1385,13 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo
|
||||
| ------------------------------------ | ------------------------------------------------------------------------ |
|
||||
| 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` |
|
||||
| Need to change scope | `/gsd-phase` (default), `/gsd-phase --insert`, or `/gsd-phase --remove` |
|
||||
| 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 |
|
||||
| Costs running high | `/gsd-config --profile budget` and `/gsd-settings` to toggle agents off |
|
||||
| Update broke local changes | `/gsd-update --reapply` |
|
||||
| Want session summary for stakeholder | `/gsd-session-report` |
|
||||
| Don't know what step is next | `/gsd-next` |
|
||||
|
||||
@@ -411,7 +411,7 @@ UI-SPEC.md (per phase) ───────────────────
|
||||
│ ├── pending/ # キャプチャされたアイデア
|
||||
│ └── done/ # 完了済みtodo
|
||||
├── threads/ # 永続コンテキストスレッド（/gsd-thread から）
|
||||
├── seeds/ # 将来に向けたアイデア（/gsd-plant-seed から）
|
||||
├── seeds/ # 将来に向けたアイデア（/gsd-capture --seed から）
|
||||
├── debug/ # アクティブなデバッグセッション
|
||||
│ ├── *.md # アクティブセッション
|
||||
│ ├── resolved/ # アーカイブ済みセッション
|
||||
|
||||
@@ -59,7 +59,7 @@
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-list-workspaces`
|
||||
### `/gsd-workspace --list`
|
||||
|
||||
アクティブなGSDワークスペースとそのステータスを一覧表示します。
|
||||
|
||||
@@ -67,12 +67,12 @@
|
||||
**表示内容:** 名前、リポジトリ数、戦略、GSDプロジェクトのステータス
|
||||
|
||||
```bash
|
||||
/gsd-list-workspaces
|
||||
/gsd-workspace --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-remove-workspace`
|
||||
### `/gsd-workspace --remove`
|
||||
|
||||
ワークスペースを削除し、git worktreeをクリーンアップします。
|
||||
|
||||
@@ -83,7 +83,7 @@
|
||||
**安全性:** コミットされていない変更があるリポジトリの削除を拒否します。名前の確認が必要です。
|
||||
|
||||
```bash
|
||||
/gsd-remove-workspace feature-b
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
---
|
||||
@@ -368,15 +368,15 @@
|
||||
|
||||
## フェーズ管理コマンド
|
||||
|
||||
### `/gsd-add-phase`
|
||||
### `/gsd-phase`
|
||||
|
||||
ロードマップに新しいフェーズを追加します。
|
||||
|
||||
```bash
|
||||
/gsd-add-phase # 対話型 — フェーズの説明を入力
|
||||
/gsd-phase # 対話型 — フェーズの説明を入力
|
||||
```
|
||||
|
||||
### `/gsd-insert-phase`
|
||||
### `/gsd-phase --insert`
|
||||
|
||||
小数番号を使用して、フェーズ間に緊急の作業を挿入します。
|
||||
|
||||
@@ -385,10 +385,10 @@
|
||||
| `N` | いいえ | このフェーズ番号の後に挿入 |
|
||||
|
||||
```bash
|
||||
/gsd-insert-phase 3 # フェーズ3と4の間に挿入 → 3.1を作成
|
||||
/gsd-phase --insert 3 # フェーズ3と4の間に挿入 → 3.1を作成
|
||||
```
|
||||
|
||||
### `/gsd-remove-phase`
|
||||
### `/gsd-phase --remove`
|
||||
|
||||
将来のフェーズを削除し、後続のフェーズの番号を振り直します。
|
||||
|
||||
@@ -397,7 +397,7 @@
|
||||
| `N` | いいえ | 削除するフェーズ番号 |
|
||||
|
||||
```bash
|
||||
/gsd-remove-phase 7 # フェーズ7を削除、8→7、9→8等に番号振り直し
|
||||
/gsd-phase --remove 7 # フェーズ7を削除、8→7、9→8等に番号振り直し
|
||||
```
|
||||
|
||||
### `/gsd-list-phase-assumptions`
|
||||
@@ -591,7 +591,7 @@ GSDの保証付きでアドホックタスクを実行します。
|
||||
/gsd-debug --diagnose "API returning 500 on /users endpoint"
|
||||
```
|
||||
|
||||
### `/gsd-add-todo`
|
||||
### `/gsd-capture`
|
||||
|
||||
後で取り組むアイデアやタスクをキャプチャします。
|
||||
|
||||
@@ -600,7 +600,7 @@ GSDの保証付きでアドホックタスクを実行します。
|
||||
| `description` | いいえ | Todoの説明 |
|
||||
|
||||
```bash
|
||||
/gsd-add-todo "Consider adding dark mode support"
|
||||
/gsd-capture "Consider adding dark mode support"
|
||||
```
|
||||
|
||||
### `/gsd-capture --list`
|
||||
@@ -745,7 +745,7 @@ Claude Codeのセッション分析から8つの次元（コミュニケーシ
|
||||
/gsd-settings # 対話型設定
|
||||
```
|
||||
|
||||
### `/gsd-set-profile`
|
||||
### `/gsd-config --profile`
|
||||
|
||||
クイックプロファイル切り替え。
|
||||
|
||||
@@ -754,8 +754,8 @@ Claude Codeのセッション分析から8つの次元（コミュニケーシ
|
||||
| `profile` | **はい** | `quality`、`balanced`、`budget`、または `inherit` |
|
||||
|
||||
```bash
|
||||
/gsd-set-profile budget # budgetプロファイルに切り替え
|
||||
/gsd-set-profile quality # qualityプロファイルに切り替え
|
||||
/gsd-config --profile budget # budgetプロファイルに切り替え
|
||||
/gsd-config --profile quality # qualityプロファイルに切り替え
|
||||
```
|
||||
|
||||
---
|
||||
@@ -878,7 +878,7 @@ GSDアップデート後にローカルの変更を復元します。
|
||||
|
||||
## バックログ＆スレッドコマンド
|
||||
|
||||
### `/gsd-add-backlog`
|
||||
### `/gsd-capture --backlog`
|
||||
|
||||
999.x番号付けを使用して、バックログのパーキングロットにアイデアを追加します。
|
||||
|
||||
@@ -889,8 +889,8 @@ GSDアップデート後にローカルの変更を復元します。
|
||||
**999.x番号付け**により、バックログ項目はアクティブなフェーズシーケンスの外に保持されます。フェーズディレクトリは即座に作成されるため、`/gsd-discuss-phase` や `/gsd-plan-phase` がそれらに対して動作します。
|
||||
|
||||
```bash
|
||||
/gsd-add-backlog "GraphQL API layer"
|
||||
/gsd-add-backlog "Mobile responsive redesign"
|
||||
/gsd-capture --backlog "GraphQL API layer"
|
||||
/gsd-capture --backlog "Mobile responsive redesign"
|
||||
```
|
||||
|
||||
---
|
||||
@@ -907,7 +907,7 @@ GSDアップデート後にローカルの変更を復元します。
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-plant-seed`
|
||||
### `/gsd-capture --seed`
|
||||
|
||||
トリガー条件付きの将来のアイデアをキャプチャ — 適切なマイルストーンで自動的に表面化します。
|
||||
|
||||
@@ -921,7 +921,7 @@ GSDアップデート後にローカルの変更を復元します。
|
||||
**利用先:** `/gsd-new-milestone`（シードをスキャンしてマッチするものを提示）
|
||||
|
||||
```bash
|
||||
/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place"
|
||||
/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -393,7 +393,7 @@
|
||||
|
||||
### 9. フェーズ管理
|
||||
|
||||
**コマンド:** `/gsd-add-phase`、`/gsd-insert-phase [N]`、`/gsd-remove-phase [N]`
|
||||
**コマンド:** `/gsd-phase`、`/gsd-phase --insert [N]`、`/gsd-phase --remove [N]`
|
||||
|
||||
**目的:** 開発中のロードマップの動的な変更。
|
||||
|
||||
@@ -680,7 +680,7 @@
|
||||
|
||||
### 26. モデルプロファイル
|
||||
|
||||
**コマンド:** `/gsd-set-profile <quality|balanced|budget|inherit>`
|
||||
**コマンド:** `/gsd-config --profile <quality|balanced|budget|inherit>`
|
||||
|
||||
**目的:** 各エージェントが使用する AI モデルを制御し、品質とコストのバランスを取ります。
|
||||
|
||||
@@ -762,7 +762,7 @@
|
||||
|
||||
### 29. Todo 管理
|
||||
|
||||
**コマンド:** `/gsd-add-todo [desc]`、`/gsd-capture --list`
|
||||
**コマンド:** `/gsd-capture [desc]`、`/gsd-capture --list`
|
||||
|
||||
**目的:** セッション中にアイデアやタスクをキャプチャし、後で作業できるようにします。
|
||||
|
||||
@@ -1065,7 +1065,7 @@ fix(03-01): correct auth token expiry
|
||||
|
||||
### 43. バックログパーキングロット
|
||||
|
||||
**コマンド:** `/gsd-add-backlog <description>`、`/gsd-review-backlog`、`/gsd-plant-seed <idea>`
|
||||
**コマンド:** `/gsd-capture --backlog <description>`、`/gsd-review-backlog`、`/gsd-capture --seed <idea>`
|
||||
|
||||
**目的:** アクティブなプランニングの準備ができていないアイデアをキャプチャします。バックログ項目は 999.x の番号付けを使用して、アクティブなフェーズシーケンスの外に留まります。シードは、適切なマイルストーンで自動的に表面化するトリガー条件を持つ、将来を見据えたアイデアです。
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ Get Shit Done（GSD）フレームワークの包括的なドキュメントで
|
||||
|
||||
## クイックリンク
|
||||
|
||||
- **v1.39 の新機能:** `--minimal` インストールプロファイル（≥94% コールドスタート削減）、`/gsd-edit-phase`、マージ後ビルド & テストゲート、`review.models.<cli>` ランタイム別レビューモデル、ワークストリーム設定の継承、手動カナリアリリースワークフロー、スキル統合（86 → 59）
|
||||
- **v1.39 の新機能:** `--minimal` インストールプロファイル（≥94% コールドスタート削減）、`/gsd-phase --edit`、マージ後ビルド & テストゲート、`review.models.<cli>` ランタイム別レビューモデル、ワークストリーム設定の継承、手動カナリアリリースワークフロー、スキル統合（86 → 59）
|
||||
- **はじめに:** [README](../README.md) → インストール → `/gsd-new-project`
|
||||
- **ワークフロー完全ガイド:** [ユーザーガイド](USER-GUIDE.md)
|
||||
- **コマンド一覧:** [コマンドリファレンス](COMMANDS.md)
|
||||
|
||||
@@ -256,8 +256,8 @@ React/Next.js/Vite プロジェクトの場合、UI リサーチャーは `compo
|
||||
アクティブなプランニングの準備ができていないアイデアは、999.x 番号を使用してバックログに格納され、アクティブなフェーズシーケンスの外に保持されます。
|
||||
|
||||
```
|
||||
/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
```
|
||||
|
||||
バックログアイテムは完全なフェーズディレクトリを取得するため、`/gsd-discuss-phase 999.1` でアイデアをさらに探索したり、準備が整ったら `/gsd-plan-phase 999.1` を使用できます。
|
||||
@@ -269,7 +269,7 @@ React/Next.js/Vite プロジェクトの場合、UI リサーチャーは `compo
|
||||
シードは、トリガー条件を持つ将来を見据えたアイデアです。バックログアイテムとは異なり、適切なマイルストーンが到来すると自動的に表面化されます。
|
||||
|
||||
```
|
||||
/gsd-plant-seed "Add real-time collab when WebSocket infra is in place"
|
||||
/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
シードは完全な WHY と表面化タイミングを保持します。`/gsd-new-milestone` はすべてのシードをスキャンし、一致するものを提示します。
|
||||
@@ -288,7 +288,7 @@ React/Next.js/Vite プロジェクトの場合、UI リサーチャーは `compo
|
||||
|
||||
スレッドは `/gsd-pause-work` より軽量です — フェーズ状態やプランコンテキストはありません。各スレッドファイルには Goal、Context、References、Next Steps セクションが含まれます。
|
||||
|
||||
スレッドは成熟した段階でフェーズ (`/gsd-add-phase`) やバックログアイテム (`/gsd-add-backlog`) にプロモーションできます。
|
||||
スレッドは成熟した段階でフェーズ (`/gsd-phase`) やバックログアイテム (`/gsd-capture --backlog`) にプロモーションできます。
|
||||
|
||||
**保存場所：** `.planning/threads/{slug}.md`
|
||||
|
||||
@@ -413,9 +413,9 @@ GSD はマークダウンファイルを生成し、それが LLM のシステ
|
||||
|
||||
| コマンド | 用途 | 使用タイミング |
|
||||
|---------|---------|-------------|
|
||||
| `/gsd-add-phase` | ロードマップに新しいフェーズを追加 | 初期プランニング後にスコープが拡大した場合 |
|
||||
| `/gsd-insert-phase [N]` | 緊急作業を挿入（小数番号） | マイルストーン中の緊急修正 |
|
||||
| `/gsd-remove-phase [N]` | 将来のフェーズを削除して番号を振り直す | 機能のスコープ縮小 |
|
||||
| `/gsd-phase` | ロードマップに新しいフェーズを追加 | 初期プランニング後にスコープが拡大した場合 |
|
||||
| `/gsd-phase --insert [N]` | 緊急作業を挿入（小数番号） | マイルストーン中の緊急修正 |
|
||||
| `/gsd-phase --remove [N]` | 将来のフェーズを削除して番号を振り直す | 機能のスコープ縮小 |
|
||||
| `/gsd-list-phase-assumptions [N]` | Claude の意図するアプローチをプレビュー | プランニング前に方向性を確認 |
|
||||
| `/gsd-plan-phase --research-phase [N]` | エコシステムの深いリサーチのみ | 複雑または不慣れなドメイン |
|
||||
|
||||
@@ -427,10 +427,10 @@ GSD はマークダウンファイルを生成し、それが LLM のシステ
|
||||
| `/gsd-quick` | GSD 保証付きのアドホックタスク | バグ修正、小機能、設定変更 |
|
||||
| `/gsd-debug [desc]` | 永続状態を持つ体系的デバッグ | 何かが壊れた時 |
|
||||
| `/gsd-forensics` | ワークフロー障害の診断レポート | 状態、アーティファクト、git 履歴が破損していると思われる場合 |
|
||||
| `/gsd-add-todo [desc]` | 後でやるアイデアを記録 | セッション中にアイデアが浮かんだ時 |
|
||||
| `/gsd-capture [desc]` | 後でやるアイデアを記録 | セッション中にアイデアが浮かんだ時 |
|
||||
| `/gsd-capture --list` | 保留中の TODO を一覧表示 | 記録したアイデアのレビュー |
|
||||
| `/gsd-settings` | ワークフロートグルとモデルプロファイルを設定 | モデル変更、エージェントのトグル |
|
||||
| `/gsd-set-profile <profile>` | クイックプロファイル切り替え | コスト/品質トレードオフの変更 |
|
||||
| `/gsd-config --profile <profile>` | クイックプロファイル切り替え | コスト/品質トレードオフの変更 |
|
||||
| `/gsd-update --reapply` | アップデート後にローカル変更を復元 | ローカル編集がある場合の `/gsd-update` 後 |
|
||||
|
||||
### コード品質とレビュー
|
||||
@@ -445,9 +445,9 @@ GSD はマークダウンファイルを生成し、それが LLM のシステ
|
||||
|
||||
| コマンド | 用途 | 使用タイミング |
|
||||
|---------|---------|-------------|
|
||||
| `/gsd-add-backlog <desc>` | バックログパーキングロットにアイデアを追加（999.x） | アクティブなプランニングの準備ができていないアイデア |
|
||||
| `/gsd-capture --backlog <desc>` | バックログパーキングロットにアイデアを追加（999.x） | アクティブなプランニングの準備ができていないアイデア |
|
||||
| `/gsd-review-backlog` | バックログアイテムのプロモーション/保持/削除 | 新マイルストーン前の優先順位付け |
|
||||
| `/gsd-plant-seed <idea>` | トリガー条件付きの将来を見据えたアイデア | 将来のマイルストーンで表面化すべきアイデア |
|
||||
| `/gsd-capture --seed <idea>` | トリガー条件付きの将来を見据えたアイデア | 将来のマイルストーンで表面化すべきアイデア |
|
||||
| `/gsd-thread [name]` | 永続コンテキストスレッド | フェーズ構造外のクロスセッション作業 |
|
||||
|
||||
---
|
||||
@@ -657,11 +657,11 @@ claude --dangerously-skip-permissions
|
||||
### マイルストーン中のスコープ変更
|
||||
|
||||
```bash
|
||||
/gsd-add-phase # ロードマップに新しいフェーズを追加
|
||||
/gsd-phase # ロードマップに新しいフェーズを追加
|
||||
# または
|
||||
/gsd-insert-phase 3 # フェーズ 3 と 4 の間に緊急作業を挿入
|
||||
/gsd-phase --insert 3 # フェーズ 3 と 4 の間に緊急作業を挿入
|
||||
# または
|
||||
/gsd-remove-phase 7 # フェーズ 7 をスコープ外にして番号を振り直す
|
||||
/gsd-phase --remove 7 # フェーズ 7 をスコープ外にして番号を振り直す
|
||||
```
|
||||
|
||||
### マルチプロジェクトワークスペース
|
||||
@@ -680,8 +680,8 @@ cd ~/gsd-workspaces/feature-b
|
||||
/gsd-new-project
|
||||
|
||||
# ワークスペースの一覧と管理
|
||||
/gsd-list-workspaces
|
||||
/gsd-remove-workspace feature-b
|
||||
/gsd-workspace --list
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
各ワークスペースには以下が含まれます：
|
||||
@@ -719,7 +719,7 @@ cd ~/gsd-workspaces/feature-b
|
||||
|
||||
### モデルのコストが高すぎる
|
||||
|
||||
budget プロファイルに切り替えてください：`/gsd-set-profile budget`。ドメインに慣れている場合（またはClaude が慣れている場合）は、`/gsd-settings` でリサーチエージェントと plan-check エージェントを無効にしてください。
|
||||
budget プロファイルに切り替えてください：`/gsd-config --profile budget`。ドメインに慣れている場合（またはClaude が慣れている場合）は、`/gsd-settings` でリサーチエージェントと plan-check エージェントを無効にしてください。
|
||||
|
||||
### 非 Claude ランタイムの使用（Codex、OpenCode、Gemini CLI、Kilo）
|
||||
|
||||
@@ -744,7 +744,7 @@ budget プロファイルに切り替えてください：`/gsd-set-profile budg
|
||||
|
||||
### 非 Anthropic プロバイダーでの Claude Code の使用（OpenRouter、ローカル）
|
||||
|
||||
GSD サブエージェントが Anthropic モデルを呼び出し、OpenRouter やローカルプロバイダーを通じて支払っている場合は、`inherit` プロファイルに切り替えてください：`/gsd-set-profile inherit`。これにより、すべてのエージェントが特定の Anthropic モデルの代わりに現在のセッションモデルを使用します。`/gsd-settings` → モデルプロファイル → Inherit も参照してください。
|
||||
GSD サブエージェントが Anthropic モデルを呼び出し、OpenRouter やローカルプロバイダーを通じて支払っている場合は、`inherit` プロファイルに切り替えてください：`/gsd-config --profile inherit`。これにより、すべてのエージェントが特定の Anthropic モデルの代わりに現在のセッションモデルを使用します。`/gsd-settings` → モデルプロファイル → Inherit も参照してください。
|
||||
|
||||
### 機密/プライベートプロジェクトでの作業
|
||||
|
||||
@@ -792,12 +792,12 @@ Windows でインストーラーが `EPERM: operation not permitted, scandir`
|
||||
|---------|----------|
|
||||
| コンテキストの喪失 / 新セッション | `/gsd-resume-work` または `/gsd-progress` |
|
||||
| フェーズが失敗した | フェーズのコミットを `git revert` して再プランニング |
|
||||
| スコープ変更が必要 | `/gsd-add-phase`、`/gsd-insert-phase`、または `/gsd-remove-phase` |
|
||||
| スコープ変更が必要 | `/gsd-phase`、`/gsd-phase --insert`、または `/gsd-phase --remove` |
|
||||
| 何かが壊れた | `/gsd-debug "description"` |
|
||||
| ワークフロー状態が破損している可能性 | `/gsd-forensics` |
|
||||
| ターゲットを絞った修正 | `/gsd-quick` |
|
||||
| プランがビジョンに合わない | `/gsd-discuss-phase [N]` で再プランニング |
|
||||
| コストが高い | `/gsd-set-profile budget` と `/gsd-settings` でエージェントをオフ |
|
||||
| コストが高い | `/gsd-config --profile budget` と `/gsd-settings` でエージェントをオフ |
|
||||
| アップデートがローカル変更を壊した | `/gsd-update --reapply` |
|
||||
| ステークホルダー向けセッションサマリーが欲しい | `/gsd-session-report` |
|
||||
| 次のステップがわからない | `/gsd-next` |
|
||||
|
||||
@@ -411,7 +411,7 @@ UI-SPEC.md (per phase) ───────────────────
|
||||
│ ├── pending/ # 캡처된 아이디어
|
||||
│ └── done/ # 완료된 할 일
|
||||
├── threads/ # 영구 컨텍스트 스레드 (/gsd-thread에서)
|
||||
├── seeds/ # 미래 지향적 아이디어 (/gsd-plant-seed에서)
|
||||
├── seeds/ # 미래 지향적 아이디어 (/gsd-capture --seed에서)
|
||||
├── debug/ # 활성 디버그 세션
|
||||
│ ├── *.md # 활성 세션
|
||||
│ ├── resolved/ # 보관된 세션
|
||||
|
||||
@@ -59,7 +59,7 @@
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-list-workspaces`
|
||||
### `/gsd-workspace --list`
|
||||
|
||||
활성 GSD 워크스페이스와 상태를 목록으로 표시합니다.
|
||||
|
||||
@@ -67,12 +67,12 @@
|
||||
**표시 항목:** 이름, 저장소 수, 전략, GSD 프로젝트 상태
|
||||
|
||||
```bash
|
||||
/gsd-list-workspaces
|
||||
/gsd-workspace --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-remove-workspace`
|
||||
### `/gsd-workspace --remove`
|
||||
|
||||
워크스페이스를 제거하고 git worktree를 정리합니다.
|
||||
|
||||
@@ -83,7 +83,7 @@
|
||||
**안전 장치:** 저장소에 커밋되지 않은 변경사항이 있으면 제거를 거부합니다. 이름 확인이 필요합니다.
|
||||
|
||||
```bash
|
||||
/gsd-remove-workspace feature-b
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
---
|
||||
@@ -368,15 +368,15 @@
|
||||
|
||||
## 페이즈 관리 명령어
|
||||
|
||||
### `/gsd-add-phase`
|
||||
### `/gsd-phase`
|
||||
|
||||
로드맵에 새 페이즈를 추가합니다.
|
||||
|
||||
```bash
|
||||
/gsd-add-phase # 대화형 — 페이즈를 설명합니다
|
||||
/gsd-phase # 대화형 — 페이즈를 설명합니다
|
||||
```
|
||||
|
||||
### `/gsd-insert-phase`
|
||||
### `/gsd-phase --insert`
|
||||
|
||||
소수점 번호 체계를 사용하여 페이즈 사이에 긴급 작업을 삽입합니다.
|
||||
|
||||
@@ -385,10 +385,10 @@
|
||||
| `N` | 아니오 | 이 페이즈 번호 다음에 삽입합니다 |
|
||||
|
||||
```bash
|
||||
/gsd-insert-phase 3 # 페이즈 3과 4 사이에 삽입 → 3.1 생성
|
||||
/gsd-phase --insert 3 # 페이즈 3과 4 사이에 삽입 → 3.1 생성
|
||||
```
|
||||
|
||||
### `/gsd-remove-phase`
|
||||
### `/gsd-phase --remove`
|
||||
|
||||
미래 페이즈를 제거하고 이후 페이즈 번호를 재정렬합니다.
|
||||
|
||||
@@ -397,7 +397,7 @@
|
||||
| `N` | 아니오 | 제거할 페이즈 번호 |
|
||||
|
||||
```bash
|
||||
/gsd-remove-phase 7 # 페이즈 7 제거, 8→7, 9→8 등으로 재번호
|
||||
/gsd-phase --remove 7 # 페이즈 7 제거, 8→7, 9→8 등으로 재번호
|
||||
```
|
||||
|
||||
### `/gsd-list-phase-assumptions`
|
||||
@@ -591,7 +591,7 @@ GSD 보증을 갖춘 임시 작업을 실행합니다.
|
||||
/gsd-debug --diagnose "API returning 500 on /users endpoint"
|
||||
```
|
||||
|
||||
### `/gsd-add-todo`
|
||||
### `/gsd-capture`
|
||||
|
||||
나중을 위한 아이디어나 작업을 캡처합니다.
|
||||
|
||||
@@ -600,7 +600,7 @@ GSD 보증을 갖춘 임시 작업을 실행합니다.
|
||||
| `description` | 아니오 | 할 일 설명 |
|
||||
|
||||
```bash
|
||||
/gsd-add-todo "Consider adding dark mode support"
|
||||
/gsd-capture "Consider adding dark mode support"
|
||||
```
|
||||
|
||||
### `/gsd-capture --list`
|
||||
@@ -745,7 +745,7 @@ Claude Code 세션 분석을 통해 8개 차원(커뮤니케이션 스타일,
|
||||
/gsd-settings # 대화형 설정
|
||||
```
|
||||
|
||||
### `/gsd-set-profile`
|
||||
### `/gsd-config --profile`
|
||||
|
||||
프로필을 빠르게 전환합니다.
|
||||
|
||||
@@ -754,8 +754,8 @@ Claude Code 세션 분석을 통해 8개 차원(커뮤니케이션 스타일,
|
||||
| `profile` | **예** | `quality`, `balanced`, `budget`, 또는 `inherit` |
|
||||
|
||||
```bash
|
||||
/gsd-set-profile budget # 예산 프로필로 전환
|
||||
/gsd-set-profile quality # 품질 프로필로 전환
|
||||
/gsd-config --profile budget # 예산 프로필로 전환
|
||||
/gsd-config --profile quality # 품질 프로필로 전환
|
||||
```
|
||||
|
||||
---
|
||||
@@ -878,7 +878,7 @@ GSD 업데이트 후 로컬 수정사항을 복원합니다.
|
||||
|
||||
## 백로그 및 스레드 명령어
|
||||
|
||||
### `/gsd-add-backlog`
|
||||
### `/gsd-capture --backlog`
|
||||
|
||||
999.x 번호 체계를 사용하여 백로그 파킹 롯에 아이디어를 추가합니다.
|
||||
|
||||
@@ -889,8 +889,8 @@ GSD 업데이트 후 로컬 수정사항을 복원합니다.
|
||||
**999.x 번호 체계**는 백로그 항목을 활성 페이즈 순서 밖에 유지합니다. 페이즈 디렉터리가 즉시 생성되므로 해당 항목에 대해 `/gsd-discuss-phase`와 `/gsd-plan-phase`를 사용할 수 있습니다.
|
||||
|
||||
```bash
|
||||
/gsd-add-backlog "GraphQL API layer"
|
||||
/gsd-add-backlog "Mobile responsive redesign"
|
||||
/gsd-capture --backlog "GraphQL API layer"
|
||||
/gsd-capture --backlog "Mobile responsive redesign"
|
||||
```
|
||||
|
||||
---
|
||||
@@ -907,7 +907,7 @@ GSD 업데이트 후 로컬 수정사항을 복원합니다.
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-plant-seed`
|
||||
### `/gsd-capture --seed`
|
||||
|
||||
트리거 조건이 있는 미래 지향적인 아이디어를 캡처합니다. 적절한 마일스톤 시점에 자동으로 표면화됩니다.
|
||||
|
||||
@@ -921,7 +921,7 @@ GSD 업데이트 후 로컬 수정사항을 복원합니다.
|
||||
**사용처:** `/gsd-new-milestone` (시드를 스캔하여 일치 항목 제시)
|
||||
|
||||
```bash
|
||||
/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place"
|
||||
/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -393,7 +393,7 @@
|
||||
|
||||
### 9. Phase Management
|
||||
|
||||
**명령어:** `/gsd-add-phase`, `/gsd-insert-phase [N]`, `/gsd-remove-phase [N]`
|
||||
**명령어:** `/gsd-phase`, `/gsd-phase --insert [N]`, `/gsd-phase --remove [N]`
|
||||
|
||||
**목적:** 개발 중 동적 로드맵 수정.
|
||||
|
||||
@@ -680,7 +680,7 @@
|
||||
|
||||
### 26. Model Profiles
|
||||
|
||||
**명령어:** `/gsd-set-profile <quality|balanced|budget|inherit>`
|
||||
**명령어:** `/gsd-config --profile <quality|balanced|budget|inherit>`
|
||||
|
||||
**목적:** 각 에이전트가 사용하는 AI 모델을 제어하여 품질과 비용의 균형을 맞춥니다.
|
||||
|
||||
@@ -762,7 +762,7 @@
|
||||
|
||||
### 29. Todo Management
|
||||
|
||||
**명령어:** `/gsd-add-todo [desc]`, `/gsd-capture --list`
|
||||
**명령어:** `/gsd-capture [desc]`, `/gsd-capture --list`
|
||||
|
||||
**목적:** 세션 중 나중에 처리할 아이디어와 작업을 캡처합니다.
|
||||
|
||||
@@ -1065,7 +1065,7 @@ fix(03-01): correct auth token expiry
|
||||
|
||||
### 43. Backlog Parking Lot
|
||||
|
||||
**명령어:** `/gsd-add-backlog <description>`, `/gsd-review-backlog`, `/gsd-plant-seed <idea>`
|
||||
**명령어:** `/gsd-capture --backlog <description>`, `/gsd-review-backlog`, `/gsd-capture --seed <idea>`
|
||||
|
||||
**목적:** 아직 적극적인 계획에 준비되지 않은 아이디어를 캡처합니다. 백로그 항목은 활성 페이즈 순서 밖에 있기 위해 999.x 번호를 사용합니다. 시드는 올바른 마일스톤에서 자동으로 표시되는 트리거 조건이 있는 미래 지향적 아이디어입니다.
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩
|
||||
|
||||
## 빠른 링크
|
||||
|
||||
- **v1.39의 새로운 기능:** `--minimal` 설치 프로파일(콜드 스타트 ≥94% 감소), `/gsd-edit-phase`, 머지 후 빌드 & 테스트 게이트, `review.models.<cli>` 런타임별 리뷰 모델, 워크스트림 설정 상속, 수동 카나리 릴리스 워크플로, 스킬 통합(86 → 59)
|
||||
- **v1.39의 새로운 기능:** `--minimal` 설치 프로파일(콜드 스타트 ≥94% 감소), `/gsd-phase --edit`, 머지 후 빌드 & 테스트 게이트, `review.models.<cli>` 런타임별 리뷰 모델, 워크스트림 설정 상속, 수동 카나리 릴리스 워크플로, 스킬 통합(86 → 59)
|
||||
- **시작하기:** [README](../README.md) → 설치 → `/gsd-new-project`
|
||||
- **전체 워크플로우 안내:** [User Guide](USER-GUIDE.md)
|
||||
- **모든 명령어 한눈에 보기:** [Command Reference](COMMANDS.md)
|
||||
|
||||
@@ -256,8 +256,8 @@ React/Next.js/Vite 프로젝트에서 `components.json`이 없으면 UI 조사
|
||||
활성 계획에 아직 준비되지 않은 아이디어는 999.x 번호 체계를 사용하여 백로그에 보관하며 활성 페이즈 순서 밖에 유지됩니다.
|
||||
|
||||
```
|
||||
/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
|
||||
/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
|
||||
```
|
||||
|
||||
백로그 항목은 전체 페이즈 디렉터리를 얻으므로 `/gsd-discuss-phase 999.1`로 아이디어를 더 탐구하거나 준비가 되면 `/gsd-plan-phase 999.1`을 사용할 수 있습니다.
|
||||
@@ -269,7 +269,7 @@ React/Next.js/Vite 프로젝트에서 `components.json`이 없으면 UI 조사
|
||||
시드는 트리거 조건이 있는 미래 지향적인 아이디어입니다. 백로그 항목과 달리 시드는 적절한 마일스톤 시점에 자동으로 표면화됩니다.
|
||||
|
||||
```
|
||||
/gsd-plant-seed "Add real-time collab when WebSocket infra is in place"
|
||||
/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
|
||||
```
|
||||
|
||||
시드는 전체 WHY와 언제 표면화할지를 보존합니다. `/gsd-new-milestone`은 모든 시드를 스캔하여 일치 항목을 제시합니다.
|
||||
@@ -288,7 +288,7 @@ React/Next.js/Vite 프로젝트에서 `components.json`이 없으면 UI 조사
|
||||
|
||||
스레드는 `/gsd-pause-work`보다 가볍습니다. 페이즈 상태나 계획 컨텍스트가 없습니다. 각 스레드 파일에는 목표, 컨텍스트, 참조, 다음 단계 섹션이 포함됩니다.
|
||||
|
||||
스레드가 성숙해지면 페이즈(`/gsd-add-phase`)나 백로그 항목(`/gsd-add-backlog`)으로 승격할 수 있습니다.
|
||||
스레드가 성숙해지면 페이즈(`/gsd-phase`)나 백로그 항목(`/gsd-capture --backlog`)으로 승격할 수 있습니다.
|
||||
|
||||
**저장 위치:** `.planning/threads/{slug}.md`
|
||||
|
||||
@@ -413,9 +413,9 @@ GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성합니
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd-add-phase` | 로드맵에 새 페이즈 추가 | 초기 계획 후 범위가 늘어날 때 |
|
||||
| `/gsd-insert-phase [N]` | 긴급 작업 삽입 (소수점 번호 체계) | 마일스톤 중간의 긴급 수정 시 |
|
||||
| `/gsd-remove-phase [N]` | 미래 페이즈 제거 및 재번호 | 기능 범위 축소 시 |
|
||||
| `/gsd-phase` | 로드맵에 새 페이즈 추가 | 초기 계획 후 범위가 늘어날 때 |
|
||||
| `/gsd-phase --insert [N]` | 긴급 작업 삽입 (소수점 번호 체계) | 마일스톤 중간의 긴급 수정 시 |
|
||||
| `/gsd-phase --remove [N]` | 미래 페이즈 제거 및 재번호 | 기능 범위 축소 시 |
|
||||
| `/gsd-list-phase-assumptions [N]` | Claude의 예상 접근 방식 미리 확인 | 계획 전 방향 검증 시 |
|
||||
| `/gsd-plan-phase --research-phase [N]` | 심층 에코시스템 조사만 수행 | 복잡하거나 익숙하지 않은 도메인 |
|
||||
|
||||
@@ -427,10 +427,10 @@ GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성합니
|
||||
| `/gsd-quick` | GSD 보증을 갖춘 임시 작업 | 버그 수정, 소규모 기능, 설정 변경 |
|
||||
| `/gsd-debug [desc]` | 지속적인 상태를 유지하는 체계적인 디버깅 | 문제가 발생했을 때 |
|
||||
| `/gsd-forensics` | 워크플로우 실패에 대한 진단 보고서 | 상태, 아티팩트, git 히스토리가 손상된 것 같을 때 |
|
||||
| `/gsd-add-todo [desc]` | 나중을 위한 아이디어 캡처 | 세션 중에 생각이 날 때 |
|
||||
| `/gsd-capture [desc]` | 나중을 위한 아이디어 캡처 | 세션 중에 생각이 날 때 |
|
||||
| `/gsd-capture --list` | 보류 중인 할 일 목록 | 캡처된 아이디어 검토 시 |
|
||||
| `/gsd-settings` | 워크플로우 토글 및 모델 프로필 설정 | 모델 변경, 에이전트 토글 시 |
|
||||
| `/gsd-set-profile <profile>` | 빠른 프로필 전환 | 비용/품질 트레이드오프 변경 시 |
|
||||
| `/gsd-config --profile <profile>` | 빠른 프로필 전환 | 비용/품질 트레이드오프 변경 시 |
|
||||
| `/gsd-update --reapply` | 업데이트 후 로컬 수정사항 복원 | 로컬 편집이 있는 상태에서 `/gsd-update` 이후 |
|
||||
|
||||
### 코드 품질 및 리뷰
|
||||
@@ -445,9 +445,9 @@ GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성합니
|
||||
|
||||
| 명령어 | 목적 | 사용 시점 |
|
||||
|--------|------|----------|
|
||||
| `/gsd-add-backlog <desc>` | 백로그 파킹 롯에 아이디어 추가 (999.x) | 활성 계획에 준비되지 않은 아이디어 |
|
||||
| `/gsd-capture --backlog <desc>` | 백로그 파킹 롯에 아이디어 추가 (999.x) | 활성 계획에 준비되지 않은 아이디어 |
|
||||
| `/gsd-review-backlog` | 백로그 항목 승격/유지/제거 | 새 마일스톤 전 우선순위 결정 시 |
|
||||
| `/gsd-plant-seed <idea>` | 트리거 조건이 있는 미래 지향적인 아이디어 | 미래 마일스톤에서 표면화되어야 할 아이디어 |
|
||||
| `/gsd-capture --seed <idea>` | 트리거 조건이 있는 미래 지향적인 아이디어 | 미래 마일스톤에서 표면화되어야 할 아이디어 |
|
||||
| `/gsd-thread [name]` | 지속적인 컨텍스트 스레드 | 페이즈 구조 밖의 교차 세션 작업 |
|
||||
|
||||
---
|
||||
@@ -657,11 +657,11 @@ claude --dangerously-skip-permissions
|
||||
### 마일스톤 중간 범위 변경
|
||||
|
||||
```bash
|
||||
/gsd-add-phase # Append a new phase to the roadmap
|
||||
/gsd-phase # Append a new phase to the roadmap
|
||||
# or
|
||||
/gsd-insert-phase 3 # Insert urgent work between phases 3 and 4
|
||||
/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
|
||||
# or
|
||||
/gsd-remove-phase 7 # Descope phase 7 and renumber
|
||||
/gsd-phase --remove 7 # Descope phase 7 and renumber
|
||||
```
|
||||
|
||||
### 멀티 프로젝트 워크스페이스
|
||||
@@ -680,8 +680,8 @@ cd ~/gsd-workspaces/feature-b
|
||||
/gsd-new-project
|
||||
|
||||
# List and manage workspaces
|
||||
/gsd-list-workspaces
|
||||
/gsd-remove-workspace feature-b
|
||||
/gsd-workspace --list
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
각 워크스페이스는 다음을 포함합니다.
|
||||
@@ -719,7 +719,7 @@ cd ~/gsd-workspaces/feature-b
|
||||
|
||||
### 모델 비용이 너무 높은 경우
|
||||
|
||||
예산 프로필로 전환하세요: `/gsd-set-profile budget`. 도메인이 익숙하다면 (또는 Claude에게 익숙하다면) `/gsd-settings`에서 조사 및 plan-check 에이전트를 비활성화하세요.
|
||||
예산 프로필로 전환하세요: `/gsd-config --profile budget`. 도메인이 익숙하다면 (또는 Claude에게 익숙하다면) `/gsd-settings`에서 조사 및 plan-check 에이전트를 비활성화하세요.
|
||||
|
||||
### 비Claude 런타임 사용 (Codex, OpenCode, Gemini CLI, Kilo)
|
||||
|
||||
@@ -744,7 +744,7 @@ cd ~/gsd-workspaces/feature-b
|
||||
|
||||
### 비Anthropic 공급자와 함께 Claude Code 사용 (OpenRouter, 로컬)
|
||||
|
||||
GSD 서브에이전트가 Anthropic 모델을 호출하는데 OpenRouter나 로컬 공급자를 통해 비용을 지불하고 있다면 `inherit` 프로필로 전환하세요: `/gsd-set-profile inherit`. 이렇게 하면 모든 에이전트가 특정 Anthropic 모델 대신 현재 세션 모델을 사용합니다. `/gsd-settings` → Model Profile → Inherit도 참고하세요.
|
||||
GSD 서브에이전트가 Anthropic 모델을 호출하는데 OpenRouter나 로컬 공급자를 통해 비용을 지불하고 있다면 `inherit` 프로필로 전환하세요: `/gsd-config --profile inherit`. 이렇게 하면 모든 에이전트가 특정 Anthropic 모델 대신 현재 세션 모델을 사용합니다. `/gsd-settings` → Model Profile → Inherit도 참고하세요.
|
||||
|
||||
### 민감하거나 비공개 프로젝트에서 작업하는 경우
|
||||
|
||||
@@ -792,12 +792,12 @@ Windows에서 설치 프로그램이 `EPERM: operation not permitted, scandir`
|
||||
|------|----------|
|
||||
| 컨텍스트 손실 / 새 세션 | `/gsd-resume-work` 또는 `/gsd-progress` |
|
||||
| 페이즈가 잘못됨 | 페이즈 커밋에 `git revert` 후 재계획 |
|
||||
| 범위 변경 필요 | `/gsd-add-phase`, `/gsd-insert-phase`, 또는 `/gsd-remove-phase` |
|
||||
| 범위 변경 필요 | `/gsd-phase`, `/gsd-phase --insert`, 또는 `/gsd-phase --remove` |
|
||||
| 무언가 고장남 | `/gsd-debug "description"` |
|
||||
| 워크플로우 상태 손상 의심 | `/gsd-forensics` |
|
||||
| 빠른 목표 수정 | `/gsd-quick` |
|
||||
| 계획이 비전과 맞지 않음 | `/gsd-discuss-phase [N]` 후 재계획 |
|
||||
| 비용이 높아짐 | `/gsd-set-profile budget` 및 `/gsd-settings`에서 에이전트 비활성화 |
|
||||
| 비용이 높아짐 | `/gsd-config --profile budget` 및 `/gsd-settings`에서 에이전트 비활성화 |
|
||||
| 업데이트가 로컬 변경사항 파괴 | `/gsd-update --reapply` |
|
||||
| 이해관계자를 위한 세션 요약 필요 | `/gsd-session-report` |
|
||||
| 다음 단계를 모르겠음 | `/gsd-next` |
|
||||
|
||||
@@ -35,9 +35,9 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
|
||||
|
||||
| Comando | Finalidade |
|
||||
|---------|------------|
|
||||
| `/gsd-add-phase` | Adiciona fase no roadmap |
|
||||
| `/gsd-insert-phase [N]` | Insere trabalho urgente entre fases |
|
||||
| `/gsd-remove-phase [N]` | Remove fase futura e reenumera |
|
||||
| `/gsd-phase` | Adiciona fase no roadmap |
|
||||
| `/gsd-phase --insert [N]` | Insere trabalho urgente entre fases |
|
||||
| `/gsd-phase --remove [N]` | Remove fase futura e reenumera |
|
||||
| `/gsd-list-phase-assumptions [N]` | Mostra abordagem assumida pelo Claude |
|
||||
|
||||
## Brownfield e Utilidades
|
||||
@@ -50,7 +50,7 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
|
||||
| `/gsd-analyze-dependencies` | Detecta dependências entre fases e sugere `Depends on` no ROADMAP.md (v1.32) |
|
||||
| `/gsd-forensics` | Diagnóstico de falhas no workflow |
|
||||
| `/gsd-settings` | Configuração de agentes, perfil e toggles |
|
||||
| `/gsd-set-profile <perfil>` | Troca rápida de perfil de modelo |
|
||||
| `/gsd-config --profile <perfil>` | Troca rápida de perfil de modelo |
|
||||
|
||||
## Qualidade de Código
|
||||
|
||||
@@ -64,9 +64,9 @@ Para detalhes completos de flags avançadas e mudanças recentes, consulte tamb
|
||||
|
||||
| Comando | Finalidade |
|
||||
|---------|------------|
|
||||
| `/gsd-add-backlog <desc>` | Adiciona item no backlog (999.x) |
|
||||
| `/gsd-capture --backlog <desc>` | Adiciona item no backlog (999.x) |
|
||||
| `/gsd-review-backlog` | Promove, mantém ou remove itens |
|
||||
| `/gsd-plant-seed <ideia>` | Registra ideia com gatilho futuro |
|
||||
| `/gsd-capture --seed <ideia>` | Registra ideia com gatilho futuro |
|
||||
| `/gsd-thread [nome]` | Gerencia threads persistentes |
|
||||
|
||||
## Gerenciamento de Estado
|
||||
|
||||
@@ -80,7 +80,7 @@ Esta versão resume os parâmetros principais em Português. Para schema complet
|
||||
Troca rápida:
|
||||
|
||||
```bash
|
||||
/gsd-set-profile budget
|
||||
/gsd-config --profile budget
|
||||
```
|
||||
|
||||
## Novidades de configuração v1.31--v1.32
|
||||
|
||||
@@ -20,7 +20,7 @@ Documentação abrangente do framework Get Shit Done (GSD) — um sistema de met
|
||||
|
||||
## Novidades v1.39
|
||||
|
||||
Perfil de instalação `--minimal` (≥94% de redução no cold-start), `/gsd-edit-phase`, build & test gate pós-merge, `review.models.<cli>` para escolha de modelo de review por runtime, herança de configuração de workstream, workflow manual de canary release, consolidação de skills (86 → 59).
|
||||
Perfil de instalação `--minimal` (≥94% de redução no cold-start), `/gsd-phase --edit`, build & test gate pós-merge, `review.models.<cli>` para escolha de modelo de review por runtime, herança de configuração de workstream, workflow manual de canary release, consolidação de skills (86 → 59).
|
||||
|
||||
## Links rápidos
|
||||
|
||||
|
||||
@@ -92,8 +92,8 @@ Com `workflow.discuss_mode: "assumptions"`, o GSD analisa o código antes de per
|
||||
Ideias fora da sequência ativa vão para backlog:
|
||||
|
||||
```bash
|
||||
/gsd-add-backlog "Camada GraphQL"
|
||||
/gsd-add-backlog "Responsividade mobile"
|
||||
/gsd-capture --backlog "Camada GraphQL"
|
||||
/gsd-capture --backlog "Responsividade mobile"
|
||||
```
|
||||
|
||||
Promover/revisar:
|
||||
@@ -107,7 +107,7 @@ Promover/revisar:
|
||||
Seeds guardam ideias futuras com condição de gatilho:
|
||||
|
||||
```bash
|
||||
/gsd-plant-seed "Adicionar colaboração real-time quando infra de WebSocket estiver pronta"
|
||||
/gsd-capture --seed "Adicionar colaboração real-time quando infra de WebSocket estiver pronta"
|
||||
```
|
||||
|
||||
### Threads persistentes
|
||||
@@ -176,7 +176,7 @@ Para arquivos sensíveis, use deny list no Claude Code.
|
||||
| `/gsd-debug [desc]` | Debug sistemático |
|
||||
| `/gsd-forensics` | Diagnóstico de workflow quebrado |
|
||||
| `/gsd-settings` | Ajustar workflow/modelos |
|
||||
| `/gsd-set-profile <profile>` | Troca rápida de perfil |
|
||||
| `/gsd-config --profile <profile>` | Troca rápida de perfil |
|
||||
|
||||
Para lista completa e flags avançadas, consulte [Command Reference](../COMMANDS.md).
|
||||
|
||||
@@ -279,7 +279,7 @@ Replaneje com escopo menor (tarefas menores por plano).
|
||||
Use perfil budget:
|
||||
|
||||
```bash
|
||||
/gsd-set-profile budget
|
||||
/gsd-config --profile budget
|
||||
```
|
||||
|
||||
### Runtime não-Claude (Codex/OpenCode/Gemini/Kilo)
|
||||
@@ -294,10 +294,10 @@ Use `resolve_model_ids: "omit"` para deixar o runtime resolver modelos padrão.
|
||||
|---------|---------|
|
||||
| Perdeu contexto | `/gsd-resume-work` ou `/gsd-progress` |
|
||||
| Fase deu errado | `git revert` + replanejar |
|
||||
| Precisa alterar escopo | `/gsd-add-phase`, `/gsd-insert-phase`, `/gsd-remove-phase` |
|
||||
| Precisa alterar escopo | `/gsd-phase`, `/gsd-phase --insert`, `/gsd-phase --remove` |
|
||||
| Bug em workflow | `/gsd-forensics` |
|
||||
| Correção pontual | `/gsd-quick` |
|
||||
| Custo alto | `/gsd-set-profile budget` |
|
||||
| Custo alto | `/gsd-config --profile budget` |
|
||||
| Não sabe próximo passo | `/gsd-next` |
|
||||
|
||||
---
|
||||
|
||||
@@ -511,9 +511,9 @@ lmn012o feat(08-02): 创建注册端点
|
||||
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-add-phase` | 向路线图追加阶段 |
|
||||
| `/gsd-insert-phase [N]` | 在阶段之间插入紧急工作 |
|
||||
| `/gsd-remove-phase [N]` | 删除未来阶段，重新编号 |
|
||||
| `/gsd-phase` | 向路线图追加阶段 |
|
||||
| `/gsd-phase --insert [N]` | 在阶段之间插入紧急工作 |
|
||||
| `/gsd-phase --remove [N]` | 删除未来阶段，重新编号 |
|
||||
| `/gsd-list-phase-assumptions [N]` | 规划前查看 Claude 的预期方法 |
|
||||
| `/gsd-autonomous [--from N] [--to N] [--only N]` | 自主执行所有剩余阶段（`--to N` 执行到阶段 N 停止，`--only N` 只执行单个阶段） |
|
||||
| `/gsd-analyze-dependencies` | 检测阶段间依赖关系并建议 ROADMAP.md 的 `Depends on` 条目 |
|
||||
@@ -530,8 +530,8 @@ lmn012o feat(08-02): 创建注册端点
|
||||
| 命令 | 作用 |
|
||||
|---------|--------------|
|
||||
| `/gsd-settings` | 配置模型配置文件和工作流代理 |
|
||||
| `/gsd-set-profile <profile>` | 切换模型配置文件（quality/balanced/budget） |
|
||||
| `/gsd-add-todo [desc]` | 捕获想法留待后用 |
|
||||
| `/gsd-config --profile <profile>` | 切换模型配置文件（quality/balanced/budget/inherit） |
|
||||
| `/gsd-capture [desc]` | 捕获想法留待后用 |
|
||||
| `/gsd-capture --list` | 列出待处理事项 |
|
||||
| `/gsd-debug [desc] [--diagnose]` | 带持久状态的系统化调试（`--diagnose` 仅诊断不修复） |
|
||||
| `/gsd-quick [--full] [--discuss] [--research]` | 用 GSD 保证执行临时任务（`--full` 启用全部阶段，`--discuss` 先收集上下文，`--research` 规划前调查方法） |
|
||||
@@ -564,7 +564,7 @@ GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd-new-project`
|
||||
|
||||
切换配置：
|
||||
```
|
||||
/gsd-set-profile budget
|
||||
/gsd-config --profile budget
|
||||
```
|
||||
|
||||
或通过 `/gsd-settings` 配置。
|
||||
|
||||
@@ -205,9 +205,9 @@
|
||||
|
||||
| 命令 | 用途 | 何时使用 |
|
||||
|---------|---------|-------------|
|
||||
| `/gsd-add-phase` | 向路线图追加新阶段 | 初始规划后范围增长 |
|
||||
| `/gsd-insert-phase [N]` | 插入紧急工作（小数编号） | 里程碑中途紧急修复 |
|
||||
| `/gsd-remove-phase [N]` | 删除未来阶段并重新编号 | 移除某个功能 |
|
||||
| `/gsd-phase` | 向路线图追加新阶段 | 初始规划后范围增长 |
|
||||
| `/gsd-phase --insert [N]` | 插入紧急工作（小数编号） | 里程碑中途紧急修复 |
|
||||
| `/gsd-phase --remove [N]` | 删除未来阶段并重新编号 | 移除某个功能 |
|
||||
| `/gsd-list-phase-assumptions [N]` | 预览 Claude 的预期方法 | 规划前，验证方向 |
|
||||
| `/gsd-plan-phase --research-phase [N]` | 仅深度生态研究 | 复杂或不熟悉的领域 |
|
||||
| `/gsd-autonomous [--from N] [--to N] [--only N]` | 自主执行剩余阶段（`--to N` 到阶段 N 停止） | 批量自动处理 |
|
||||
@@ -229,10 +229,10 @@
|
||||
| `/gsd-map-codebase` | 分析现有代码库 | 在现有代码上运行 `/gsd-new-project` 之前 |
|
||||
| `/gsd-quick` | 带 GSD 保证的临时任务 | Bug 修复、小功能、配置更改 |
|
||||
| `/gsd-debug [desc] [--diagnose]` | 带持久状态的系统化调试（`--diagnose` 仅诊断） | 出问题时 |
|
||||
| `/gsd-add-todo [desc]` | 捕获想法留待后用 | 会话期间想到什么 |
|
||||
| `/gsd-capture [desc]` | 捕获想法留待后用 | 会话期间想到什么 |
|
||||
| `/gsd-capture --list` | 列出待处理事项 | 查看捕获的想法 |
|
||||
| `/gsd-settings` | 配置工作流开关和模型配置 | 更改模型、切换代理 |
|
||||
| `/gsd-set-profile <profile>` | 快速切换配置 | 更改成本/质量权衡 |
|
||||
| `/gsd-config --profile <profile>` | 快速切换配置 | 更改成本/质量权衡 |
|
||||
| `/gsd-update --reapply` | 更新后恢复本地修改 | 如果你有本地编辑，在 `/gsd-update` 后 |
|
||||
|
||||
---
|
||||
@@ -403,11 +403,11 @@ claude --dangerously-skip-permissions
|
||||
### 里程碑中途范围变更
|
||||
|
||||
```bash
|
||||
/gsd-add-phase # 向路线图追加新阶段
|
||||
/gsd-phase # 向路线图追加新阶段
|
||||
# 或
|
||||
/gsd-insert-phase 3 # 在阶段 3 和 4 之间插入紧急工作
|
||||
/gsd-phase --insert 3 # 在阶段 3 和 4 之间插入紧急工作
|
||||
# 或
|
||||
/gsd-remove-phase 7 # 移除阶段 7 并重新编号
|
||||
/gsd-phase --remove 7 # 移除阶段 7 并重新编号
|
||||
```
|
||||
|
||||
---
|
||||
@@ -456,7 +456,7 @@ node gsd-tools.cjs state sync # 从磁盘重建 STATE.md
|
||||
|
||||
### 模型成本太高
|
||||
|
||||
切换到 budget 配置：`/gsd-set-profile budget`。如果领域对你（或 Claude）熟悉，通过 `/gsd-settings` 禁用研究和计划检查代理。
|
||||
切换到 budget 配置：`/gsd-config --profile budget`。如果领域对你（或 Claude）熟悉，通过 `/gsd-settings` 禁用研究和计划检查代理。
|
||||
|
||||
### 处理敏感/私有项目
|
||||
|
||||
@@ -478,12 +478,12 @@ node gsd-tools.cjs state sync # 从磁盘重建 STATE.md
|
||||
|---------|----------|
|
||||
| 丢失上下文 / 新会话 | `/gsd-resume-work` 或 `/gsd-progress` |
|
||||
| 阶段出错 | `git revert` 阶段提交，然后重新规划 |
|
||||
| 需要更改范围 | `/gsd-add-phase`、`/gsd-insert-phase` 或 `/gsd-remove-phase` |
|
||||
| 需要更改范围 | `/gsd-phase`、`/gsd-phase --insert` 或 `/gsd-phase --remove` |
|
||||
| 出问题了 | `/gsd-debug "描述"` |
|
||||
| STATE.md 不同步 | `state validate` 然后 `state sync` |
|
||||
| 快速针对性修复 | `/gsd-quick` |
|
||||
| 计划与你的愿景不符 | `/gsd-discuss-phase [N]` 然后重新规划 |
|
||||
| 成本过高 | `/gsd-set-profile budget` 和 `/gsd-settings` 关闭代理 |
|
||||
| 成本过高 | `/gsd-config --profile budget` 和 `/gsd-settings` 关闭代理 |
|
||||
| 更新破坏了本地更改 | `/gsd-update --reapply` |
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user