@therocketcode/gsd-core 1.4.0

package/commands/gsd/surface.md

@@ -0,0 +1,155 @@
+---
+name: gsd:surface
+description: Toggle which skills are surfaced — apply a profile, list, or disable a cluster without reinstall
+argument-hint: "[list|status|profile <name>|disable <cluster>|enable <cluster>|reset]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+requires: [config, update]
+---
+
+<objective>
+Manage the runtime skill surface without reinstall. Reads/writes `~/.claude/.gsd-surface.json`
+(sibling to `~/.claude/.gsd-profile`) and re-stages the active skills directory in place.
+Skill dirs live at `~/.claude/skills/gsd-*/`.
+
+Sub-commands: list · status · profile · disable · enable · reset
+</objective>
+
+## Sub-command routing
+
+Parse the first token of $ARGUMENTS:
+
+| Token | Action |
+|---|---|
+| `list` | Show enabled + disabled clusters and skills |
+| `status` | Alias for `list` plus token cost summary |
+| `profile <name>` | Write `baseProfile` and re-stage |
+| `profile <n1>,<n2>` | Composed profiles (comma-separated, no spaces) |
+| `disable <cluster>` | Add cluster to `disabledClusters`, re-stage |
+| `enable <cluster>` | Remove cluster from `disabledClusters`, re-stage |
+| `reset` | Delete `.gsd-surface.json`, return to install-time profile |
+| *(none)* | Treat as `list` |
+
+---
+
+## list / status
+
+Call `listSurface(runtimeConfigDir, manifest, CLUSTERS)` from
+`gsd-core/bin/lib/surface.cjs`. Display:
+
+```
+Enabled (N skills, ~T tokens):
+  core_loop:   new-project  discuss-phase  plan-phase  execute-phase  help  update
+  audit_review: …
+  …
+
+Disabled:
+  utility:  health  stats  settings  …
+
+Token cost: ~T (budget cap ~500 tokens for 200k context @ 1%)
+```
+
+For `status` also append:
+
+```
+Base profile:   standard  (from .gsd-surface.json)
+Install profile: standard  (from .gsd-profile)
+```
+
+---
+
+## profile \<name\>
+
+1. Read current surface: `readSurface(runtimeConfigDir)` → if null, seed from `readActiveProfile(runtimeConfigDir)`.
+2. Set `surfaceState.baseProfile = name`.
+3. `writeSurface(runtimeConfigDir, surfaceState)`.
+4. Resolve and re-apply:
+   ```js
+   const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
+   applySurface(runtimeConfigDir, layout, manifest, CLUSTERS);
+   ```
+5. Confirm: "Surface updated to profile `<name>`. N skills enabled."
+
+---
+
+## disable \<cluster\>
+
+Valid cluster names: `core_loop`, `audit_review`, `milestone`, `research_ideate`,
+`workspace_state`, `docs`, `ui`, `ai_eval`, `ns_meta`, `utility`.
+
+1. Validate cluster name against `Object.keys(CLUSTERS)`.
+2. Read or initialize surface state.
+3. Add cluster to `surfaceState.disabledClusters` (deduplicate).
+4. `writeSurface` → resolve layout → `applySurface`:
+   ```js
+   const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
+   applySurface(runtimeConfigDir, layout, manifest, CLUSTERS);
+   ```
+5. Confirm: "Disabled cluster `<cluster>`. N skills removed from surface."
+
+---
+
+## enable \<cluster\>
+
+1. Read surface state; if null, nothing to enable — print "No surface delta active."
+2. Remove cluster from `surfaceState.disabledClusters`.
+3. `writeSurface` → resolve layout → `applySurface`:
+   ```js
+   const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
+   applySurface(runtimeConfigDir, layout, manifest, CLUSTERS);
+   ```
+4. Confirm: "Enabled cluster `<cluster>`. N skills added back to surface."
+
+---
+
+## reset
+
+1. Check if `.gsd-surface.json` exists.
+2. Delete it.
+3. Re-apply using only `readActiveProfile(runtimeConfigDir)` (install-time profile).
+4. Confirm: "Surface reset to install-time profile `<name>`."
+
+---
+
+## runtimeConfigDir resolution
+
+The `runtimeConfigDir` for `applySurface` is the **base Claude config directory**
+(`~/.claude`), NOT the skills sub-directory (`~/.claude/skills`).
+
+This matches `installRuntimeArtifacts` and `uninstallRuntimeArtifacts`, which also
+receive `~/.claude` as `configDir`. The skill dirs themselves live at
+`~/.claude/skills/gsd-*/` because the `claude global` layout has `destSubpath =
+'skills'` — they are derived from `configDir`, not the root for it.
+
+```bash
+# Claude Code — global install
+RUNTIME_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+SCOPE="global"
+
+# Artifact destinations are derived from runtime layout
+# via resolveRuntimeArtifactLayout(runtime, RUNTIME_CONFIG_DIR, SCOPE)
+# then applySurface(RUNTIME_CONFIG_DIR, layout, manifest, CLUSTERS)
+```
+
+Surface state is stored at `${RUNTIME_CONFIG_DIR}/.gsd-surface.json`
+(i.e. `~/.claude/.gsd-surface.json`).
+
+All paths can be overridden by reading the `CLAUDE_CONFIG_DIR` env var if set.
+
+---
+
+## Error handling
+
+- Unknown cluster name → list valid cluster names, exit without writing.
+- Unknown profile name → list known profiles (`core`, `standard`, `full`), exit.
+- Missing `surface.cjs` → prompt: "Run `npm i -g gsd-core` to reinstall GSD."
+
+<execution_context>
+Surface state file: `~/.claude/.gsd-surface.json`
+Install profile marker: `~/.claude/.gsd-profile`
+Skill dirs: `~/.claude/skills/gsd-*/`
+Engine module: `~/.claude/gsd-core/bin/lib/surface.cjs`
+Cluster definitions: `~/.claude/gsd-core/bin/lib/clusters.cjs`
+</execution_context>

