@opengsd/gsd-core 1.2.0-rc.1

package/commands/gsd/ship.md

@@ -0,0 +1,24 @@
+---
+name: gsd:ship
+description: Create PR, run review, and prepare for merge after verification passes
+argument-hint: "[phase number or milestone, e.g., '4' or 'v1.0']"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Write
+  - AskUserQuestion
+requires: [review, verify-work]
+---
+<objective>
+Bridge local completion → merged PR. After /gsd:verify-work passes, ship the work: push branch, create PR with auto-generated body, optionally trigger review, and track the merge.
+
+Closes the plan → execute → verify → ship loop.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/ship.md
+</execution_context>
+
+Execute the ship workflow from @~/.claude/get-shit-done/workflows/ship.md end-to-end.

package/commands/gsd/sketch.md

@@ -0,0 +1,60 @@
+---
+name: gsd:sketch
+description: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
+argument-hint: "[design idea to explore] [--quick] [--text] [--wrap-up] or [frontier]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+requires: [spike]
+---
+<objective>
+Explore design directions through throwaway HTML mockups before committing to implementation.
+Each sketch produces 2-3 variants for comparison. Sketches live in `.planning/sketches/` and
+integrate with GSD commit patterns, state tracking, and handoff workflows. Loads spike
+findings to ground mockups in real data shapes and validated interaction patterns.
+
+Two modes:
+- **Idea mode** (default) — describe a design idea to sketch
+- **Frontier mode** (no argument or "frontier") — analyzes existing sketch landscape and proposes consistency and frontier sketches
+
+Does not require prior new-project setup — auto-creates `.planning/sketches/` if needed.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/sketch.md
+@~/.claude/get-shit-done/workflows/sketch-wrap-up.md
+@~/.claude/get-shit-done/references/ui-brand.md
+@~/.claude/get-shit-done/references/sketch-theme-system.md
+@~/.claude/get-shit-done/references/sketch-interactivity.md
+@~/.claude/get-shit-done/references/sketch-tooling.md
+@~/.claude/get-shit-done/references/sketch-variant-patterns.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
+</runtime_note>
+
+<context>
+Design idea: $ARGUMENTS
+
+**Available flags:**
+- `--quick` — Skip mood/direction intake, jump straight to decomposition and building. Use when the design direction is already clear.
+- `--wrap-up` — Package sketch design findings into a persistent project skill for future build conversations. Runs the sketch-wrap-up workflow.
+</context>
+
+<process>
+Parse the first token of $ARGUMENTS:
+- If it is `--wrap-up`: strip the flag, execute the sketch-wrap-up workflow end-to-end.
+- Otherwise: execute the sketch workflow end-to-end.
+
+Preserve all workflow gates (intake, decomposition, target stack research, variant evaluation, MANIFEST updates, commit patterns).
+</process>

package/commands/gsd/spec-phase.md

@@ -0,0 +1,63 @@
+---
+name: gsd:spec-phase
+description: Clarify WHAT a phase delivers with ambiguity scoring; produces a SPEC.md before discuss-phase.
+argument-hint: "<phase> [--auto] [--text]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+requires: [discuss-phase, execute-phase, phase, plan-phase]
+---
+
+<objective>
+Clarify phase requirements through structured Socratic questioning with quantitative ambiguity scoring.
+
+**Position in workflow:** `spec-phase → discuss-phase → plan-phase → execute-phase → verify`
+
+**How it works:**
+1. Load phase context (PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md)
+2. Scout the codebase — understand current state before asking questions
+3. Run Socratic interview loop (up to 6 rounds, rotating perspectives)
+4. Score ambiguity across 4 weighted dimensions after each round
+5. Gate: ambiguity ≤ 0.20 AND all dimensions meet minimums → write SPEC.md
+6. Commit SPEC.md — discuss-phase picks it up automatically on next run
+
+**Output:** `{phase_dir}/{padded_phase}-SPEC.md` — falsifiable requirements that lock "what/why" before discuss-phase handles "how"
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/spec-phase.md
+@~/.claude/get-shit-done/templates/spec.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+</runtime_note>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+**Flags:**
+- `--auto` — Skip interactive questions; Claude selects recommended defaults and writes SPEC.md
+- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
+
+Context files are resolved in-workflow using `init phase-op`.
+</context>
+
+<process>
+Execute end-to-end.
+
+**MANDATORY:** Read the workflow file BEFORE taking any action. The workflow contains the complete step-by-step process including the Socratic interview loop, ambiguity scoring gate, and SPEC.md generation. Do not improvise from the objective summary above.
+</process>
+
+<success_criteria>
+- Codebase scouted for current state before questioning begins
+- All 4 ambiguity dimensions scored after each interview round
+- Gate passed: ambiguity ≤ 0.20 AND all dimension minimums met
+- SPEC.md written with falsifiable requirements, explicit boundaries, and acceptance criteria
+- SPEC.md committed atomically
+- User knows they can now run /gsd:discuss-phase which will load SPEC.md automatically
+</success_criteria>