package/commands/gsd/testing-strategy.md

@@ -0,0 +1,65 @@
+---
+name: gsd:testing-strategy
+description: Recommend a test strategy matched to the architecture — test shape, levels, and what to test.
+argument-hint: "[--auto] [--text]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+requires: [recommend-architecture, add-tests, plan-phase]
+---
+
+<objective>
+Decide WHAT to test, at WHICH level, and HOW MUCH — matched to the architecture — and capture it so execution and add-tests follow a coherent shape. Extends the project's existing test rigor (TESTING-STANDARDS.md), it does not replace it.
+
+**Position in workflow:** `recommend-architecture → testing-strategy → plan-phase / execute-phase`
+
+**How it works:**
+1. Load the architecture decision (ADR / SKELETON) and DOMAIN-MODEL
+2. Derive the test-level emphasis per subdomain — shape FOLLOWS architecture (rich core → unit; CRUD-over-DB → integration)
+3. Identify the gnarly bits to unit-test (money, state machines, parsers) and what NOT to test
+4. Pick the persistent critical-path e2e smoke list; set coverage-as-floor + mutation + TDD stance
+5. Write TEST-STRATEGY.md and commit
+
+**Output:** `.planning/TEST-STRATEGY.md` — level emphasis per subdomain, unit-test targets, no-duplicate-coverage rules, the persistent e2e smoke list, coverage/mutation stance, and TDD stance. Feeds add-tests, execute-phase, and plan-phase.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/testing-strategy.md
+@~/.claude/gsd-core/references/test-strategy.md
+@~/.claude/gsd-core/templates/test-strategy.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+</runtime_note>
+
+<context>
+**Flags:**
+- `--auto` — Skip interactive questions; synthesize the strategy from the ADR / DOMAIN-MODEL using the consensus defaults (behavior-first, sociable, shape-follows-architecture).
+- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions).
+
+**When to run:** after `/gsd:recommend-architecture` (it consumes the architecture decision), before planning/execution. Works without an ADR too — it will ask briefly about the architecture.
+
+Context files are resolved in-workflow during initialization.
+</context>
+
+<process>
+Execute end-to-end.
+
+**MANDATORY:** Read the workflow file BEFORE taking any action. It contains the full process: deriving the shape FROM the architecture (not picking a pyramid/diamond), the behavior-over-implementation + sociable-by-default rules, test-once-at-cheapest-level, the gnarly-bits list, persistent-vs-transient e2e, coverage-as-floor + mutation, and TDD stance. Do not improvise from the objective summary above. The shape is an OUTPUT of the architecture, never a target you pick; default to sociable tests and mock only at architectural boundaries; keep all existing TESTING-STANDARDS.md standards.
+</process>
+
+<success_criteria>
+- Architecture decision (ADR/SKELETON) and DOMAIN-MODEL loaded; shape derived FROM it (not a picked pyramid/diamond)
+- Per-subdomain level emphasis recorded with the architecture rung that justifies it
+- Gnarly bits to unit-test identified (money/state-machines/parsers); what-not-to-test stated; no duplicate coverage
+- Persistent critical-path e2e smoke list set; transient e2e distinguished
+- Coverage-as-floor + mutation targets + TDD stance (behavior + small increments; test-first knob) recorded
+- Existing TESTING-STANDARDS.md rigor preserved (sociable default, mock only at ports)
+- TEST-STRATEGY.md written and committed (when commit_docs is true)
+- User directed to /gsd:plan-phase
+</success_criteria>

package/commands/gsd/thread.md

@@ -0,0 +1,24 @@
+---
+name: gsd:thread
+description: Manage persistent context threads for cross-session work
+argument-hint: "[list [--open | --resolved] | close <slug> | status <slug> | name | description]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+requires: [phase]
+---
+
+<objective>
+Create, list, close, or resume persistent context threads. Threads are lightweight
+cross-session knowledge stores for work that spans multiple sessions but
+doesn't belong to any specific phase.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/thread.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/gsd/ui-phase.md

@@ -0,0 +1,35 @@
+---
+name: gsd:ui-phase
+description: Generate UI design contract (UI-SPEC.md) for frontend phases
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - WebFetch
+  - AskUserQuestion
+  - mcp__context7__*
+requires: [phase]
+---
+<objective>
+Create a UI design contract (UI-SPEC.md) for a frontend phase.
+Orchestrates gsd-ui-researcher and gsd-ui-checker.
+Flow: Validate → Research UI → Verify UI-SPEC → Done
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/ui-phase.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates.
+</process>

package/commands/gsd/ui-review.md

@@ -0,0 +1,33 @@
+---
+name: gsd:ui-review
+description: Retroactive 6-pillar visual audit of implemented frontend code
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [phase]
+---
+<objective>
+Conduct a retroactive 6-pillar visual audit. Produces UI-REVIEW.md with
+graded assessment (1-4 per pillar). Works on any project.
+Output: {phase_num}-UI-REVIEW.md
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/ui-review.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates.
+</process>

package/commands/gsd/ultraplan-phase.md

@@ -0,0 +1,34 @@
+---
+name: gsd:ultraplan-phase
+description: "[BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back."
+argument-hint: "[phase-number]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+requires: [import, phase, plan-phase]
+---
+
+<objective>
+Offload GSD's plan phase to Claude Code's ultraplan cloud infrastructure.
+
+Ultraplan drafts the plan in a remote cloud session while your terminal stays free.
+Review and comment on the plan in your browser, then import it back via /gsd:import --from.
+
+⚠ BETA: ultraplan is in research preview. Use /gsd:plan-phase for stable local planning.
+Requirements: Claude Code v2.1.91+, claude.ai account, GitHub repository.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/ultraplan-phase.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the ultraplan-phase workflow end-to-end.
+</process>