package/commands/gsd/spike.md

@@ -0,0 +1,57 @@
+---
+name: gsd:spike
+description: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
+argument-hint: "[idea to validate] [--quick] [--text] [--wrap-up] or [frontier]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+requires: []
+---
+<objective>
+Spike an idea through experiential exploration — build focused experiments to feel the pieces
+of a future app, validate feasibility, and produce verified knowledge for the real build.
+Spikes live in `.planning/spikes/` and integrate with GSD commit patterns, state tracking,
+and handoff workflows.
+
+Two modes:
+- **Idea mode** (default) — describe an idea to spike
+- **Frontier mode** (no argument or "frontier") — analyzes existing spike landscape and proposes integration and frontier spikes
+
+Does not require prior new-project setup — auto-creates `.planning/spikes/` if needed.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/spike.md
+@~/.claude/get-shit-done/workflows/spike-wrap-up.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
+</runtime_note>
+
+<context>
+Idea: $ARGUMENTS
+
+**Available flags:**
+- `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike.
+- `--text` — Use plain-text numbered lists instead of AskUserQuestion (for non-Claude runtimes).
+- `--wrap-up` — Package spike findings into a persistent project skill for future build conversations. Runs the spike-wrap-up workflow.
+</context>
+
+<process>
+Parse the first token of $ARGUMENTS:
+- If it is `--wrap-up`: strip the flag, execute the spike-wrap-up workflow
+- Otherwise: pass all of $ARGUMENTS as the idea to the spike workflow end-to-end.
+
+Preserve all workflow gates (prior spike check, decomposition, research, risk ordering, observability assessment, verification, MANIFEST updates, commit patterns).
+</process>

package/commands/gsd/stats.md

@@ -0,0 +1,19 @@
+---
+name: gsd:stats
+description: Display project statistics — phases, plans, requirements, git metrics, and timeline
+allowed-tools:
+  - Read
+  - Bash
+requires: [phase, progress]
+---
+<objective>
+Display comprehensive project statistics including phase progress, plan execution metrics, requirements completion, git history stats, and project timeline.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/stats.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

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
+`get-shit-done/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 get-shit-done` 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/get-shit-done/bin/lib/surface.cjs`
+Cluster definitions: `~/.claude/get-shit-done/bin/lib/clusters.cjs`
+</execution_context>

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/get-shit-done/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/get-shit-done/workflows/ui-phase.md
+@~/.claude/get-shit-done/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/get-shit-done/workflows/ui-review.md
+@~/.claude/get-shit-done/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/get-shit-done/workflows/ultraplan-phase.md
+@~/.claude/get-shit-done/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/get-shit-done/workflows/undo.md
+@~/.claude/get-shit-done/references/ui-brand.md
+@~/.claude/get-shit-done/references/gate-prompts.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/gsd/update.md

@@ -0,0 +1,48 @@
+---
+name: gsd:update
+description: Update GSD to latest version with changelog display
+argument-hint: "[--sync | --reapply]"
+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/get-shit-done/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.
+- **(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: execute the update workflow end-to-end.
+
+</process>
+
+<execution_context_extended>
+@~/.claude/get-shit-done/workflows/sync-skills.md
+@~/.claude/get-shit-done/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/get-shit-done/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/get-shit-done/workflows/verify-work.md
+@~/.claude/get-shit-done/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>