package/commands/gsd/undo.md

@@ -0,0 +1,35 @@
+---
+name: gsd:undo
+description: "Safe git revert. Roll back phase or plan commits using the phase manifest with dependency checks."
+argument-hint: "--last N | --phase NN | --plan NN-MM"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+requires: [phase]
+---
+
+<objective>
+Safe git revert — roll back GSD phase or plan commits using the phase manifest, with dependency checks and a confirmation gate before execution.
+
+Three modes:
+- **--last N**: Show recent GSD commits for interactive selection
+- **--phase NN**: Revert all commits for a phase (manifest + git log fallback)
+- **--plan NN-MM**: Revert all commits for a specific plan
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/undo.md
+@~/.claude/gsd-core/references/ui-brand.md
+@~/.claude/gsd-core/references/gate-prompts.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/gsd/update.md

@@ -0,0 +1,49 @@
+---
+name: gsd:update
+description: Update GSD to latest version with changelog display
+argument-hint: "[--sync | --reapply | --next | --rc]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Check for GSD updates, install if available, and display what changed.
+
+Routes to the update workflow which handles:
+- Version detection (local vs global installation)
+- npm version checking
+- Changelog fetching and display
+- User confirmation with clean install warning
+- Update execution and cache clearing
+- Restart reminder
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/update.md
+</execution_context>
+
+<flags>
+- **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
+- **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+- **--next** (alias **--rc**): Target the `@next` RC dist-tag instead of `@latest` so you can install or refresh a release candidate (e.g. `1.4.0-rc.1`) through the normal update flow — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all still apply. Omitting it keeps targeting `@latest` (no change). See ADR #660 for the RC channel.
+- **(no flag)**: Standard update — check for new version, show changelog, install.
+</flags>
+
+<process>
+Parse the first token of $ARGUMENTS:
+- If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
+- If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
+- Otherwise (including `--next` / `--rc`): execute the update workflow end-to-end, passing `$ARGUMENTS` through so the workflow's parse_update_channel step can select the release channel.
+
+</process>
+
+<execution_context_extended>
+@~/.claude/gsd-core/workflows/sync-skills.md
+@~/.claude/gsd-core/workflows/reapply-patches.md
+</execution_context_extended>

package/commands/gsd/validate-phase.md

@@ -0,0 +1,36 @@
+---
+name: gsd:validate-phase
+description: Retroactively audit and fill Nyquist validation gaps for a completed phase
+argument-hint: "[phase number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [phase]
+---
+<objective>
+Audit Nyquist validation coverage for a completed phase. Three states:
+- (A) VALIDATION.md exists — audit and fill gaps
+- (B) No VALIDATION.md, SUMMARY.md exists — reconstruct from artifacts
+- (C) Phase not executed — exit with guidance
+
+Output: updated VALIDATION.md + generated test files.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/validate-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates.
+</process>

package/commands/gsd/verify-work.md

@@ -0,0 +1,39 @@
+---
+name: gsd:verify-work
+description: Validate built features through conversational UAT
+argument-hint: "[phase number, e.g., '4'] [--ws <name>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - Agent
+requires: [execute-phase, phase]
+---
+<objective>
+Validate built features through conversational testing with persistent state.
+
+Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.
+
+Output: {phase_num}-UAT.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /gsd:execute-phase
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/verify-work.md
+@~/.claude/gsd-core/templates/UAT.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS (optional)
+- If provided: Test specific phase (e.g., "4")
+- If not provided: Check for active sessions or prompt for phase
+
+Context files are resolved inside the workflow (`init verify-work`) and delegated via `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates (session management, test presentation, diagnosis, fix planning, routing).
+</process>

package/commands/gsd/workspace.md

@@ -0,0 +1,52 @@
+---
+name: gsd:workspace
+description: Manage GSD workspaces — create, list, or remove isolated workspace environments
+argument-hint: "[--new | --list | --remove] [name]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Manage GSD workspaces with a single consolidated command.
+
+Mode routing:
+- **--new**: Create an isolated workspace with repo copies and independent .planning/ → new-workspace workflow
+- **--list**: List active GSD workspaces and their status → list-workspaces workflow
+- **--remove**: Remove a GSD workspace and clean up worktrees → remove-workspace workflow
+</objective>
+
+<routing>
+
+| Flag | Action | Workflow |
+|------|--------|----------|
+| --new | Create workspace with worktree/clone strategy | new-workspace |
+| --list | Scan ~/gsd-workspaces/, show summary table | list-workspaces |
+| --remove | Confirm and remove workspace directory | remove-workspace |
+
+</routing>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/new-workspace.md
+@~/.claude/gsd-core/workflows/list-workspaces.md
+@~/.claude/gsd-core/workflows/remove-workspace.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--new`: strip the flag, pass remainder (--name, --repos, --path, --strategy, --branch, --auto flags) to new-workspace workflow
+- If it is `--list`: execute list-workspaces workflow (no argument needed)
+- If it is `--remove`: strip the flag, pass remainder (workspace-name) to remove-workspace workflow
+- Otherwise (no flag): show usage — one of --new, --list, or --remove is required
+</context>
+
+<process>
+1. Parse the leading flag from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end based on the routing table above.
+3. Preserve all workflow gates from the target workflow (validation, approvals, commits, routing).
+</process>

package/commands/gsd/workstreams.md

@@ -0,0 +1,70 @@
+---
+name: gsd:workstreams
+description: Manage parallel workstreams — list, create, switch, status, progress, complete, and resume
+allowed-tools:
+  - Read
+  - Bash
+requires: [new-milestone, phase, progress, resume-work]
+---
+
+# /gsd:workstreams
+
+Manage parallel workstreams for concurrent milestone work.
+
+## Usage
+
+`/gsd:workstreams [subcommand] [args]`
+
+### Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `list` | List all workstreams with status |
+| `create <name>` | Create a new workstream |
+| `status <name>` | Detailed status for one workstream |
+| `switch <name>` | Set active workstream |
+| `progress` | Progress summary across all workstreams |
+| `complete <name>` | Archive a completed workstream |
+| `resume <name>` | Resume work in a workstream |
+
+## Step 1: Parse Subcommand
+
+Parse the user's input to determine which workstream operation to perform.
+If no subcommand given, default to `list`.
+
+## Step 2: Execute Operation
+
+### list
+Run: `gsd-tools query workstream.list --raw --cwd "$CWD"`
+Display the workstreams in a table format showing name, status, current phase, and progress.
+
+### create
+Run: `gsd-tools query workstream.create <name> --raw --cwd "$CWD"`
+After creation, display the new workstream path and suggest next steps:
+- `/gsd:new-milestone --ws <name>` to set up the milestone
+
+### status
+Run: `gsd-tools query workstream.status <name> --raw --cwd "$CWD"`
+Display detailed phase breakdown and state information.
+
+### switch
+Run: `gsd-tools query workstream.set <name> --raw --cwd "$CWD"`
+Also set `GSD_WORKSTREAM` for the current session when the runtime supports it.
+If the runtime exposes a session identifier, GSD also stores the active workstream
+session-locally so concurrent sessions do not overwrite each other.
+
+### progress
+Run: `gsd-tools query workstream.progress --raw --cwd "$CWD"`
+Display a progress overview across all workstreams.
+
+### complete
+Run: `gsd-tools query workstream.complete <name> --raw --cwd "$CWD"`
+Archive the workstream to milestones/.
+
+### resume
+Set the workstream as active and suggest `/gsd:resume-work --ws <name>`.
+
+## Step 3: Display Results
+
+Format the JSON output from gsd-tools query into a human-readable display.
+Include the `${GSD_WS}` flag in any routing suggestions.

package/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "gsd-core",
+  "version": "1.4.0",
+  "description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
+  "contextFileName": "GEMINI.md"
+}