docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
218
docs/how-to/configure-model-profiles.md
Normal file
218
docs/how-to/configure-model-profiles.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# How to configure model profiles
|
||||
|
||||
Choose the right model tier strategy for your project, then tune individual agents or entire phase types without writing a large override block. This guide starts with the simplest lever and works up to dynamic routing.
|
||||
|
||||
---
|
||||
|
||||
## The four profiles (plus `adaptive` and `inherit`)
|
||||
|
||||
Set `model_profile` in `.planning/config.json` or via `/gsd-config --profile <name>`:
|
||||
|
||||
| Profile | Planner | Executor | Researchers | Verifier | Use when |
|
||||
|---------|---------|----------|-------------|----------|----------|
|
||||
| `quality` | Opus | Opus | Opus | Sonnet | Production-quality work where cost is secondary |
|
||||
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | Normal development — the default |
|
||||
| `budget` | Sonnet | Sonnet | Haiku | Haiku | Rapid prototyping, cost-sensitive contexts |
|
||||
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | Resolves the same way as the other tiers under runtime-aware profiles; use when switching between runtimes frequently |
|
||||
| `inherit` | (session model) | (session model) | (session model) | (session model) | Non-Anthropic providers (OpenRouter, local models) — all agents follow your current session model |
|
||||
|
||||
The table above shows a representative subset. All 33 shipped agents have explicit per-profile tier assignments in `sdk/shared/model-catalog.json`. For the full table see [Model Profiles](../CONFIGURATION.md#model-profiles) in the configuration reference.
|
||||
|
||||
**Quick switch via command:**
|
||||
|
||||
```bash
|
||||
/gsd-config --profile balanced # Normal development
|
||||
/gsd-config --profile budget # Prototyping or high-cost phases
|
||||
/gsd-config --profile quality # Production release
|
||||
/gsd-config --profile inherit # OpenRouter, local models
|
||||
```
|
||||
|
||||
**Or edit `.planning/config.json` directly:**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Per-agent overrides (`model_overrides`)
|
||||
|
||||
If a single agent needs a different tier without changing the whole profile, use `model_overrides`:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"model_overrides": {
|
||||
"gsd-executor": "opus",
|
||||
"gsd-codebase-mapper": "haiku"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g. `"openai/o3"`, `"google/gemini-2.5-pro"`).
|
||||
|
||||
`model_overrides` can be set per-project in `.planning/config.json` or globally in `~/.gsd/defaults.json`. Per-project entries win on conflict; non-conflicting global entries are preserved.
|
||||
|
||||
**Important for Codex and OpenCode:** Those runtimes embed the resolved model into each agent's static config at install time. After editing `model_overrides`, re-run the installer for the change to take effect:
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Per-phase-type models (`models`)
|
||||
|
||||
If you want to say "Opus for planning, Sonnet for everything else" without learning all 33 agent names, use the `models` block. It maps six phase types to tier aliases:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"models": {
|
||||
"planning": "opus",
|
||||
"discuss": "opus",
|
||||
"research": "sonnet",
|
||||
"execution": "opus",
|
||||
"verification": "sonnet",
|
||||
"completion": "sonnet"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Phase types and their agents:
|
||||
|
||||
| Phase type | Agents covered |
|
||||
|---|---|
|
||||
| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
|
||||
| `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-codebase-mapper`, `gsd-ui-researcher` |
|
||||
| `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` |
|
||||
| `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker`, `gsd-ui-auditor`, `gsd-doc-verifier` |
|
||||
| `discuss`, `completion` | Reserved — no subagent today; accepted by schema for forward compatibility |
|
||||
|
||||
The `models` block accepts tier aliases only (`opus`, `sonnet`, `haiku`, `inherit`). For a fully-qualified model ID, use `model_overrides` per agent instead.
|
||||
|
||||
**Combining `models` with a per-agent exception:**
|
||||
|
||||
```json
|
||||
{
|
||||
"model_profile": "balanced",
|
||||
"models": {
|
||||
"research": "sonnet"
|
||||
},
|
||||
"model_overrides": {
|
||||
"gsd-codebase-mapper": "haiku"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
All five research agents resolve to `sonnet` *except* `gsd-codebase-mapper`, which is pinned to `haiku`.
|
||||
|
||||
---
|
||||
|
||||
## Dynamic routing — start cheap, escalate on failure
|
||||
|
||||
If you want to pay for cheaper tiers by default and only escalate when an agent fails a quality gate, enable `dynamic_routing`:
|
||||
|
||||
```json
|
||||
{
|
||||
"dynamic_routing": {
|
||||
"enabled": true,
|
||||
"tier_models": {
|
||||
"light": "haiku",
|
||||
"standard": "sonnet",
|
||||
"heavy": "opus"
|
||||
},
|
||||
"escalate_on_failure": true,
|
||||
"max_escalations": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Each agent has a default tier (`light`, `standard`, or `heavy`). On the first attempt, GSD picks `tier_models[default_tier]`. If the orchestrator detects a soft failure (verification inconclusive, plan-check flagged, etc.), it re-spawns the agent one tier up. `max_escalations` caps the total retries.
|
||||
|
||||
Agents that already sit at `heavy` cannot escalate further.
|
||||
|
||||
**Turning off escalation while keeping dynamic resolution:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dynamic_routing": {
|
||||
"enabled": true,
|
||||
"escalate_on_failure": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Every attempt uses `tier_models[default_tier]` regardless of outcome — useful when you want explicit tier-to-model mapping without the escalation behaviour.
|
||||
|
||||
`dynamic_routing` is **disabled by default**. Omitting the block or setting `enabled: false` preserves static resolution.
|
||||
|
||||
---
|
||||
|
||||
## Using GSD on non-Anthropic runtimes
|
||||
|
||||
If you installed GSD for Codex, OpenCode, Gemini CLI, or Kilo, the installer already set `resolve_model_ids: "omit"` in your config. This tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model. No manual setup is needed for the basic case.
|
||||
|
||||
**If you want tiered models on Codex:**
|
||||
|
||||
```json
|
||||
{
|
||||
"runtime": "codex",
|
||||
"model_profile": "balanced"
|
||||
}
|
||||
```
|
||||
|
||||
GSD resolves each tier alias to the Codex-native model and reasoning effort defined in the runtime tier map.
|
||||
|
||||
**If you want per-agent model IDs on any non-Claude runtime:**
|
||||
|
||||
```json
|
||||
{
|
||||
"resolve_model_ids": "omit",
|
||||
"model_overrides": {
|
||||
"gsd-planner": "o3",
|
||||
"gsd-executor": "o4-mini",
|
||||
"gsd-debugger": "o3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For the full runtime-aware profiles reference and the `model_policy` surface (provider-neutral presets added in v1.42), see [Configuration reference — Model Profiles](../CONFIGURATION.md#model-profiles).
|
||||
|
||||
---
|
||||
|
||||
## Resolution precedence (highest to lowest)
|
||||
|
||||
When multiple layers apply, the resolver picks the highest-priority entry:
|
||||
|
||||
```text
|
||||
1. model_overrides[<agent>] — per-agent; full IDs; targeted exception
|
||||
2. dynamic_routing.tier_models[<tier>] — when enabled; escalates on soft failure
|
||||
3. models[<phase_type>] — coarse phase-level tier
|
||||
4. model_profile (per-agent column) — global tier strategy
|
||||
5. Runtime default — when nothing else applies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Choosing the right lever
|
||||
|
||||
| You want | Use |
|
||||
|---|---|
|
||||
| One tier strategy for all agents | `model_profile` |
|
||||
| Coarse phase-level tuning ("Opus for planning") | `models.<phase_type>` |
|
||||
| Per-agent precision ("force Haiku on the codebase mapper") | `model_overrides[<agent>]` |
|
||||
| A fully-qualified model ID for a specific agent | `model_overrides[<agent>]: "openai/gpt-5"` |
|
||||
| Start cheap, escalate only on failure | `dynamic_routing` |
|
||||
| All agents follow the session model (non-Anthropic provider) | `model_profile: "inherit"` |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Configuration reference](../CONFIGURATION.md)
|
||||
- [Multi-agent orchestration](../explanation/multi-agent-orchestration.md)
|
||||
- [Commands reference](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
178
docs/how-to/debug-a-failed-execution.md
Normal file
178
docs/how-to/debug-a-failed-execution.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# How to debug a failed execution
|
||||
|
||||
**Goal:** Recover when a phase execution fails, stalls, or produces incomplete work — and resume cleanly without losing progress or repeating work that already succeeded.
|
||||
|
||||
**Prerequisites:** You have run `/gsd-execute-phase N` and the execution stopped before writing `VERIFICATION.md`, or you see unexpected output, missing files, or a stalled spinner.
|
||||
|
||||
---
|
||||
|
||||
## Detect whether the execution stalled or failed
|
||||
|
||||
Before taking any recovery action, determine what actually happened.
|
||||
|
||||
### If you see "Spawning…" with no output after 1–5 minutes
|
||||
|
||||
This is normal, not a freeze. GSD subagents run in an isolated context window. The liveness note on the spawn line confirms this. Do not interrupt the session.
|
||||
|
||||
If it has been more than 10 minutes with no result, check the Claude Code sidebar. If the agent task shows as completed but no output appeared, the result may have been lost in a context switch — re-run the same command:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD checks for `SUMMARY.md` files before dispatching executors. Plans that already have one are skipped automatically.
|
||||
|
||||
### If execution stopped mid-wave with an error message
|
||||
|
||||
Check git history to see which plans committed successfully:
|
||||
|
||||
```bash
|
||||
git log --oneline -20
|
||||
```
|
||||
|
||||
Plans that committed their work will have an entry such as `feat(01-02): …`. Plans without a commit are incomplete and will be re-executed when you re-run.
|
||||
|
||||
### If the executor committed code but did not write SUMMARY.md
|
||||
|
||||
GSD detects this at the next run and surfaces a safe-resume gate with three options:
|
||||
|
||||
- **Close out manually** — inspect the commits yourself, write `SUMMARY.md`, then re-run.
|
||||
- **Re-execute from scratch** — revert or supersede the partial commits before dispatching a new executor.
|
||||
- **Mark-and-skip** — record the anomaly and continue, only with your explicit confirmation.
|
||||
|
||||
---
|
||||
|
||||
## Diagnose the root cause
|
||||
|
||||
### Run `/gsd-debug --diagnose`
|
||||
|
||||
If execution produced wrong output, stubbed code, or a verification failure, use the diagnosis-only mode to investigate without applying any fixes:
|
||||
|
||||
```bash
|
||||
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
|
||||
```
|
||||
|
||||
`--diagnose` stops at root cause without touching your files. It creates a session file at `.planning/debug/<slug>.md` so you can pick up the investigation later if needed.
|
||||
|
||||
To start a full debug session that also applies a fix:
|
||||
|
||||
```bash
|
||||
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
|
||||
```
|
||||
|
||||
GSD gathers symptoms, runs a structured investigation using the scientific method, and proposes a fix. If `tdd_mode: true` is set in your config, it requires a failing test before applying any fix.
|
||||
|
||||
### Check active debug sessions
|
||||
|
||||
```bash
|
||||
/gsd-debug list
|
||||
```
|
||||
|
||||
Shows all open sessions with their current hypothesis and next action. To resume a specific session:
|
||||
|
||||
```bash
|
||||
/gsd-debug continue <slug>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Run a post-mortem with `/gsd-forensics`
|
||||
|
||||
If the cause is not clear from the error output — for example, plans reference nonexistent files, execution produced unexpected results, or state seems corrupted — run a forensic investigation:
|
||||
|
||||
```bash
|
||||
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
||||
```
|
||||
|
||||
GSD analyses git history, `.planning/` artifact completeness, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a structured report to `.planning/forensics/report-<timestamp>.md` and surfaces recommended remediation steps.
|
||||
|
||||
`/gsd-forensics` is read-only — it never modifies your project files.
|
||||
|
||||
**What it detects:**
|
||||
|
||||
- **Stuck loop** — the same file appears in three or more consecutive commits within a short time window (HIGH confidence if commit messages are similar)
|
||||
- **Missing artefacts** — a phase has commits but no `SUMMARY.md` or `VERIFICATION.md`
|
||||
- **Abandoned work** — uncommitted changes with STATE.md showing mid-execution and the last commit more than two hours old
|
||||
- **Crash or interruption** — uncommitted changes combined with an active execution state and orphaned worktrees
|
||||
- **Scope drift** — recent commits touch files outside the current phase's expected file set
|
||||
|
||||
---
|
||||
|
||||
## Resume execution after recovery
|
||||
|
||||
Once the underlying issue is resolved, re-run the execute command:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD skips plans whose `SUMMARY.md` already exists and dispatches executors only for the remaining plans.
|
||||
|
||||
If you need to re-execute only a specific wave:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --wave 2
|
||||
```
|
||||
|
||||
If you want to validate `.planning/` integrity before dispatching:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --validate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Roll back with `/gsd-undo`
|
||||
|
||||
If execution produced code you want to discard entirely, roll back using the plan manifest rather than manual `git revert`:
|
||||
|
||||
### Roll back a single plan
|
||||
|
||||
```bash
|
||||
/gsd-undo --plan 03-02
|
||||
```
|
||||
|
||||
Reverts all commits for plan `02` of phase `3`. GSD shows a confirmation gate before writing any change.
|
||||
|
||||
### Roll back an entire phase
|
||||
|
||||
```bash
|
||||
/gsd-undo --phase 03
|
||||
```
|
||||
|
||||
Reverts all commits for phase `3`. GSD checks whether any subsequent phases depend on this phase and warns you before proceeding.
|
||||
|
||||
### Pick interactively from recent commits
|
||||
|
||||
```bash
|
||||
/gsd-undo --last 5
|
||||
```
|
||||
|
||||
Shows the five most recent GSD commits and lets you select which to revert.
|
||||
|
||||
---
|
||||
|
||||
## Restore session context after a break
|
||||
|
||||
If you have returned to the project after a context reset or a new session:
|
||||
|
||||
```bash
|
||||
/gsd-resume-work
|
||||
```
|
||||
|
||||
Restores your full session context from the last handoff, including the current phase, blockers, and where execution stopped.
|
||||
|
||||
Alternatively, to see your current position and auto-advance to the correct next step:
|
||||
|
||||
```bash
|
||||
/gsd-progress --next
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Execute a phase](execute-a-phase.md)
|
||||
- [Recover and troubleshoot](recover-and-troubleshoot.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
149
docs/how-to/design-a-ui-phase.md
Normal file
149
docs/how-to/design-a-ui-phase.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# How to design a UI phase
|
||||
|
||||
**Goal:** Produce a locked UI design contract (`UI-SPEC.md`) that fixes spacing, colour, typography, and copywriting decisions before the planner writes tasks, preventing visual inconsistency caused by ad-hoc styling choices during execution.
|
||||
|
||||
**Prerequisites:** `.planning/ROADMAP.md` exists. The phase must have frontend or UI work. Running `/gsd-discuss-phase N` first is strongly recommended — the UI researcher reads `CONTEXT.md` to avoid re-asking decisions you have already made.
|
||||
|
||||
---
|
||||
|
||||
## Decide whether this phase needs a UI contract
|
||||
|
||||
Not all phases need `/gsd-ui-phase`. Use it when:
|
||||
|
||||
- The phase introduces new UI surfaces (pages, flows, layouts)
|
||||
- Multiple components will be built and visual consistency matters
|
||||
- You are starting a new project's frontend and need a design system baseline
|
||||
- You are adding significant UI work to an existing project and want to lock tokens, spacing, and colour before execution
|
||||
|
||||
Skip it when:
|
||||
|
||||
- The phase is purely backend, infrastructure, or data work with no user-facing output
|
||||
- A UI-SPEC.md already exists for an earlier phase and this phase builds on identical visual patterns without introducing new surfaces
|
||||
|
||||
If you are unsure, the safety gate will prompt you: when `workflow.ui_safety_gate` is enabled (default), `/gsd-plan-phase` warns when it detects frontend work but no UI-SPEC.md and asks whether to run `/gsd-ui-phase` first.
|
||||
|
||||
---
|
||||
|
||||
## Run the UI design contract
|
||||
|
||||
```bash
|
||||
/gsd-ui-phase 2
|
||||
```
|
||||
|
||||
If no phase number is given, GSD Core targets the current phase.
|
||||
|
||||
The command runs in two stages:
|
||||
|
||||
1. **`gsd-ui-researcher`** — reads `CONTEXT.md`, `RESEARCH.md`, and `REQUIREMENTS.md` for existing decisions, detects the design system state (shadcn `components.json`, Tailwind config, existing tokens), and asks only the unanswered design questions across five areas: spacing, colour, typography, copywriting, and registry safety.
|
||||
2. **`gsd-ui-checker`** — validates the resulting `UI-SPEC.md` across six dimensions. If issues are found, a revision loop reruns the researcher (up to two iterations) targeting only the flagged items.
|
||||
|
||||
**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/`.
|
||||
|
||||
---
|
||||
|
||||
## What the UI-SPEC covers
|
||||
|
||||
The researcher locks decisions across five areas:
|
||||
|
||||
| Area | Examples |
|
||||
|---|---|
|
||||
| **Spacing** | Base scale (4px or 8px), grid alignment, component padding |
|
||||
| **Colour** | Primary, accent, neutral palette; 60/30/10 rule; dark-mode considerations |
|
||||
| **Typography** | Font families, size/weight scale constraints, heading hierarchy |
|
||||
| **Copywriting** | CTA labels, empty state messages, error state copy, loading indicators |
|
||||
| **Registry safety** | shadcn component inspection protocol (see below) |
|
||||
|
||||
The checker validates the spec against six pillars, scored 1–4 each: Copywriting, Visuals, Colour, Typography, Spacing, and Experience Design (loading / error / empty state coverage).
|
||||
|
||||
---
|
||||
|
||||
## shadcn initialisation
|
||||
|
||||
For React, Next.js, and Vite projects, the researcher offers to initialise shadcn if no `components.json` is found. The flow:
|
||||
|
||||
1. Visit `ui.shadcn.com/create` and configure your preset (colours, border radius, fonts)
|
||||
2. Copy the preset string
|
||||
3. Run:
|
||||
|
||||
```bash
|
||||
npx shadcn init --preset <paste>
|
||||
```
|
||||
|
||||
The preset string becomes a first-class GSD Core planning artefact that is reproducible across phases and milestones.
|
||||
|
||||
---
|
||||
|
||||
## Registry safety gate
|
||||
|
||||
Third-party shadcn registries can inject arbitrary code. When `workflow.ui_safety_gate` is enabled (default), the spec requires these steps before installing any non-official component:
|
||||
|
||||
```bash
|
||||
npx shadcn view <component> # inspect source before installing
|
||||
npx shadcn diff <component> # compare against the official registry
|
||||
```
|
||||
|
||||
The checker will flag the spec as BLOCKED if registry safety is not addressed. Disable the gate via `/gsd-settings` if your project does not use shadcn or you have an alternative vetting process.
|
||||
|
||||
---
|
||||
|
||||
## Use sketch findings as a head start
|
||||
|
||||
If you have already run `/gsd-sketch --wrap-up`, the UI researcher loads `.claude/skills/sketch-findings-[project]/` automatically. Pre-validated decisions (layout, palette, typography, spacing) are treated as locked — the researcher does not re-ask them. You see a note at the start of the run:
|
||||
|
||||
```text
|
||||
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
|
||||
Pre-validated decisions (layout, palette, typography, spacing) should be treated
|
||||
as locked — not re-asked.
|
||||
```
|
||||
|
||||
This is the main reason to run `/gsd-sketch --wrap-up` before `/gsd-ui-phase`: it turns the conversational design exploration into binding contract input.
|
||||
|
||||
---
|
||||
|
||||
## Retroactive visual audit with `/gsd-ui-review`
|
||||
|
||||
`/gsd-ui-review` runs after execution, not before. Use it to audit the implemented frontend against the UI-SPEC (or against abstract 6-pillar standards when no spec exists).
|
||||
|
||||
```bash
|
||||
/gsd-ui-review # audit the current phase
|
||||
/gsd-ui-review 3 # audit phase 3 specifically
|
||||
```
|
||||
|
||||
It works on any project with frontend code — GSD project initialisation is not required.
|
||||
|
||||
**What it checks (6 pillars, scored 1–4 each):**
|
||||
|
||||
1. Copywriting — CTA labels, empty states, error states
|
||||
2. Visuals — focal points, visual hierarchy, icon accessibility
|
||||
3. Colour — accent usage discipline, 60/30/10 compliance
|
||||
4. Typography — font size and weight constraint adherence
|
||||
5. Spacing — grid alignment, token consistency
|
||||
6. Experience Design — loading, error, and empty state coverage
|
||||
|
||||
**Output:** `{padded_phase}-UI-REVIEW.md` with scores and top three priority fixes. When a browser MCP server such as `gsd-browser` is configured, the audit also captures screenshots with visual evidence.
|
||||
|
||||
**Screenshot storage:** Screenshots are saved to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`.
|
||||
|
||||
---
|
||||
|
||||
## Recommended position in the phase lifecycle
|
||||
|
||||
```text
|
||||
/gsd-discuss-phase N ← lock implementation preferences
|
||||
/gsd-ui-phase N ← lock design contract (frontend phases)
|
||||
/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
|
||||
/gsd-execute-phase N ← parallel execution
|
||||
/gsd-verify-work N ← manual UAT
|
||||
/gsd-ui-review N ← retroactive visual audit (optional but recommended)
|
||||
```
|
||||
|
||||
`/gsd-ui-phase` sits between discuss and plan because the planner reads `UI-SPEC.md` as design context — tasks in `PLAN.md` reference spacing tokens, colour variables, and copywriting decisions that the spec locked.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Spike and sketch](spike-and-sketch.md)
|
||||
- [Plan a phase](plan-a-phase.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
158
docs/how-to/discuss-a-phase.md
Normal file
158
docs/how-to/discuss-a-phase.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# How to discuss a phase
|
||||
|
||||
**Goal:** Gather the implementation decisions a phase needs before planning begins — so the researcher and planner can act without asking you again.
|
||||
|
||||
**Prerequisites:** `.planning/ROADMAP.md` exists. If not, run `/gsd-new-project` first.
|
||||
|
||||
---
|
||||
|
||||
## Choose your discuss mode
|
||||
|
||||
GSD Core offers two modes. Choose based on how well-understood the codebase is.
|
||||
|
||||
**If you want to express your own implementation preferences upfront** (interview mode, the default):
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2
|
||||
```
|
||||
|
||||
Claude identifies grey areas in the phase scope, lets you select which to discuss, then works through approximately four questions per area.
|
||||
|
||||
**If the codebase already has clear patterns and you find most questions obvious** (assumptions mode):
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
|
||||
/gsd-discuss-phase 2
|
||||
```
|
||||
|
||||
Claude reads 5–15 relevant codebase files via a subagent, forms assumptions with evidence and confidence levels, and presents them for confirmation or correction. Typically 2–4 interactions rather than 15–20.
|
||||
|
||||
To switch back:
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set workflow.discuss_mode discuss
|
||||
```
|
||||
|
||||
See [Discuss modes explained](../workflow-discuss-mode.md) for a full comparison, including when each mode is likely to save time.
|
||||
|
||||
---
|
||||
|
||||
## Discuss all grey areas without the selection step
|
||||
|
||||
By default, Claude presents grey areas and asks which you want to cover. If you want to work through all of them without that selection prompt:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Speed up a straightforward phase
|
||||
|
||||
**If the phase is well-understood and you want Claude to pick the recommended defaults without prompting you:**
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 3 --auto
|
||||
```
|
||||
|
||||
Claude selects the recommended answer for every question and logs the choices. Use this for phases where the decisions are low-stakes or already implied by prior phases.
|
||||
|
||||
**If you have remote-session constraints (no TUI menus):**
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --text
|
||||
```
|
||||
|
||||
All prompts are rendered as plain-text numbered lists instead of interactive selectors.
|
||||
|
||||
---
|
||||
|
||||
## Work through questions in groups
|
||||
|
||||
If you prefer to answer several questions at once rather than one at a time:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --batch
|
||||
```
|
||||
|
||||
Claude groups 2–5 questions per turn.
|
||||
|
||||
---
|
||||
|
||||
## Add trade-off analysis to each question
|
||||
|
||||
If you want a comparison table of the options before committing:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 2 --analyze
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bulk-answer from a prepared file
|
||||
|
||||
If you have a prepared answers file and want to push all decisions in one pass:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1 --power
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Surface Claude's assumptions before discussing
|
||||
|
||||
**If you want to see what Claude would assume and do before any interactive session** — useful for validating alignment before investing discussion time:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 3 --assumptions
|
||||
```
|
||||
|
||||
Claude outputs its assumptions (with codebase evidence and confidence levels) and exits. No CONTEXT.md is written. Review the output, then run a normal discuss or assumptions-mode session if anything needs correcting.
|
||||
|
||||
---
|
||||
|
||||
## What CONTEXT.md contains
|
||||
|
||||
Both discuss and assumptions mode produce the same `{phase}-CONTEXT.md` in the phase directory. Downstream agents (researcher, planner, plan-checker) read this file identically regardless of which mode produced it. It contains six sections:
|
||||
|
||||
| Section | Purpose |
|
||||
|---|---|
|
||||
| `<domain>` | Phase boundary — what this phase delivers |
|
||||
| `<decisions>` | Locked implementation decisions from the session |
|
||||
| `<canonical_refs>` | Specs, ADRs, and docs downstream agents must read |
|
||||
| `<code_context>` | Reusable assets, patterns, and integration points |
|
||||
| `<specifics>` | User references and preferences |
|
||||
| `<deferred>` | Ideas noted for future phases |
|
||||
|
||||
The `<canonical_refs>` section is mandatory. If you reference a doc, spec, or ADR during the discussion, Claude adds it immediately and reads it to inform subsequent questions.
|
||||
|
||||
See [CONTEXT.md schema](../reference/context-md.md) for the full field reference.
|
||||
|
||||
---
|
||||
|
||||
## How decisions feed into planning
|
||||
|
||||
When you run `/gsd-plan-phase` next, the planner reads CONTEXT.md to know which decisions are locked. It will not re-ask questions already answered here. The researcher reads it first to know what to investigate.
|
||||
|
||||
**If CONTEXT.md is missing when you run `/gsd-plan-phase`**, you will be offered the choice to continue without context (plans use research and requirements only, without your design preferences) or to run `/gsd-discuss-phase` first.
|
||||
|
||||
---
|
||||
|
||||
## If you have a PRD or acceptance-criteria document
|
||||
|
||||
Skip discuss-phase entirely and go straight to planning:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --prd path/to/prd.md
|
||||
```
|
||||
|
||||
The planner synthesises CONTEXT.md from the PRD and treats all requirements as locked decisions.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Plan a phase](plan-a-phase.md)
|
||||
- [Discuss modes](../workflow-discuss-mode.md)
|
||||
- [CONTEXT.md schema](../reference/context-md.md)
|
||||
- [docs index](../README.md)
|
||||
176
docs/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
176
docs/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# How to drive GSD Core from a tracker issue
|
||||
|
||||
**Goal:** Take a single well-scoped GitHub, Linear, or Jira issue through the full GSD pipeline — from isolated workspace to merged PR — using only commands that already exist in GSD Core, with no custom scripts or tracker integrations.
|
||||
|
||||
**Prerequisites:** GSD Core is installed. The issue has bounded scope, observable acceptance criteria, and no upstream blockers.
|
||||
|
||||
For the concepts and design rationale behind this pattern, see [Issue-driven orchestration explained](../issue-driven-orchestration.md).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Map the issue to a phase
|
||||
|
||||
Open your tracker issue and decide how it maps onto `ROADMAP.md`:
|
||||
|
||||
- **Issue matches an existing phase** → note the phase number and move to Step 2.
|
||||
- **Issue is standalone new work** → add a phase:
|
||||
|
||||
```bash
|
||||
/gsd-phase "Description matching the issue title"
|
||||
```
|
||||
|
||||
- **Issue is urgent and must slot between existing phases** → insert a decimal phase:
|
||||
|
||||
```bash
|
||||
/gsd-phase --insert 3 "Fix: description from issue"
|
||||
```
|
||||
|
||||
Copy the tracker issue URL. You will paste it into `CONTEXT.md` in Step 3 so traceability survives context compaction.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create an isolated workspace
|
||||
|
||||
Every issue gets its own workspace — a git worktree with an independent `.planning/` directory. Partial work, aborted plans, and exploratory commits stay outside `main`.
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
|
||||
```
|
||||
|
||||
Switch into the workspace directory before continuing:
|
||||
|
||||
```bash
|
||||
cd ~/gsd-workspaces/my-issue-slug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Discuss the phase
|
||||
|
||||
Run discuss-phase to lock in implementation decisions before any planning happens. When the session opens, paste the tracker issue URL into the discussion so it is captured in `CONTEXT.md`.
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase N
|
||||
```
|
||||
|
||||
GSD asks about ambiguities in the issue scope — error handling, edge cases, interface contracts, technology choices. Your answers shape the plan that follows.
|
||||
|
||||
If you already know all the answers and want to move quickly:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase N --auto
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Plan the phase
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase N
|
||||
```
|
||||
|
||||
GSD spawns research agents, reads your `CONTEXT.md` decisions (including the issue URL), and produces atomic `PLAN.md` files. A plan-checker validates each plan before saving.
|
||||
|
||||
If you want peer review from external AI CLIs before execution (recommended for significant changes):
|
||||
|
||||
```bash
|
||||
/gsd-review --phase N
|
||||
/gsd-plan-phase N --reviews
|
||||
```
|
||||
|
||||
Or run the full plan–review–converge loop until no HIGH concerns remain:
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence N
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Execute the phase
|
||||
|
||||
For interactive, phase-at-a-time execution:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase N
|
||||
```
|
||||
|
||||
For a hands-off run through all remaining phases:
|
||||
|
||||
```bash
|
||||
/gsd-autonomous
|
||||
```
|
||||
|
||||
For an interactive dashboard where you can watch progress and dispatch work across phases:
|
||||
|
||||
```bash
|
||||
/gsd-manager
|
||||
```
|
||||
|
||||
All three approaches update `STATE.md`, commit each task atomically, and run the post-phase verifier.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Verify the work
|
||||
|
||||
```bash
|
||||
/gsd-verify-work N
|
||||
```
|
||||
|
||||
GSD walks you through the acceptance criteria from the phase goal (which reflects your tracker issue) one at a time. If anything fails, GSD diagnoses the root cause and creates a fix plan. Re-run execute and re-verify until all checks pass.
|
||||
|
||||
Treat `verification_failed` as a blocker even when the code looks correct — the failure usually surfaces a missed acceptance criterion from the original issue.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Review and ship
|
||||
|
||||
Run a code review before opening the PR:
|
||||
|
||||
```bash
|
||||
/gsd-code-review N
|
||||
/gsd-code-review N --fix
|
||||
```
|
||||
|
||||
Then create the PR:
|
||||
|
||||
```bash
|
||||
/gsd-ship N
|
||||
```
|
||||
|
||||
GSD assembles the PR body from your planning artifacts: phase goal, changes summary, requirements addressed, verification status, and key decisions. Include `Closes #NNN` or `Fixes #NNN` in the PR body (or set it via `/gsd-config`) so the tracker issue closes automatically when the PR merges.
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Capture follow-up work
|
||||
|
||||
As you work through the issue you will often discover related work. Capture it without losing context:
|
||||
|
||||
```bash
|
||||
/gsd-capture "Follow-up: description of discovered work" # Add as a todo
|
||||
/gsd-capture --seed "Idea worth a future phase" # Preserve for the next milestone
|
||||
/gsd-capture --backlog "Not urgent but worth tracking" # Park in the backlog
|
||||
```
|
||||
|
||||
GSD does not post to your tracker automatically. Creating a tracker issue from captured follow-ups is a separate manual step — this keeps human review in the loop.
|
||||
|
||||
---
|
||||
|
||||
## Conditionals
|
||||
|
||||
| Situation | What to do |
|
||||
|-----------|-----------|
|
||||
| Issue is very small (typo, config change) | Skip workspace + discuss + plan; use `/gsd-quick` instead |
|
||||
| Issue has multiple independent sub-tasks | Use `/gsd-manager` to parallelise execution across plans |
|
||||
| Issue is blocked on another issue | Do not start until the upstream blocker is resolved; GSD has no automatic dependency poller |
|
||||
| Issue scope turns out larger than expected mid-execution | Stop, run `/gsd-phase --insert N` to add sub-phases, continue |
|
||||
| You want to skip the interactive discussion | Use `--auto` flag with `/gsd-discuss-phase`, or set `workflow.skip_discuss: true` for project-wide automation |
|
||||
| Multiple issues form a coherent release | Run `/gsd-new-milestone` to group them and `/gsd-autonomous` to execute in sequence |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Issue-driven orchestration explained](../issue-driven-orchestration.md)
|
||||
- [Isolate work with workspaces](isolate-work-with-workspaces.md)
|
||||
- [Verify and ship](verify-and-ship.md)
|
||||
- [docs index](../README.md)
|
||||
119
docs/how-to/execute-a-phase.md
Normal file
119
docs/how-to/execute-a-phase.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# How to execute a phase
|
||||
|
||||
**Goal:** Run a planned phase through wave-based parallel execution and land every plan as an atomic git commit.
|
||||
|
||||
**Prerequisites:** The phase has at least one `PLAN.md` file. If planning is not yet done, run `/gsd-plan-phase N` first — see [Plan a phase](plan-a-phase.md).
|
||||
|
||||
---
|
||||
|
||||
## Run the full phase
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD reads the phase's plan files, groups them into dependency waves, and spawns a fresh executor agent per plan. Each executor commits its work atomically before the next wave begins.
|
||||
|
||||
Before any agents are dispatched, GSD prints a wave table:
|
||||
|
||||
```
|
||||
## Execution Plan
|
||||
|
||||
Phase 1: Core middleware — 3 plans across 2 wave(s)
|
||||
|
||||
| Wave | Plans | What it builds |
|
||||
|------|----------------|---------------------------|
|
||||
| 1 | 01-01, 01-02 | Core validation function |
|
||||
| 2 | 01-03 | Express middleware wrapper |
|
||||
```
|
||||
|
||||
Wave 1 plans run in parallel (each in an isolated git worktree). Wave 2 waits until all Wave 1 commits are merged.
|
||||
|
||||
For the underlying agent coordination model, see [Multi-agent orchestration](../explanation/multi-agent-orchestration.md).
|
||||
|
||||
---
|
||||
|
||||
## Run a single wave
|
||||
|
||||
If you want to execute only one wave — for example, to inspect Wave 1 output before committing to Wave 2 — use `--wave N`:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --wave 2
|
||||
```
|
||||
|
||||
GSD executes only Wave 2 plans. It first checks that all earlier waves are complete; if any Wave 1 plan is still marked incomplete, it stops and tells you to finish earlier waves first.
|
||||
|
||||
---
|
||||
|
||||
## Validate state before execution
|
||||
|
||||
If you suspect the `.planning/` directory is out of sync with the filesystem — for example after a crash or an interrupted previous run — pass `--validate`:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1 --validate
|
||||
```
|
||||
|
||||
GSD runs a state consistency check before spawning any executors. Detected drift is reported and you can accept or correct it before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Resume a stalled execution
|
||||
|
||||
If execution stops partway through — a quota error, a network drop, or a crashed session — the wave-level progress is preserved. GSD checks for a `SUMMARY.md` file for each plan; plans that have one are skipped automatically when you re-run:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 1
|
||||
```
|
||||
|
||||
GSD will skip plans where `SUMMARY.md` already exists and pick up from the first incomplete plan.
|
||||
|
||||
**If commits exist but `SUMMARY.md` is missing** (the executor committed but did not write its summary before the session died), GSD surfaces a safe-resume gate and offers three options:
|
||||
|
||||
- `close out manually` — inspect the commits, write `SUMMARY.md`, then re-run.
|
||||
- `re-execute from scratch` — revert or supersede the partial commits before dispatching a new executor.
|
||||
- `mark-and-skip` — record the anomaly and move on, only with explicit confirmation.
|
||||
|
||||
For systematic failure diagnosis, see [Debug a failed execution](debug-a-failed-execution.md).
|
||||
|
||||
---
|
||||
|
||||
## Where output lands
|
||||
|
||||
After all waves complete, the phase directory contains:
|
||||
|
||||
```
|
||||
.planning/phases/01-<name>/
|
||||
01-01-SUMMARY.md # What plan 01 built, key files, deviations
|
||||
01-02-SUMMARY.md
|
||||
01-03-SUMMARY.md
|
||||
VERIFICATION.md # Requirement-by-requirement pass/fail status
|
||||
```
|
||||
|
||||
`STATE.md` and `ROADMAP.md` are updated automatically once all waves are done. `VERIFICATION.md` is written only when the phase is fully complete.
|
||||
|
||||
Git history will show one commit per task (from each executor), followed by tracking commits from the orchestrator.
|
||||
|
||||
---
|
||||
|
||||
## Cross-AI execution
|
||||
|
||||
To delegate execution to an external AI CLI (Codex, Gemini, etc.) configured in `workflow.cross_ai_command`:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 2 --cross-ai
|
||||
```
|
||||
|
||||
To force local execution even when cross-AI is enabled in config:
|
||||
|
||||
```bash
|
||||
/gsd-execute-phase 2 --no-cross-ai
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Plan a phase](plan-a-phase.md)
|
||||
- [Verify and ship](verify-and-ship.md)
|
||||
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
121
docs/how-to/handle-quick-and-fast-tasks.md
Normal file
121
docs/how-to/handle-quick-and-fast-tasks.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# How to handle quick and fast tasks
|
||||
|
||||
Not every piece of work fits inside a phase. GSD provides two lightweight commands for work that does not need the full discuss → plan → execute → verify loop.
|
||||
|
||||
For context on when the full phase pipeline is worth its overhead, see [Context engineering](../explanation/context-engineering.md).
|
||||
|
||||
---
|
||||
|
||||
## Deciding which command to use
|
||||
|
||||
| Situation | Command |
|
||||
|-----------|---------|
|
||||
| Fixing a bug, adding a small feature, or any task you cannot summarise as a single trivial edit | `/gsd-quick` |
|
||||
| Fixing a typo, updating a config value, adding a `.gitignore` entry, or any change that touches ≤ 3 files and takes under a minute | `/gsd-fast` |
|
||||
| The task has unknowns, needs research, or will touch more than a handful of files | `/gsd-quick` with `--research` |
|
||||
|
||||
**The rule of thumb:** if you hesitate for even a moment about whether the task is trivial, use `/gsd-quick`. `/gsd-fast` redirects you to `/gsd-quick` automatically if the scope looks non-trivial.
|
||||
|
||||
---
|
||||
|
||||
## `/gsd-quick` — ad-hoc tasks with GSD guarantees
|
||||
|
||||
`/gsd-quick` runs a planner and executor with the same atomic-commit and STATE.md tracking guarantees as a full phase, but without the phase overhead (no ROADMAP entry, no discuss-phase, no wave coordination across multiple plans).
|
||||
|
||||
### Basic use
|
||||
|
||||
```bash
|
||||
/gsd-quick
|
||||
```
|
||||
|
||||
GSD prompts you for a task description, then plans and executes it. Artifacts land in `.planning/quick/`.
|
||||
|
||||
You can also pass the description directly:
|
||||
|
||||
```bash
|
||||
/gsd-quick "Fix the login button not responding on mobile Safari"
|
||||
```
|
||||
|
||||
### Flags
|
||||
|
||||
Add flags to bring in more of the quality pipeline when the task warrants it.
|
||||
|
||||
| Flag | What it adds |
|
||||
|------|-------------|
|
||||
| `--discuss` | A lightweight pre-planning discussion that surfaces grey areas and captures your decisions in a `CONTEXT.md` before the planner runs |
|
||||
| `--research` | A focused research agent investigates approaches, libraries, and pitfalls before planning |
|
||||
| `--validate` | Plan-checking (up to 2 iterations) plus post-execution verification |
|
||||
| `--full` | All of the above — equivalent to `--discuss --research --validate` |
|
||||
|
||||
Flags compose freely:
|
||||
|
||||
```bash
|
||||
/gsd-quick --research --validate # research + plan-checking + verification, no discuss
|
||||
/gsd-quick --discuss # just surface grey areas before planning
|
||||
/gsd-quick --full # the complete quality pipeline
|
||||
```
|
||||
|
||||
### When to add flags
|
||||
|
||||
- Add `--research` when you are unsure how to approach a task or which library to use.
|
||||
- Add `--validate` when the task touches critical code paths and you want a verifier agent to confirm the must-haves were met.
|
||||
- Add `--discuss` when the task has design choices you want to lock in before the planner runs — for example, when the right error-handling behaviour is not obvious.
|
||||
- Use `--full` when a task is genuinely significant and you would normally plan it as a phase but it does not belong in the ROADMAP.
|
||||
|
||||
### Listing and resuming quick tasks
|
||||
|
||||
```bash
|
||||
/gsd-quick list # show all quick tasks with status
|
||||
/gsd-quick status my-task-slug # show status of a specific task
|
||||
/gsd-quick resume my-task-slug # resume an interrupted task
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/gsd-fast` — inline trivial edits
|
||||
|
||||
`/gsd-fast` does the work directly in the current context. There are no subagents, no `PLAN.md`, and no research. It is suitable only for changes you could make yourself in under a minute.
|
||||
|
||||
```bash
|
||||
/gsd-fast "fix typo in README"
|
||||
/gsd-fast "add .env to .gitignore"
|
||||
```
|
||||
|
||||
If you omit the description, GSD prompts you for it.
|
||||
|
||||
`/gsd-fast` checks whether the task is actually trivial before proceeding. If it judges the scope too large it stops and redirects you:
|
||||
|
||||
```text
|
||||
This looks like it needs planning. Use /gsd-quick instead:
|
||||
/gsd-quick "your task description"
|
||||
```
|
||||
|
||||
After making the change, `/gsd-fast` commits atomically and, if a `Quick Tasks Completed` table exists in `.planning/STATE.md`, appends a row to it.
|
||||
|
||||
---
|
||||
|
||||
## What `/gsd-quick` does that `/gsd-fast` does not
|
||||
|
||||
| Capability | `/gsd-fast` | `/gsd-quick` |
|
||||
|------------|------------|--------------|
|
||||
| Subagent planner | No | Yes |
|
||||
| Subagent executor | No | Yes |
|
||||
| Research agent | No | Optional (`--research`) |
|
||||
| Plan-checking | No | Optional (`--validate`) |
|
||||
| Post-execution verification | No | Optional (`--validate`) |
|
||||
| Discussion phase | No | Optional (`--discuss`) |
|
||||
| Worktree isolation | No | Yes (default) |
|
||||
| Atomic commits per task | Single commit | One per plan task |
|
||||
| STATE.md tracking | Row appended if table exists | Always updated |
|
||||
| `.planning/quick/` artifacts | No | Yes |
|
||||
|
||||
The key distinction is subagent isolation. `/gsd-quick` spawns a fresh planner and executor in separate context windows, which means the work is planned properly, commits are atomic per task, and the orchestrator can verify results. `/gsd-fast` uses only the current context window and is intentionally limited to changes trivial enough not to need any of that.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [The phase loop](../explanation/the-phase-loop.md)
|
||||
- [Context engineering](../explanation/context-engineering.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
291
docs/how-to/install-on-your-runtime.md
Normal file
291
docs/how-to/install-on-your-runtime.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# How to install GSD Core on your runtime
|
||||
|
||||
Install GSD Core (`@opengsd/gsd-core`) into the AI coding runtime you use every day. This guide gives you the standard installer path for each supported runtime, then covers the manual path for machines without Node.js.
|
||||
|
||||
**What you need:** Node.js 18+ and npm (or npx). If you do not have Node.js, jump to [Installing without Node.js](#installing-without-nodejs).
|
||||
|
||||
---
|
||||
|
||||
## Why the installer is required
|
||||
|
||||
GSD Core ships agent and command files in Claude Code's native frontmatter format. Each supported runtime expects a different schema, directory layout, and command-invocation syntax. The installer performs the necessary transformations — for example, converting tool lists and colour values for OpenCode, writing TOML agent entries for Codex, and rewriting every command body from hyphen form (`/gsd-update`) to colon form (`/gsd:update`) for Gemini CLI.
|
||||
|
||||
**Do not copy files from `agents/` or `commands/` directly.** Doing so bypasses the transformations and produces schema-validation errors or missing commands.
|
||||
|
||||
---
|
||||
|
||||
## Standard install
|
||||
|
||||
Run the installer from any directory. It prompts for your runtime and whether to install globally (all projects) or locally (this project only).
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest
|
||||
```
|
||||
|
||||
That is the only command you need for a fresh install or to re-run the installer after switching runtimes.
|
||||
|
||||
---
|
||||
|
||||
## Per-runtime instructions
|
||||
|
||||
### Claude Code
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --global
|
||||
```
|
||||
|
||||
Skills land in `~/.claude/`. Commands appear as `/gsd-*` slash commands in your next Claude Code session. Restart Claude Code to pick them up.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --gemini --global
|
||||
```
|
||||
|
||||
Skills land in `~/.gemini/`. The installer rewrites all command bodies to Gemini's colon namespace (`/gsd:update`, `/gsd:config`, etc.). Restart Gemini CLI after install.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OpenCode
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --opencode --global
|
||||
```
|
||||
|
||||
Skills land in `~/.config/opencode/` (XDG) or `~/.opencode/`. The installer converts agent frontmatter to OpenCode's schema — removing the `tools:` field and converting colour values to hex. See [Installing without Node.js — OpenCode transformations](#opencode--required-transformations) if you need to understand what changes.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Kilo
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --kilo --global
|
||||
```
|
||||
|
||||
Skills land in `~/.config/kilo/` (XDG) or `~/.kilo/`. Uses the same OpenCode-style flat markdown command format.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Codex
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --codex --global
|
||||
```
|
||||
|
||||
Skills land in `~/.codex/skills/gsd-*/SKILL.md`. Agents are written with per-agent TOML entries in `config.toml`. Restart Codex (or run `codex --reload`) after install.
|
||||
|
||||
**Minimum supported version:** Codex CLI 0.130.0. Earlier versions had additional skill-root scanning that can produce duplicate listings.
|
||||
|
||||
---
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --copilot --global
|
||||
```
|
||||
|
||||
Skills land in `~/.copilot/`. GSD installs as agent `.md` files and repository instruction files.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cursor
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --cursor --global
|
||||
```
|
||||
|
||||
Skills land in `~/.cursor/`. GSD installs skills, agents, and rule references.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Windsurf
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --windsurf --global
|
||||
```
|
||||
|
||||
Skills land in `~/.codeium/windsurf/`. GSD installs skills, agents, and workspace rules.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cline
|
||||
|
||||
Cline uses a rules-based integration — GSD installs as `.clinerules` rather than slash commands.
|
||||
|
||||
```bash
|
||||
# Global install (all projects)
|
||||
npx @opengsd/gsd-core@latest --cline --global
|
||||
|
||||
# Local install (this project only)
|
||||
npx @opengsd/gsd-core@latest --cline --local
|
||||
```
|
||||
|
||||
Global installs write to `~/.cline/`. Local installs write to `./.cline/`. Rules are loaded automatically by Cline — no custom slash commands are registered.
|
||||
|
||||
---
|
||||
|
||||
### CodeBuddy
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --codebuddy --global
|
||||
```
|
||||
|
||||
Skills land in `~/.codebuddy/skills/gsd-*/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
### Qwen Code
|
||||
|
||||
Qwen Code uses the same open skills standard as Claude Code 2.1.88+.
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --qwen --global
|
||||
```
|
||||
|
||||
Skills land in `~/.qwen/skills/gsd-*/SKILL.md`.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Augment Code
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --augment --global
|
||||
```
|
||||
|
||||
Skills land in `~/.augment/`. GSD installs skills and agents. No hook or statusline ownership.
|
||||
|
||||
---
|
||||
|
||||
### Antigravity
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --antigravity --global
|
||||
```
|
||||
|
||||
The installer auto-detects the Antigravity config directory (`~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, or `~/.gemini/antigravity-cli`). Uses Gemini-compatible settings policy.
|
||||
|
||||
**Override the install directory:**
|
||||
|
||||
```bash
|
||||
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Trae
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --trae --global
|
||||
```
|
||||
|
||||
Skills land in `~/.trae/`. GSD installs skills, agents, and rule references.
|
||||
|
||||
---
|
||||
|
||||
## Local vs global install
|
||||
|
||||
All examples above use `--global`, which installs GSD once for your user account. To scope an install to a single project, replace `--global` with `--local`:
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --local
|
||||
```
|
||||
|
||||
A local install writes into the `.claude/` directory at your project root. Local install settings take precedence over global ones when both exist.
|
||||
|
||||
---
|
||||
|
||||
## Installing prerelease editions (Next / Nightly / Insiders / Preview)
|
||||
|
||||
Prerelease editions of runtimes (Windsurf Next, Cursor Nightly, VS Code Insiders, Codex preview channels, etc.) read from a sibling config directory. Set the matching `*_CONFIG_DIR` env var before running the installer:
|
||||
|
||||
```bash
|
||||
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
|
||||
```
|
||||
|
||||
Select the corresponding stable runtime in the installer prompt. GSD does not enumerate prerelease editions as separate named runtimes — they are best-effort via this env-var mechanism and are not separately tested in release CI.
|
||||
|
||||
---
|
||||
|
||||
## Installing without Node.js
|
||||
|
||||
If you cannot run `npx` (for example, on a Windows machine without Node.js), you have two options.
|
||||
|
||||
**Option A — Use a machine that has Node.js.** Any machine with Node.js will do: WSL, a Linux VM, a CI runner, or a Docker container. Run the installer there, then copy the output directory to your target machine. For OpenCode:
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --opencode --global
|
||||
# Then copy ~/.config/opencode/agents/ to the Windows machine
|
||||
```
|
||||
|
||||
**Option B — Manually transform the source files.** The agent source files live in `agents/` in the GSD Core repository and are in Claude Code's native frontmatter format. Each runtime expects a different shape. For the exact field transformations per runtime, see [Manual install / no-Node.js setup](../USER-GUIDE.md#manual-install--no-nodejs-setup) in the User Guide, which covers the OpenCode transformations in full detail and points to the installer's `convert*Frontmatter` functions for other runtimes.
|
||||
|
||||
---
|
||||
|
||||
## After install
|
||||
|
||||
Restart your runtime to pick up new commands and agents. Then start your first project:
|
||||
|
||||
```bash
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Your first project](../tutorials/your-first-project.md)
|
||||
- [Update GSD Core](update-gsd.md)
|
||||
- [Configuration](../CONFIGURATION.md)
|
||||
- [Docs index](../README.md)
|
||||
144
docs/how-to/isolate-work-with-workspaces.md
Normal file
144
docs/how-to/isolate-work-with-workspaces.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# How to isolate work with workspaces
|
||||
|
||||
**Goal:** Create a fully isolated GSD environment — separate git worktree, independent `.planning/` root, and optionally multiple repositories — for feature branches or multi-repo work.
|
||||
|
||||
**Prerequisites:** `git` is installed and the repository supports worktrees. For multi-repo workspaces, the target repos exist on your local machine or are accessible by path.
|
||||
|
||||
---
|
||||
|
||||
## What workspaces are
|
||||
|
||||
A workspace is a self-contained environment that pairs one or more git worktrees (or clones) with its own `.planning/` root directory. Each workspace has:
|
||||
|
||||
- Its own `.planning/` directory that is **completely independent** from the source repo's `.planning/` — not a subdirectory of it
|
||||
- Its own `WORKSPACE.md` manifest tracking member repos
|
||||
- Git worktrees (default) or full clones of the specified repos, checked out on a dedicated branch (default: `workspace/<name>`)
|
||||
|
||||
Workspaces live under `~/gsd-workspaces/<name>/` by default.
|
||||
|
||||
```
|
||||
~/gsd-workspaces/
|
||||
└── feature-b/
|
||||
├── WORKSPACE.md ← manifest
|
||||
├── .planning/ ← fully independent GSD state
|
||||
│ ├── PROJECT.md
|
||||
│ ├── ROADMAP.md
|
||||
│ └── ...
|
||||
├── hr-ui/ ← worktree or clone of hr-ui repo
|
||||
└── ZeymoAPI/ ← worktree or clone of ZeymoAPI repo
|
||||
```
|
||||
|
||||
Because the workspace's `.planning/` is separate from the source repos, there is no overlap or conflict with planning state that exists in the source repos themselves.
|
||||
|
||||
---
|
||||
|
||||
## Create a workspace for multiple repos
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
|
||||
```
|
||||
|
||||
GSD creates worktrees of `hr-ui` and `ZeymoAPI` inside `~/gsd-workspaces/feature-b/`, checks out a `workspace/feature-b` branch in each, writes `WORKSPACE.md`, and creates an empty `.planning/` directory ready for `/gsd-new-project`.
|
||||
|
||||
To customise the location:
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create a workspace for the current repo
|
||||
|
||||
When you want feature-branch isolation on a single repo — independent branch, independent `.planning/`, no state bleed from main:
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos .
|
||||
```
|
||||
|
||||
The `.` tells GSD to create a worktree of the current repo. The worktree is checked out on `workspace/payments-rework`.
|
||||
|
||||
To force a full clone instead of a worktree:
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos . --strategy clone
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Specify a branch explicitly
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
|
||||
```
|
||||
|
||||
The `--branch` flag sets the branch name for all repos in the workspace. Defaults to `workspace/<name>`.
|
||||
|
||||
---
|
||||
|
||||
## Skip interactive questions
|
||||
|
||||
```bash
|
||||
/gsd-workspace --new --name payments-rework --repos . --auto
|
||||
```
|
||||
|
||||
GSD accepts all defaults without prompting.
|
||||
|
||||
---
|
||||
|
||||
## Initialise GSD inside the workspace
|
||||
|
||||
After creating a workspace, move into it and initialise a GSD project:
|
||||
|
||||
```bash
|
||||
cd ~/gsd-workspaces/feature-b
|
||||
/gsd-new-project
|
||||
```
|
||||
|
||||
The `.planning/` directory inside the workspace is the root for all subsequent GSD commands run from that directory. It is entirely separate from any `.planning/` that exists in the source repos.
|
||||
|
||||
---
|
||||
|
||||
## List workspaces
|
||||
|
||||
```bash
|
||||
/gsd-workspace --list
|
||||
```
|
||||
|
||||
Prints all active GSD workspaces and their status.
|
||||
|
||||
---
|
||||
|
||||
## Remove a workspace
|
||||
|
||||
```bash
|
||||
/gsd-workspace --remove feature-b
|
||||
```
|
||||
|
||||
GSD removes the git worktrees and cleans up the workspace directory. This does not delete the branches from the origin remote — only the local worktrees and workspace directory.
|
||||
|
||||
---
|
||||
|
||||
## When to use workspaces instead of workstreams
|
||||
|
||||
Choose workspaces when:
|
||||
|
||||
- You are working across **multiple repositories** that need to be co-ordinated under one GSD project (e.g., an API repo and a UI repo that ship together)
|
||||
- You need a **separate git worktree** with its own branch, lock files, and build artefacts per feature — so builds and dependency installs in one environment cannot affect another
|
||||
- You want a **wholly independent `.planning/` root** rather than a subdirectory of the main repo's `.planning/`
|
||||
- You are following an issue-driven workflow where each tracker issue maps to a workspace (see [Drive GSD from a tracker issue](drive-gsd-from-a-tracker-issue.md))
|
||||
|
||||
Choose [workstreams](work-in-parallel-with-workstreams.md) instead when:
|
||||
|
||||
- All the work lives in **one repository** and shares the same git history
|
||||
- You want to run `/gsd-plan-phase` or `/gsd-discuss-phase` on different concern areas concurrently — API, UI, infra — without context bleed between their `STATE.md` files
|
||||
- You do not need a separate worktree per concern; switching planning context is sufficient
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Work in parallel with workstreams](work-in-parallel-with-workstreams.md)
|
||||
- [Drive GSD from a tracker issue](drive-gsd-from-a-tracker-issue.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
145
docs/how-to/migrate-from-gsd-2.md
Normal file
145
docs/how-to/migrate-from-gsd-2.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# How to migrate from GSD-2
|
||||
|
||||
**Goal:** Bring an older GSD-2 project (`.gsd/` directory layout) forward into GSD Core (`.planning/` layout), and optionally absorb any existing ADRs, PRDs, or specs that live in the repository into the new planning structure.
|
||||
|
||||
**Prerequisites:** GSD Core is installed. The GSD-2 project directory is available on disk.
|
||||
|
||||
---
|
||||
|
||||
## Understand what migrates
|
||||
|
||||
GSD-2 used a `.gsd/` directory as its planning root. GSD Core uses `.planning/`. The migration reverses this: it reads `.gsd/` artifacts and writes them into the standard `.planning/` structure that all GSD Core commands expect.
|
||||
|
||||
| What exists in GSD-2 | What `/gsd-import --from-gsd2` produces |
|
||||
|----------------------|-----------------------------------------|
|
||||
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
|
||||
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
|
||||
| `.gsd/STATE.md` | `.planning/STATE.md` |
|
||||
| `.gsd/phases/` directories | `.planning/phases/` directories |
|
||||
| Phase `PLAN.md` files | GSD Core `{NN}-{MM}-PLAN.md` files (renaming enforced) |
|
||||
|
||||
Conflict detection runs before any files are written. If the target directory already has a `PROJECT.md` and the imported content contradicts it, the migration stops at the BLOCKER gate and lists the conflicts for you to resolve.
|
||||
|
||||
---
|
||||
|
||||
## Run the migration
|
||||
|
||||
### Migrate the current directory
|
||||
|
||||
```bash
|
||||
/gsd-import --from-gsd2
|
||||
```
|
||||
|
||||
GSD reads `.gsd/` in the current working directory and writes the migrated artifacts into `.planning/`.
|
||||
|
||||
### Migrate from a different path
|
||||
|
||||
```bash
|
||||
/gsd-import --from-gsd2 --path ~/projects/old-project
|
||||
```
|
||||
|
||||
Use `--path` when the GSD-2 project is not your current working directory.
|
||||
|
||||
---
|
||||
|
||||
## Resolve conflicts
|
||||
|
||||
If conflict detection finds blockers — for example, a GSD-2 tech-stack declaration that contradicts an existing `.planning/PROJECT.md` — it prints a conflict report and stops without writing any files.
|
||||
|
||||
Read the report, resolve the contradiction (edit the source document or the existing planning artifact), then re-run `/gsd-import --from-gsd2`. The migration is safe to re-run until it passes cleanly.
|
||||
|
||||
---
|
||||
|
||||
## Import an external plan file
|
||||
|
||||
If you have a standalone plan document (a team planning document, a Markdown spec, an exported task list) rather than a full GSD-2 project, use `--from` instead:
|
||||
|
||||
```bash
|
||||
/gsd-import --from /tmp/team-plan.md
|
||||
```
|
||||
|
||||
GSD performs the same conflict-detection pass, converts the content to GSD Core `PLAN.md` format, and validates the result with the plan-checker. After validation you will see the target filename and next steps.
|
||||
|
||||
---
|
||||
|
||||
## Absorb existing documentation
|
||||
|
||||
If your repository already contains ADRs (Architecture Decision Records), PRDs, or specification documents, use `/gsd-ingest-docs` to synthesise them into the `.planning/` structure after migration:
|
||||
|
||||
### Scan the whole repository (auto-detects mode)
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs
|
||||
```
|
||||
|
||||
If `.planning/` is already present (for example, from the migration you just ran), GSD defaults to merge mode — it synthesises the ingested documents alongside what is already there rather than overwriting it.
|
||||
|
||||
### Scope to a specific directory
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs docs/
|
||||
/gsd-ingest-docs docs/adr/
|
||||
```
|
||||
|
||||
### Use an explicit precedence manifest
|
||||
|
||||
When documents have mixed types or you want to control which document wins on conflicts:
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs --manifest ingest.yaml
|
||||
```
|
||||
|
||||
The manifest is a YAML file listing `{path, type, precedence?}` per document. See the `--manifest` flag description in [Commands](../COMMANDS.md) for the expected shape.
|
||||
|
||||
### Force a specific mode
|
||||
|
||||
```bash
|
||||
/gsd-ingest-docs --mode merge # Merge into existing .planning/
|
||||
/gsd-ingest-docs --mode new # Bootstrap from scratch (overwrites)
|
||||
```
|
||||
|
||||
**Output:** `/gsd-ingest-docs` always produces an `INGEST-CONFLICTS.md` with three buckets — auto-resolved, competing-variants, and unresolved-blockers. Review this file after every ingest run. Hard-stops only occur on LOCKED-vs-LOCKED ADR contradictions; everything else is surfaced for your review, not silently discarded.
|
||||
|
||||
---
|
||||
|
||||
## Verify the migrated project
|
||||
|
||||
Once migration and any doc ingestion are complete, confirm the project state is consistent:
|
||||
|
||||
```bash
|
||||
/gsd-health
|
||||
/gsd-health --repair
|
||||
```
|
||||
|
||||
`/gsd-health` checks `.planning/` directory integrity and reports any drift. `--repair` auto-fixes recoverable issues.
|
||||
|
||||
Then check that GSD Core can read your project state:
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
If the project came across cleanly you will see the current phase status and the recommended next step. From here the standard GSD Core workflow applies.
|
||||
|
||||
---
|
||||
|
||||
## Conditionals: what migrates and what does not
|
||||
|
||||
| Situation | What to do |
|
||||
|-----------|-----------|
|
||||
| `.gsd/` exists in the current directory | Run `/gsd-import --from-gsd2` (no `--path` needed) |
|
||||
| `.gsd/` is in a different directory | Use `--path ~/projects/old-project` |
|
||||
| You have a standalone plan document, not a full GSD-2 project | Use `/gsd-import --from /path/to/plan.md` |
|
||||
| You have ADRs in `docs/adr/` | Run `/gsd-ingest-docs docs/adr/` after migration |
|
||||
| You have a mix of ADRs, PRDs, and specs | Run `/gsd-ingest-docs` at repo root; it classifies automatically |
|
||||
| Conflict detection reports blockers | Resolve the listed contradictions then re-run; no files are written until all blockers clear |
|
||||
| You are not sure whether migration worked | Run `/gsd-health` and `/gsd-progress` to confirm |
|
||||
| INGEST-CONFLICTS.md lists unresolved blockers | These require manual resolution before affected documents are incorporated into planning |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Your first project](../tutorials/your-first-project.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
216
docs/how-to/plan-a-phase.md
Normal file
216
docs/how-to/plan-a-phase.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# How to plan a phase
|
||||
|
||||
**Goal:** Turn phase decisions and research into an atomic, verifiable task plan ready for execution.
|
||||
|
||||
**Prerequisites:** `.planning/ROADMAP.md` exists. A `{phase}-CONTEXT.md` from `/gsd-discuss-phase` is strongly recommended but not required.
|
||||
|
||||
---
|
||||
|
||||
## Run the standard planning flow
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 2
|
||||
```
|
||||
|
||||
This runs three stages in sequence:
|
||||
|
||||
1. **Research** — A `gsd-phase-researcher` subagent investigates the domain and writes `{phase}-RESEARCH.md`.
|
||||
2. **Plan** — A `gsd-planner` subagent reads context, research, and requirements, then writes one or more `{phase}-{N}-PLAN.md` files.
|
||||
3. **Verify** — A `gsd-plan-checker` subagent validates plan quality across eight dimensions and triggers a revision loop (up to three iterations) until quality gates pass.
|
||||
|
||||
If no phase number is given, GSD Core targets the next unplanned phase from the roadmap.
|
||||
|
||||
---
|
||||
|
||||
## Skip or force research
|
||||
|
||||
**If the domain is familiar and you do not need new research:**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --skip-research
|
||||
```
|
||||
|
||||
**If RESEARCH.md already exists but you want to force a refresh:**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --research
|
||||
```
|
||||
|
||||
**If you want to run research only** — write RESEARCH.md and exit before planning:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --research-phase 4
|
||||
```
|
||||
|
||||
If RESEARCH.md already exists, you are prompted to update, view, or skip. To force-refresh without the prompt:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --research-phase 4 --research
|
||||
```
|
||||
|
||||
To print existing RESEARCH.md to stdout without spawning the researcher:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --research-phase 4 --view
|
||||
```
|
||||
|
||||
Note: `--research-phase <N>` is a flag on `/gsd-plan-phase`. There is no standalone research-phase command — the removed standalone research command was retired in favour of this flag.
|
||||
|
||||
---
|
||||
|
||||
## Plan vertical feature slices instead of horizontal layers
|
||||
|
||||
**If you want tasks organised as thin end-to-end slices** (UI → API → DB per feature) rather than by technical layer:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --mvp
|
||||
```
|
||||
|
||||
On Phase 1 of a new project with no prior phase summaries, `--mvp` also produces `SKELETON.md` — a Walking Skeleton covering project scaffold, routing, one real DB read/write, one real UI interaction, and dev deployment.
|
||||
|
||||
You can persist MVP mode for a phase without the flag by adding `**Mode:** mvp` to that phase's entry in ROADMAP.md.
|
||||
|
||||
---
|
||||
|
||||
## Require a failing test per behaviour-adding task
|
||||
|
||||
**If you want TDD enforcement** — each behaviour-adding task begins with a failing test before implementation:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --tdd
|
||||
```
|
||||
|
||||
Composable with `--mvp`:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --mvp --tdd
|
||||
```
|
||||
|
||||
This produces vertical slices where every behaviour-adding task follows RED → GREEN → REFACTOR. The planner applies `type: tdd` to eligible tasks (business logic, API endpoints, data transformations) and uses standard `type: execute` for UI, configuration, and glue code.
|
||||
|
||||
TDD mode can also be persisted in config:
|
||||
|
||||
```bash
|
||||
node gsd-tools.cjs config-set workflow.tdd_mode true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Replan using cross-AI review feedback
|
||||
|
||||
**If you have run `/gsd-review --phase N` and a `REVIEWS.md` exists:**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --reviews
|
||||
```
|
||||
|
||||
The planner reads `REVIEWS.md` and revises plans to address the feedback. Cannot be combined with `--gaps`.
|
||||
|
||||
**If you want an automated loop** — replan and re-review until no HIGH concerns remain:
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3
|
||||
```
|
||||
|
||||
The convergence loop runs plan → review → replan → re-review cycles (up to three by default). Use `--max-cycles N` to override the cap.
|
||||
|
||||
---
|
||||
|
||||
## Close gaps after a failed verification
|
||||
|
||||
**If `VERIFICATION.md` exists with unresolved gaps and you want to replan against those gaps only:**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --gaps
|
||||
```
|
||||
|
||||
Research is skipped; the planner reads the verification gaps directly.
|
||||
|
||||
---
|
||||
|
||||
## Validate project state before planning begins
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 2 --validate
|
||||
```
|
||||
|
||||
Runs state validation before spawning the researcher. Use this if you suspect ROADMAP.md or STATE.md has drifted.
|
||||
|
||||
---
|
||||
|
||||
## Run an external bounce validation after planning
|
||||
|
||||
**If `workflow.plan_bounce_script` is configured and you want external validation of the finished plan:**
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --bounce
|
||||
```
|
||||
|
||||
To skip bounce even if it is enabled in config:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1 --skip-bounce
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Suppress interactive confirmations
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase --auto
|
||||
```
|
||||
|
||||
Skips all prompts. Useful in automated pipelines. Research is skipped if `research_enabled` is false in config.
|
||||
|
||||
---
|
||||
|
||||
## What the plan produces
|
||||
|
||||
A successful run writes:
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `{phase}-RESEARCH.md` | Domain research, package legitimacy audit, validation architecture |
|
||||
| `{phase}-VALIDATION.md` | Nyquist test-mapping — the test cases the plan must satisfy (Dimension 8) |
|
||||
| `{phase}-{N}-PLAN.md` | Executable task plan with frontmatter, wave assignments, and acceptance criteria |
|
||||
| `{phase}/SKELETON.md` | Walking Skeleton (MVP mode, Phase 1 of new project only) |
|
||||
|
||||
Each PLAN.md contains tasks with mandatory `<read_first>` and `<acceptance_criteria>` fields. Every `<acceptance_criteria>` entry is verifiable as a source assertion, behaviour assertion, test command, or CLI output — never subjective language.
|
||||
|
||||
For the full field reference see [PLAN.md schema](../reference/plan-md.md).
|
||||
|
||||
### Plan quality dimensions
|
||||
|
||||
The `gsd-plan-checker` validates plans across eight dimensions before allowing execution:
|
||||
|
||||
1. Task atomicity — each task is a single concern
|
||||
2. Dependency correctness — wave ordering is consistent
|
||||
3. Acceptance criteria verifiability — no subjective criteria
|
||||
4. `<read_first>` completeness — the file being modified is always listed
|
||||
5. Concrete `<action>` values — no vague "align with" instructions
|
||||
6. `must_haves` derived from phase goal
|
||||
7. Requirement ID coverage — every phase requirement ID appears in at least one plan
|
||||
8. Nyquist test mapping — plans address the validation strategy in VALIDATION.md
|
||||
|
||||
The revision loop runs up to three times. If quality gates have not passed after three iterations, the checker surfaces remaining issues for manual review.
|
||||
|
||||
---
|
||||
|
||||
## Replanning a closed phase
|
||||
|
||||
If a phase has `VERIFICATION.md` with `status: passed`, it is considered closed. Attempting to replan it stops with an error. If the closeout was incorrect, override with `--force`:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 2 --force
|
||||
```
|
||||
|
||||
A warning is emitted into the transcript and any committed plan docs.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Discuss a phase](discuss-a-phase.md)
|
||||
- [Execute a phase](execute-a-phase.md)
|
||||
- [PLAN.md schema](../reference/plan-md.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
323
docs/how-to/recover-and-troubleshoot.md
Normal file
323
docs/how-to/recover-and-troubleshoot.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# How to recover and troubleshoot
|
||||
|
||||
**Goal:** Identify and fix common problems — from lost context and corrupted state to installation failures and permission errors — using a conditional recipe structure.
|
||||
|
||||
**Prerequisites:** GSD Core is installed. For install problems specifically, see [Install on your runtime](install-on-your-runtime.md).
|
||||
|
||||
---
|
||||
|
||||
## Context and session problems
|
||||
|
||||
### If you have lost track of where you are
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
Reads all state files and tells you exactly where you are and what to do next.
|
||||
|
||||
To automatically advance to the correct next step:
|
||||
|
||||
```bash
|
||||
/gsd-progress --next
|
||||
```
|
||||
|
||||
### If you are starting a new session and need to restore context
|
||||
|
||||
```bash
|
||||
/gsd-resume-work
|
||||
```
|
||||
|
||||
Restores your full session context from the last handoff, including current phase, planning decisions, and where work stopped.
|
||||
|
||||
### If quality is dropping during a long session
|
||||
|
||||
Clear your context window between major commands:
|
||||
|
||||
```bash
|
||||
/clear
|
||||
```
|
||||
|
||||
Then restore state:
|
||||
|
||||
```bash
|
||||
/gsd-resume-work
|
||||
```
|
||||
|
||||
GSD is designed around fresh contexts. Every subagent already gets a clean 200k window. The main session degrades over time — clearing it and resuming is the correct remedy, not pushing on.
|
||||
|
||||
### If you want to save context before stopping
|
||||
|
||||
```bash
|
||||
/gsd-pause-work
|
||||
```
|
||||
|
||||
Creates `.planning/HANDOFF.json` with your current position. Add `--report` to also write a post-session summary to `.planning/reports/`:
|
||||
|
||||
```bash
|
||||
/gsd-pause-work --report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Planning integrity problems
|
||||
|
||||
### If `.planning/` integrity is uncertain
|
||||
|
||||
```bash
|
||||
/gsd-health
|
||||
```
|
||||
|
||||
Reports status across errors, warnings, and informational notes:
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `HEALTHY` | All expected artefacts present and well-formed |
|
||||
| `DEGRADED` | Warnings that should be addressed but work can continue |
|
||||
| `BROKEN` | Critical errors that will block execution |
|
||||
|
||||
Common auto-repairable issues (errors E004, E005; warnings W003, W008):
|
||||
|
||||
```bash
|
||||
/gsd-health --repair
|
||||
```
|
||||
|
||||
This recreates missing `STATE.md`, resets a corrupt `config.json` to defaults, and adds any missing configuration keys. It will not overwrite `PROJECT.md` or `ROADMAP.md`.
|
||||
|
||||
### If STATE.md references a phase that does not exist
|
||||
|
||||
This produces warning `W002`. Use the state CLI to diagnose and repair:
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
|
||||
```
|
||||
|
||||
Preview what a sync would change without writing:
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
|
||||
```
|
||||
|
||||
Apply the sync:
|
||||
|
||||
```bash
|
||||
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
|
||||
```
|
||||
|
||||
These commands reconstruct `STATE.md` from actual project state on disk. They replace manual `STATE.md` editing.
|
||||
|
||||
### If you see "Project already initialised"
|
||||
|
||||
`.planning/PROJECT.md` already exists. `/gsd-new-project` is a safety check. If you genuinely want to start over, delete the `.planning/` directory first:
|
||||
|
||||
```bash
|
||||
rm -rf .planning/
|
||||
```
|
||||
|
||||
Then re-run `/gsd-new-project`.
|
||||
|
||||
### If context-window utilisation is high
|
||||
|
||||
```bash
|
||||
/gsd-health --context
|
||||
```
|
||||
|
||||
Probes the context-window utilisation guard. Warns at 60 %, critical at 70 %. If you are above the warning threshold, run `/clear` followed by `/gsd-resume-work` before starting the next major command.
|
||||
|
||||
---
|
||||
|
||||
## Execution problems
|
||||
|
||||
### If an executor gets "Permission denied" on Bash commands
|
||||
|
||||
GSD's `gsd-executor` subagents need write-capable Bash access. Add the required patterns to `~/.claude/settings.json` under `permissions.allow`. At minimum:
|
||||
|
||||
```json
|
||||
"Bash(git add:*)",
|
||||
"Bash(git commit:*)",
|
||||
"Bash(git merge:*)",
|
||||
"Bash(git checkout:*)"
|
||||
```
|
||||
|
||||
For stack-specific patterns (Rails, Python, Node, Rust), see the full table in `docs/USER-GUIDE.md` under "Executor Subagent Gets Permission denied".
|
||||
|
||||
Per-project alternative: add the same block to `.claude/settings.local.json` in your project root.
|
||||
|
||||
### If execution fails or produces stubs
|
||||
|
||||
Check whether the plan is too ambitious. Plans should have two or three tasks at most. If tasks are too large they exceed what a single context window can produce reliably. Re-plan the phase with smaller scope:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
For systematic diagnosis of what went wrong, see [Debug a failed execution](debug-a-failed-execution.md).
|
||||
|
||||
### If parallel execution causes build lock errors or pre-commit hook failures
|
||||
|
||||
This is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26. If you are on an older version, or still seeing contention, disable parallel execution:
|
||||
|
||||
```bash
|
||||
/gsd-settings
|
||||
```
|
||||
|
||||
Set `parallelization.enabled` to `false`.
|
||||
|
||||
### If a subagent appears to fail but commits were made
|
||||
|
||||
Check git log before concluding something broke:
|
||||
|
||||
```bash
|
||||
git log --oneline -10
|
||||
```
|
||||
|
||||
A known Claude Code classification bug can report failure while work succeeded. GSD's orchestrators spot-check actual output, but if you see a mismatch, the commits are the ground truth.
|
||||
|
||||
---
|
||||
|
||||
## Plan and phase problems
|
||||
|
||||
### If plans seem wrong or misaligned with your intent
|
||||
|
||||
Run `/gsd-discuss-phase N` before planning. Most plan quality issues come from assumptions that `CONTEXT.md` would have prevented:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1
|
||||
```
|
||||
|
||||
To see what assumptions GSD is currently making without starting a full session:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 3 --assumptions
|
||||
```
|
||||
|
||||
### If you need to change something after execution
|
||||
|
||||
Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes:
|
||||
|
||||
```bash
|
||||
/gsd-quick "Fix the login button not responding on mobile Safari"
|
||||
```
|
||||
|
||||
Or use `/gsd-verify-work N` to systematically identify and fix issues through UAT.
|
||||
|
||||
### If a command appears frozen at "Spawning…"
|
||||
|
||||
Wait. GSD subagents run in a separate context window. Their work is invisible to the parent session while in progress. The liveness note on the spawn line confirms this is expected. Research and planning agents routinely take 1–5 minutes; verification agents can take longer on large phases.
|
||||
|
||||
Do not interrupt the session. Killing it discards in-progress subagent work.
|
||||
|
||||
If it has been more than 10 minutes, check whether the agent task still shows as active in the Claude Code sidebar.
|
||||
|
||||
---
|
||||
|
||||
## Workflow state problems
|
||||
|
||||
### If the workflow seems corrupted or state is inconsistent
|
||||
|
||||
```bash
|
||||
/gsd-forensics
|
||||
```
|
||||
|
||||
Or with a description:
|
||||
|
||||
```bash
|
||||
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
||||
```
|
||||
|
||||
`/gsd-forensics` runs a post-mortem investigation: git history anomalies, artefact integrity, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a report to `.planning/forensics/` and surfaces recommended remediation steps. It is read-only and never modifies your project files.
|
||||
|
||||
### If you need to roll back a phase or plan
|
||||
|
||||
```bash
|
||||
/gsd-undo --phase 03 # Roll back all commits for phase 3
|
||||
/gsd-undo --plan 03-02 # Roll back commits for plan 02 of phase 3
|
||||
/gsd-undo --last 5 # Pick interactively from the 5 most recent GSD commits
|
||||
```
|
||||
|
||||
`/gsd-undo` checks dependent phases before reverting and always shows a confirmation gate.
|
||||
|
||||
---
|
||||
|
||||
## Install and update problems
|
||||
|
||||
### If GSD is not recognised after install
|
||||
|
||||
Restart your runtime. GSD installs slash commands into your runtime's command directory (for example `~/.claude/commands/gsd/`). Most runtimes discover new commands only at startup.
|
||||
|
||||
If the problem persists, verify the install:
|
||||
|
||||
```bash
|
||||
npx @opengsd/gsd-core@latest --claude --local
|
||||
```
|
||||
|
||||
For runtime-specific install paths and troubleshooting, see [Install on your runtime](install-on-your-runtime.md).
|
||||
|
||||
### If an update overwrote your local changes
|
||||
|
||||
Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Reapply your changes:
|
||||
|
||||
```bash
|
||||
/gsd-update --reapply
|
||||
```
|
||||
|
||||
### If you cannot update via npm
|
||||
|
||||
If `npx @opengsd/gsd-core` fails due to npm outages or network restrictions, see `docs/manual-update.md` for a step-by-step manual update procedure that works without npm access.
|
||||
|
||||
For routine updates, see [Update GSD](update-gsd.md).
|
||||
|
||||
---
|
||||
|
||||
## Cost problems
|
||||
|
||||
### If model costs are too high
|
||||
|
||||
Switch to the budget profile:
|
||||
|
||||
```bash
|
||||
/gsd-config --profile budget
|
||||
```
|
||||
|
||||
Disable research and plan-check agents via settings if the domain is familiar:
|
||||
|
||||
```bash
|
||||
/gsd-settings
|
||||
```
|
||||
|
||||
Also audit which MCP servers are enabled. Every enabled MCP server injects its tool schema into every turn. Browser and platform-specific tools can cost 20k+ tokens each. Disable any that the current phase does not need in `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"disabledMcpjsonServers": ["playwright", "mac-tools"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recovery quick reference
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|---------|
|
||||
| Lost context or new session | `/gsd-resume-work` or `/gsd-progress` |
|
||||
| Don't know what step is next | `/gsd-progress --next` |
|
||||
| Phase went wrong | `/gsd-undo --phase NN`, then re-plan |
|
||||
| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
|
||||
| STATE.md out of sync | `state validate` then `state sync` |
|
||||
| `.planning/` integrity uncertain | `/gsd-health`, then `/gsd-health --repair` |
|
||||
| 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-config --profile budget` and `/gsd-settings` to toggle agents off |
|
||||
| Update broke local changes | `/gsd-update --reapply` |
|
||||
| Want session summary | `/gsd-pause-work --report` |
|
||||
| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||
- [Install on your runtime](install-on-your-runtime.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
124
docs/how-to/run-phases-autonomously.md
Normal file
124
docs/how-to/run-phases-autonomously.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# How to run phases autonomously
|
||||
|
||||
Run all remaining phases — or a bounded range of them — unattended, so GSD moves through discuss → plan → execute for each phase without you driving every step.
|
||||
|
||||
For background on what the phase loop is doing during an autonomous run, see [The phase loop](../explanation/the-phase-loop.md).
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An active project with `.planning/ROADMAP.md` and `.planning/STATE.md`
|
||||
- All phases you want to run must be in a state that autonomous mode can drive (pending or in-progress; not already complete)
|
||||
- Any design decisions you care about should already be in `PROJECT.md` or captured via a prior `/gsd-discuss-phase` — autonomous mode can surface grey areas interactively only when you use `--interactive`
|
||||
|
||||
---
|
||||
|
||||
## Run all remaining phases
|
||||
|
||||
```bash
|
||||
/gsd-autonomous
|
||||
```
|
||||
|
||||
GSD reads `ROADMAP.md`, discovers every incomplete phase in numeric order, and runs discuss → plan → execute on each one. After all phases complete it automatically runs the milestone lifecycle: audit → complete → cleanup.
|
||||
|
||||
---
|
||||
|
||||
## Run a specific range of phases
|
||||
|
||||
Use `--from` and `--to` to bound the run. Both flags accept decimal phase numbers (e.g. `3.1`).
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --from 3 # phases 3, 4, 5 … (skip already-done phases 1 and 2)
|
||||
/gsd-autonomous --to 5 # phases up to and including 5
|
||||
/gsd-autonomous --from 3 --to 5 # exactly phases 3, 4, and 5
|
||||
```
|
||||
|
||||
When `--to` is reached the lifecycle step is skipped, because not all milestone phases are done. The completion banner tells you how to resume:
|
||||
|
||||
```text
|
||||
Resume with: /gsd-autonomous --from 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Run with interactive discuss
|
||||
|
||||
By default, autonomous mode answers discuss questions automatically using smart discuss (batch table proposals). If you want to answer design questions yourself while keeping plan and execute out of the main context:
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --interactive
|
||||
```
|
||||
|
||||
In interactive mode:
|
||||
- `/gsd-discuss-phase` runs inline and waits for your answers
|
||||
- Planning and execution are dispatched as background agents so you can discuss the next phase while the current one builds
|
||||
- The main context stays lean — only discuss conversations accumulate
|
||||
|
||||
---
|
||||
|
||||
## What safety gates still apply
|
||||
|
||||
Autonomous mode does not bypass GSD's quality pipeline. Each phase still:
|
||||
|
||||
- Runs the plan-checker before execution
|
||||
- Reads `VERIFICATION.md` after execution and routes on the result
|
||||
- Pauses and asks you what to do when verification status is `human_needed` or `gaps_found`
|
||||
- Stops and presents options (fix and retry, skip phase, or stop) if any step fails
|
||||
|
||||
The only difference from manual execution is that `passed` verification advances automatically — you are not prompted between phases unless a decision is required.
|
||||
|
||||
The package legitimacy gate also remains active. If a plan includes a `checkpoint:human-verify` task for a suspicious package, the executor will stop and surface the checkpoint. Autonomous mode will not silently install flagged packages.
|
||||
|
||||
---
|
||||
|
||||
## When not to use autonomous mode
|
||||
|
||||
Do not use `/gsd-autonomous` when:
|
||||
|
||||
- **Phases have unsettled design decisions.** If you have not run `/gsd-discuss-phase` and your `PROJECT.md` does not capture your preferences, smart discuss will make autonomous choices you may not agree with. Run discuss interactively first, or use `--interactive`.
|
||||
|
||||
- **You need fine-grained control over a single phase.** For one phase, `/gsd-execute-phase N` gives you step-by-step output and lets you react before continuing. Autonomous mode is designed for bulk unattended runs.
|
||||
|
||||
- **The phase has novel or high-risk work.** Autonomous mode skips pauses unless it hits a blocker. On a phase where you expect surprises, stay in the loop with manual execution.
|
||||
|
||||
- **You are mid-phase with partial execution.** Autonomous mode picks up incomplete phases but it does not resume a partially-executed wave. Use `/gsd-execute-phase N` to finish a phase that is already in progress.
|
||||
|
||||
If a run stops partway through, see [Debug a failed execution](debug-a-failed-execution.md) for how to diagnose what went wrong.
|
||||
|
||||
---
|
||||
|
||||
## Checking progress during a run
|
||||
|
||||
Autonomous mode prints a progress banner before each phase:
|
||||
|
||||
```text
|
||||
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
|
||||
```
|
||||
|
||||
If you need to check where the run stands mid-session, open another terminal and run:
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resuming after a stop
|
||||
|
||||
If autonomous mode stops — whether you chose "Stop autonomous mode" from the blocker prompt, or the session was interrupted — resume from where it left off:
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --from 4 # replace 4 with the first incomplete phase number
|
||||
```
|
||||
|
||||
GSD skips already-complete phases automatically, so it is safe to re-run from an earlier phase number if you are not sure where the run stopped.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Execute a phase](execute-a-phase.md)
|
||||
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
159
docs/how-to/set-up-cross-ai-review.md
Normal file
159
docs/how-to/set-up-cross-ai-review.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# How to set up cross-AI review
|
||||
|
||||
**Goal:** Configure which AI reviewers participate in plan review, run a review of a planned phase, and use the feedback to converge on a plan with no HIGH-severity concerns.
|
||||
|
||||
**Prerequisites:** The phase has been planned (`{phase}-PLAN.md` files exist in `.planning/phases/`). At least one external AI CLI is installed and authenticated.
|
||||
|
||||
---
|
||||
|
||||
## Decide which reviewers to use
|
||||
|
||||
GSD Core can route review requests to any combination of: Gemini CLI, Claude (separate session), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio, and llama.cpp.
|
||||
|
||||
Each reviewer runs the same structured prompt against your `PLAN.md` files independently. Because different models have different blind spots, multi-reviewer consensus catches more issues than any single reviewer.
|
||||
|
||||
**If you have no external CLIs installed yet**, install at least one:
|
||||
|
||||
```bash
|
||||
# Gemini CLI (free with Google credentials)
|
||||
npm install -g @google/gemini-cli
|
||||
|
||||
# Antigravity CLI (free with Google credentials)
|
||||
curl -fsSL https://antigravity.google/cli/install.sh | bash
|
||||
|
||||
# Codex CLI
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Set default reviewers (optional)
|
||||
|
||||
By default, `/gsd-review` runs all detected CLIs. To pin a subset as project defaults:
|
||||
|
||||
```bash
|
||||
/gsd-config --integrations
|
||||
```
|
||||
|
||||
The integrations wizard covers API keys, code-review CLI routing, and the `review.default_reviewers` list. Set the list to the reviewers you want as the no-flag default — for example `["gemini","codex"]`.
|
||||
|
||||
Alternatively, set it directly with `gsd-tools`:
|
||||
|
||||
```bash
|
||||
gsd config-set review.default_reviewers '["gemini","codex"]'
|
||||
```
|
||||
|
||||
For the full integration settings schema (API keys, model overrides per reviewer, local server host addresses), see [Configuration](../CONFIGURATION.md).
|
||||
|
||||
---
|
||||
|
||||
## Run a review
|
||||
|
||||
### Standard review (uses your configured defaults or all detected CLIs)
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3
|
||||
```
|
||||
|
||||
GSD invokes each reviewer in sequence, collects structured feedback (Summary, Strengths, Concerns at HIGH/MEDIUM/LOW, Suggestions, Risk Assessment), and writes the combined output to `.planning/phases/03-.../03-REVIEWS.md`.
|
||||
|
||||
### Select a single reviewer for a one-off run
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3 --gemini
|
||||
/gsd-review --phase 3 --codex
|
||||
/gsd-review --phase 3 --cursor
|
||||
```
|
||||
|
||||
Any explicit flag overrides both the `--all` default and `review.default_reviewers` for that run.
|
||||
|
||||
### Run every available reviewer in parallel
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3 --all
|
||||
```
|
||||
|
||||
`--all` always overrides config and runs the full detected set, including any configured local model servers (Ollama, LM Studio, llama.cpp).
|
||||
|
||||
### Local model server reviewers
|
||||
|
||||
If you run Ollama or LM Studio locally, they are included automatically with `--all` when the server is reachable. You can also target them explicitly:
|
||||
|
||||
```bash
|
||||
/gsd-review --phase 3 --ollama
|
||||
/gsd-review --phase 3 --lm-studio
|
||||
```
|
||||
|
||||
Configure the host addresses and model selection under `review.*` keys via `/gsd-config --integrations` if the defaults (`localhost:11434` / `localhost:1234`) do not apply.
|
||||
|
||||
---
|
||||
|
||||
## Read the review output
|
||||
|
||||
The `{padded_phase}-REVIEWS.md` file contains:
|
||||
|
||||
- Individual reviews from each reviewer with severity-classified concerns
|
||||
- A **Consensus Summary** section that synthesises concerns raised by two or more reviewers — start here for the highest-priority signal
|
||||
- A **Divergent Views** section for areas where reviewers disagreed
|
||||
|
||||
---
|
||||
|
||||
## Incorporate feedback into the plan
|
||||
|
||||
Once you have reviewed the output, replan incorporating the feedback:
|
||||
|
||||
```bash
|
||||
/gsd-plan-phase 3 --reviews
|
||||
```
|
||||
|
||||
The planner reads `REVIEWS.md` and adjusts the plans to address the concerns before saving.
|
||||
|
||||
---
|
||||
|
||||
## Automate the plan–review–replan loop
|
||||
|
||||
For phases where you want to iterate until all HIGH-severity concerns are resolved, use the convergence loop:
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3
|
||||
```
|
||||
|
||||
This runs `plan-phase → review → replan → re-review` up to three cycles (default). The loop exits when the HIGH-concern count reaches zero.
|
||||
|
||||
### Convergence with a specific reviewer
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3 --codex
|
||||
/gsd-plan-review-convergence 3 --gemini
|
||||
```
|
||||
|
||||
### Convergence with all reviewers and a higher cycle cap
|
||||
|
||||
```bash
|
||||
/gsd-plan-review-convergence 3 --all --max-cycles 5
|
||||
```
|
||||
|
||||
**Stall detection:** if the HIGH-concern count is not decreasing across cycles, GSD warns you. When the cycle cap is reached with open HIGH concerns, an escalation gate asks whether to proceed or review manually.
|
||||
|
||||
---
|
||||
|
||||
## Conditionals: which reviewers to choose
|
||||
|
||||
| Situation | Recommended approach |
|
||||
|-----------|---------------------|
|
||||
| You have Gemini CLI already installed | `--gemini` is always a good starting reviewer |
|
||||
| You want free multi-reviewer coverage | `--gemini` + `--agy` (both use Google credentials) |
|
||||
| Your project is OpenAI-heavy | add `--codex` for an OpenAI-model perspective |
|
||||
| You want GitHub Copilot's model | add `--opencode` |
|
||||
| You want to avoid API costs entirely | configure Ollama with a local model and use `--ollama` |
|
||||
| You need maximum coverage before a release | `/gsd-plan-review-convergence N --all` |
|
||||
| You're iterating quickly and want fast feedback | pick one CLI: `/gsd-review --phase N --gemini` |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Verify and ship](verify-and-ship.md)
|
||||
- [Configuration](../CONFIGURATION.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
160
docs/how-to/spike-and-sketch.md
Normal file
160
docs/how-to/spike-and-sketch.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# How to spike and sketch before committing
|
||||
|
||||
**Goal:** De-risk an implementation by running focused feasibility experiments (spikes) and exploring visual directions through throwaway HTML mockups (sketches) before committing a phase to any specific approach.
|
||||
|
||||
**Prerequisites:** None. `/gsd-spike` and `/gsd-sketch` create their own storage directories and do not require an initialised GSD project.
|
||||
|
||||
---
|
||||
|
||||
## Decide: spike, sketch, or both
|
||||
|
||||
| You want to answer… | Use |
|
||||
|---|---|
|
||||
| "Will this technical approach actually work?" | `/gsd-spike` |
|
||||
| "Does this layout / interaction / visual treatment feel right?" | `/gsd-sketch` |
|
||||
| "What's the right technical approach, and what should it look like?" | Both, in order: spike first, then sketch |
|
||||
|
||||
Spikes answer binary feasibility questions with executable code and a VALIDATED / INVALIDATED / PARTIAL verdict. Sketches answer visual questions with 2–3 browser-comparable HTML variants. They are complementary — a spike proves the approach is buildable, a sketch proves the design is worth building.
|
||||
|
||||
---
|
||||
|
||||
## Run a spike
|
||||
|
||||
### Interactive intake (default)
|
||||
|
||||
```bash
|
||||
/gsd-spike
|
||||
```
|
||||
|
||||
GSD asks about the technical question, decomposes it into 2–5 independent experiments framed as **Given / When / Then** hypotheses, and asks for confirmation before building.
|
||||
|
||||
### Provide the idea directly
|
||||
|
||||
```bash
|
||||
/gsd-spike "can we stream LLM tokens through SSE"
|
||||
```
|
||||
|
||||
### Skip intake and run immediately
|
||||
|
||||
```bash
|
||||
/gsd-spike --quick "websocket vs SSE latency"
|
||||
```
|
||||
|
||||
`--quick` skips the decomposition conversation and treats the argument as a single spike question. Use this when the question is already specific enough to run without refinement.
|
||||
|
||||
### What each experiment produces
|
||||
|
||||
Each spike in `.planning/spikes/NNN-descriptive-name/` includes:
|
||||
|
||||
- Working code (not pseudocode)
|
||||
- A **Given / When / Then** hypothesis written before any code
|
||||
- An investigation trail documenting edge cases, pivots, and surprises
|
||||
- A **VALIDATED**, **INVALIDATED**, or **PARTIAL** verdict with evidence
|
||||
- A `README.md` with frontmatter, how-to-run instructions, and results
|
||||
|
||||
All spikes are indexed in `.planning/spikes/MANIFEST.md`.
|
||||
|
||||
### Package the findings
|
||||
|
||||
When you have signal, wrap the findings into a project-local skill so future sessions load them automatically:
|
||||
|
||||
```bash
|
||||
/gsd-spike --wrap-up
|
||||
```
|
||||
|
||||
This writes `.claude/skills/spike-findings-[project]/`. The skill is discovered automatically and loaded by subsequent `/gsd-sketch`, `/gsd-ui-phase`, and `/gsd-plan-phase` runs — you do not need to reference it explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Run a sketch
|
||||
|
||||
### Mood intake (default)
|
||||
|
||||
```bash
|
||||
/gsd-sketch
|
||||
```
|
||||
|
||||
GSD opens a short conversation to explore feel, visual references, and the core user action before any code is written. It asks one question at a time and only starts building when you say go.
|
||||
|
||||
### Provide a design direction directly
|
||||
|
||||
```bash
|
||||
/gsd-sketch "dashboard layout"
|
||||
```
|
||||
|
||||
### Skip mood intake and run immediately
|
||||
|
||||
```bash
|
||||
/gsd-sketch --quick "sidebar navigation"
|
||||
```
|
||||
|
||||
`--quick` skips the intake conversation entirely and uses the argument as the design direction.
|
||||
|
||||
### Non-Claude runtimes (Codex, Gemini CLI, etc.)
|
||||
|
||||
```bash
|
||||
/gsd-sketch --text "onboarding flow"
|
||||
```
|
||||
|
||||
`--text` replaces interactive prompts with plain-text numbered lists. Use this when your runtime does not support `AskUserQuestion`.
|
||||
|
||||
### What each sketch produces
|
||||
|
||||
Each sketch in `.planning/sketches/NNN-descriptive-name/` includes:
|
||||
|
||||
- `index.html` with 2–3 variants accessible via tab navigation — open directly in a browser, no build step
|
||||
- Functional interactive elements (hover, click, transitions)
|
||||
- Real-ish content using field names and data shapes from any prior spike findings
|
||||
- Shared CSS variables from `.planning/sketches/themes/default.css`
|
||||
- A `README.md` with the design question, variants, and what to look for
|
||||
|
||||
All sketches are indexed in `.planning/sketches/MANIFEST.md`.
|
||||
|
||||
### Package the winning design decisions
|
||||
|
||||
After picking a variant, capture the visual decisions into a project-local skill:
|
||||
|
||||
```bash
|
||||
/gsd-sketch --wrap-up
|
||||
```
|
||||
|
||||
This writes `.claude/skills/sketch-findings-[project]/`. The skill is picked up automatically by `/gsd-ui-phase` — pre-validated decisions (layout, colour palette, typography, spacing) are treated as locked and are not re-asked.
|
||||
|
||||
---
|
||||
|
||||
## Combined flow: spike → sketch → phase
|
||||
|
||||
This is the recommended sequence when you are uncertain about both technical feasibility and visual direction:
|
||||
|
||||
```bash
|
||||
/gsd-spike "SSE vs WebSocket for real-time feed"
|
||||
/gsd-spike --wrap-up
|
||||
|
||||
/gsd-sketch "real-time feed UI"
|
||||
/gsd-sketch --wrap-up
|
||||
|
||||
/gsd-discuss-phase N
|
||||
/gsd-plan-phase N
|
||||
```
|
||||
|
||||
The spike findings inform the sketch (real data shapes, real interaction states, realistic constraints). Both wrap-ups persist decisions that the planner and UI researcher load automatically, so you do not need to re-explain choices during `/gsd-discuss-phase` or `/gsd-ui-phase`.
|
||||
|
||||
---
|
||||
|
||||
## How a spike or sketch feeds into a phase
|
||||
|
||||
Spike and sketch artifacts do not need to be manually referenced. GSD reads them automatically at two points:
|
||||
|
||||
1. **`/gsd-sketch`** — loads `.claude/skills/spike-findings-*/` before building mockups, so variants reflect proven constraints (streaming states, real field names, etc.)
|
||||
2. **`/gsd-ui-phase N`** — loads `.claude/skills/sketch-findings-*/` before generating the UI design contract; pre-validated design decisions are treated as locked
|
||||
|
||||
The planner also reads spike findings when a `spike-findings-*` skill is present, so validated technical choices (which library, which protocol, which data format) flow directly into task plans without repeated explanation.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Design a UI phase](design-a-ui-phase.md)
|
||||
- [Plan a phase](plan-a-phase.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
120
docs/how-to/update-gsd.md
Normal file
120
docs/how-to/update-gsd.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# How to update GSD Core
|
||||
|
||||
Update an existing GSD Core install to the latest release, preview the changelog before committing, and recover any local customisations that the update would overwrite.
|
||||
|
||||
**What you need:** The same runtime GSD is installed for. The update command re-runs the installer under the hood, so it needs Node.js and npx available (same requirement as the original install).
|
||||
|
||||
---
|
||||
|
||||
## The standard update path
|
||||
|
||||
From inside your AI runtime, run:
|
||||
|
||||
```bash
|
||||
/gsd-update
|
||||
```
|
||||
|
||||
GSD will:
|
||||
|
||||
1. Detect the installed version and install scope (global or local).
|
||||
2. Check npm for the latest release of `@opengsd/gsd-core`.
|
||||
3. Fetch the changelog and show you what changed between your installed version and the latest.
|
||||
4. Ask for confirmation before touching anything.
|
||||
5. Back up any user-added files found inside GSD-managed directories to `gsd-user-files-backup/`.
|
||||
6. Run the installer (`npx @opengsd/gsd-core@latest --<runtime> --<scope>`).
|
||||
7. Clear the update-check cache so the statusline indicator resets.
|
||||
8. Report whether locally modified GSD files were backed up to `gsd-local-patches/`.
|
||||
|
||||
Restart your runtime after the update to pick up new commands and agents.
|
||||
|
||||
---
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | What it does |
|
||||
|------|--------------|
|
||||
| `--sync` | After updating, sync skills from the GSD registry |
|
||||
| `--reapply` | After updating, merge locally modified GSD files back in from `gsd-local-patches/` |
|
||||
|
||||
```bash
|
||||
/gsd-update --sync # Update and sync skills
|
||||
/gsd-update --reapply # Update and reapply local patches
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reviewing the changelog before updating
|
||||
|
||||
`/gsd-update` always shows the changelog diff between your installed version and the latest *before* it asks for confirmation. You do not need to visit GitHub separately. The output looks like:
|
||||
|
||||
```text
|
||||
## GSD Update Available
|
||||
|
||||
Installed: 1.39.0
|
||||
Latest: 1.41.0
|
||||
|
||||
### What's New
|
||||
────────────────────────────────────────────────────────────
|
||||
[changelog entries for 1.40.0 and 1.41.0]
|
||||
────────────────────────────────────────────────────────────
|
||||
|
||||
Proceed with update? [Yes, update now / No, cancel]
|
||||
```
|
||||
|
||||
If the changelog cannot be fetched (no network access, npm outage), the update still proceeds after confirmation — it does not block on changelog availability.
|
||||
|
||||
---
|
||||
|
||||
## Recovering local customisations
|
||||
|
||||
### Files you added inside GSD-managed directories
|
||||
|
||||
If you placed custom files inside directories that GSD owns (for example, custom agents prefixed with `gsd-` or extra files in `commands/gsd/`), the installer will detect them and copy them to `gsd-user-files-backup/` before wiping those directories. After the update, restore them manually from that backup location.
|
||||
|
||||
Files you placed outside GSD-managed directories — custom agents not prefixed with `gsd-`, custom commands outside `commands/gsd/`, your `CLAUDE.md` files, and custom hooks — are never touched by the installer.
|
||||
|
||||
### GSD files you modified directly
|
||||
|
||||
If you edited a file that GSD installed (for example, tweaking an agent's system prompt), the installer detects the modification via a hash comparison against its manifest, backs the file up to `gsd-local-patches/`, and then replaces it with the new version. After the update:
|
||||
|
||||
```bash
|
||||
/gsd-update --reapply
|
||||
```
|
||||
|
||||
This merges your modifications from `gsd-local-patches/` back into the newly installed files.
|
||||
|
||||
If you skipped `--reapply` after a previous update and want to apply patches now:
|
||||
|
||||
```bash
|
||||
/gsd-update --reapply
|
||||
```
|
||||
|
||||
It is safe to run `--reapply` on its own without triggering a new download — if you are already on the latest version, GSD skips the install step and goes straight to reapplying patches.
|
||||
|
||||
---
|
||||
|
||||
## When npm is unavailable
|
||||
|
||||
If `npx @opengsd/gsd-core@latest` fails due to an npm outage, network restrictions, or because you are working from the source repository, use the manual update procedure in [docs/manual-update.md](../manual-update.md). That document covers pulling the latest commit, building the hooks dist, and running `node bin/install.js` directly.
|
||||
|
||||
---
|
||||
|
||||
## If you are already on the latest version
|
||||
|
||||
`/gsd-update` exits early with a confirmation message — no download, no install, no restart needed.
|
||||
|
||||
---
|
||||
|
||||
## Installer migrations
|
||||
|
||||
Each GSD release may include installer migrations that rename, move, or retire managed files. The migration layer runs automatically before the new package payload is written. Migrations that would affect files you have modified prompt for confirmation rather than acting silently. For the full design and runtime-configuration contract registry, see [docs/installer-migrations.md](../installer-migrations.md).
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Install on your runtime](install-on-your-runtime.md)
|
||||
- [Commands reference](../COMMANDS.md)
|
||||
- [Manual update](../manual-update.md)
|
||||
- [Installer migrations](../installer-migrations.md)
|
||||
- [Docs index](../README.md)
|
||||
124
docs/how-to/verify-and-ship.md
Normal file
124
docs/how-to/verify-and-ship.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# How to verify and ship a phase
|
||||
|
||||
**Goal:** Walk executed work through user acceptance testing, diagnose and fix any failures, then open a pull request with an auto-generated body.
|
||||
|
||||
**Prerequisites:** The phase has been executed and has `SUMMARY.md` files. If execution is not yet done, see [Execute a phase](execute-a-phase.md).
|
||||
|
||||
---
|
||||
|
||||
## Run user acceptance testing
|
||||
|
||||
```bash
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
GSD reads the phase's `SUMMARY.md` files, extracts user-observable deliverables, and walks you through them one at a time. For each checkpoint it presents what *should* happen and asks whether reality matches.
|
||||
|
||||
- `yes` / `y` / empty → pass, move to next test
|
||||
- Anything else → recorded as an issue, severity inferred from your description
|
||||
|
||||
You never need to categorise severity — GSD infers it from your words ("crashes" → blocker, "doesn't work" → major, "looks off" → cosmetic).
|
||||
|
||||
Progress is written to `.planning/phases/01-<name>/01-UAT.md` and survives a `/clear`. If a session is interrupted, re-run `/gsd-verify-work 1` and GSD offers to resume from the last checkpoint.
|
||||
|
||||
---
|
||||
|
||||
## When failures are found: auto-diagnose and fix planning
|
||||
|
||||
If any tests report issues, GSD proceeds automatically:
|
||||
|
||||
1. **Diagnoses root causes** — spawns parallel debug agents, one per issue, and updates `UAT.md` with root causes.
|
||||
2. **Plans gap closure** — spawns a `gsd-planner` in gap-closure mode, which reads `UAT.md` (with diagnoses) and writes new `PLAN.md` files.
|
||||
3. **Verifies the fix plans** — spawns a `gsd-plan-checker` to ensure the plans are executable. If issues are found, the planner and checker iterate up to three times.
|
||||
4. **Presents next step** — when plans pass the checker:
|
||||
|
||||
```
|
||||
Plans verified and ready for execution.
|
||||
|
||||
`/clear` then `/gsd-execute-phase 1 --gaps-only`
|
||||
```
|
||||
|
||||
Run the suggested command to apply fixes, then re-run `/gsd-verify-work 1` to confirm everything passes.
|
||||
|
||||
---
|
||||
|
||||
## When all tests pass: ship the phase
|
||||
|
||||
Once all UAT tests pass (or if this is your first run and no issues are found), the phase is marked complete in `ROADMAP.md` and `STATE.md` automatically.
|
||||
|
||||
```bash
|
||||
/gsd-ship 1
|
||||
```
|
||||
|
||||
GSD runs preflight checks (verification status, clean working tree, branch, remote, `gh` CLI authentication), pushes the branch, and creates a PR:
|
||||
|
||||
```bash
|
||||
/gsd-ship 1 # Ready-for-review PR
|
||||
/gsd-ship 1 --draft # Draft PR — useful when more phases will follow
|
||||
```
|
||||
|
||||
The PR body is assembled from planning artefacts automatically:
|
||||
|
||||
- Phase goal from `ROADMAP.md`
|
||||
- Per-plan summaries from `SUMMARY.md` files and their key files
|
||||
- Requirements addressed (REQ-IDs)
|
||||
- Verification status from `VERIFICATION.md`
|
||||
- Key decisions from `STATE.md`
|
||||
|
||||
No manual body writing required.
|
||||
|
||||
---
|
||||
|
||||
## Optional: code review before or after shipping
|
||||
|
||||
`/gsd-ship` does not run a code review automatically, but you can slot one in at any point:
|
||||
|
||||
**Before verification** (catches issues before UAT):
|
||||
|
||||
```bash
|
||||
/gsd-code-review 1 # Standard review
|
||||
/gsd-code-review 1 --fix # Review then auto-fix Critical + Warning findings
|
||||
```
|
||||
|
||||
**After the PR is open** (to gate on quality before merge):
|
||||
|
||||
```bash
|
||||
/gsd-code-review 1 --depth=deep # Cross-file analysis including import graphs
|
||||
```
|
||||
|
||||
See [Set up cross-AI review](set-up-cross-ai-review.md) to configure Gemini, Codex, or other reviewers for plan review earlier in the cycle.
|
||||
|
||||
---
|
||||
|
||||
## Optional: create a clean PR branch
|
||||
|
||||
If your branch contains `.planning/` commits that you do not want reviewers to see:
|
||||
|
||||
```bash
|
||||
/gsd-pr-branch # Filter against main
|
||||
/gsd-pr-branch develop # Filter against develop
|
||||
```
|
||||
|
||||
`/gsd-pr-branch` creates a new branch with only code changes — planning artefact commits are excluded. Run this before `/gsd-ship` if your team's review policy excludes planning noise.
|
||||
|
||||
---
|
||||
|
||||
## Closing a milestone
|
||||
|
||||
If this was the last phase in the milestone, run the milestone audit and archive it:
|
||||
|
||||
```bash
|
||||
/gsd-audit-milestone # Verify all requirements shipped
|
||||
/gsd-complete-milestone # Archive, create git tag
|
||||
```
|
||||
|
||||
`/gsd-complete-milestone` is the natural next step after the PR merges. See the [The phase loop](../explanation/the-phase-loop.md) for how verification and shipping fit into the full project lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Execute a phase](execute-a-phase.md)
|
||||
- [Set up cross-AI review](set-up-cross-ai-review.md)
|
||||
- [The phase loop](../explanation/the-phase-loop.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
157
docs/how-to/work-in-parallel-with-workstreams.md
Normal file
157
docs/how-to/work-in-parallel-with-workstreams.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# How to work on multiple areas in parallel with workstreams
|
||||
|
||||
**Goal:** Run concurrent work on different milestone areas — backend API, frontend dashboard, infrastructure, or any other concern — without planning state from one area bleeding into another.
|
||||
|
||||
**Prerequisites:** An active GSD Core project (`.planning/ROADMAP.md` exists). If not, run `/gsd-new-project` first.
|
||||
|
||||
---
|
||||
|
||||
## What workstreams are
|
||||
|
||||
A workstream is an isolated planning context within a single codebase. Each workstream gets its own `.planning/workstreams/<name>/` subtree containing independent `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md`, and `phases/` directories. The codebase itself — source code, git history, and branches — is shared across all workstreams.
|
||||
|
||||
```
|
||||
.planning/
|
||||
├── PROJECT.md ← shared
|
||||
├── config.json ← shared
|
||||
├── codebase/ ← shared
|
||||
└── workstreams/
|
||||
├── backend-api/
|
||||
│ ├── STATE.md
|
||||
│ ├── ROADMAP.md
|
||||
│ ├── REQUIREMENTS.md
|
||||
│ └── phases/
|
||||
└── frontend-dash/
|
||||
├── STATE.md
|
||||
├── ROADMAP.md
|
||||
├── REQUIREMENTS.md
|
||||
└── phases/
|
||||
```
|
||||
|
||||
When a workstream is active, every GSD command — `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase` — reads from and writes to that workstream's directory. Switching workstreams redirects all of those commands to a different subtree without touching the source tree.
|
||||
|
||||
---
|
||||
|
||||
## Create a workstream
|
||||
|
||||
```bash
|
||||
/gsd-workstreams create backend-api
|
||||
```
|
||||
|
||||
GSD creates the workstream directory under `.planning/workstreams/backend-api/` and seeds it with a skeleton `STATE.md` and `ROADMAP.md`. The workstream is not automatically activated — you switch to it explicitly.
|
||||
|
||||
---
|
||||
|
||||
## List workstreams
|
||||
|
||||
```bash
|
||||
/gsd-workstreams list
|
||||
```
|
||||
|
||||
Shows all workstreams and which one is currently active in your session.
|
||||
|
||||
---
|
||||
|
||||
## Switch to a workstream
|
||||
|
||||
```bash
|
||||
/gsd-workstreams switch backend-api
|
||||
```
|
||||
|
||||
From this point forward, all GSD workflow commands operate in the `backend-api` context. The switch is session-scoped: when multiple Claude Code terminals are open on the same repo, each session can hold a different active workstream without interfering with the others.
|
||||
|
||||
Once switched, drive the normal phase workflow:
|
||||
|
||||
```bash
|
||||
/gsd-discuss-phase 1
|
||||
/gsd-plan-phase 1
|
||||
/gsd-execute-phase 1
|
||||
/gsd-verify-work 1
|
||||
```
|
||||
|
||||
To work on another area, switch workstreams in a second terminal:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams switch frontend-dash
|
||||
/gsd-discuss-phase 1
|
||||
/gsd-plan-phase 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Check progress across all workstreams
|
||||
|
||||
```bash
|
||||
/gsd-workstreams progress
|
||||
```
|
||||
|
||||
Prints a cross-workstream summary — phase status, current position, and outstanding work for every workstream — without requiring you to switch between them.
|
||||
|
||||
For detailed status on a single workstream:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams status backend-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resume work in a workstream
|
||||
|
||||
After a context reset or a new session, restore your position:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams resume backend-api
|
||||
```
|
||||
|
||||
This activates the workstream and restores your last known position within it, equivalent to switching and then running `/gsd-resume-work`.
|
||||
|
||||
---
|
||||
|
||||
## Archive a completed workstream
|
||||
|
||||
When a workstream's milestone work is done:
|
||||
|
||||
```bash
|
||||
/gsd-workstreams complete backend-api
|
||||
```
|
||||
|
||||
GSD marks the workstream as archived and moves it out of the active listing. The planning artifacts are preserved under `.planning/workstreams/backend-api/` for audit purposes.
|
||||
|
||||
---
|
||||
|
||||
## Scope a single command to a workstream without switching
|
||||
|
||||
If you need to run one command against a specific workstream without changing your session's active context, use the `--ws` flag:
|
||||
|
||||
```bash
|
||||
/gsd-progress --ws frontend-dash
|
||||
/gsd-plan-phase 2 --ws backend-api
|
||||
```
|
||||
|
||||
`--ws` takes highest priority in the resolution order and does not alter the session-scoped pointer.
|
||||
|
||||
---
|
||||
|
||||
## When to use workstreams instead of workspaces
|
||||
|
||||
Choose workstreams when:
|
||||
|
||||
- All the work lives in the **same repository** and shares the same git history
|
||||
- You want to plan or discuss different concern areas (API, UI, infra) **concurrently** without one workstream's `STATE.md` overwriting another's
|
||||
- You do not need a separate branch per workstream at creation time (though you can branch as normal within each workstream's execution)
|
||||
- The overhead of creating full git worktrees is not justified by the isolation you need
|
||||
|
||||
Choose [workspaces](isolate-work-with-workspaces.md) instead when:
|
||||
|
||||
- You are working across **multiple repositories** (e.g., `hr-ui` and `ZeymoAPI`)
|
||||
- You need the isolation of a **separate git worktree** or clone per feature — fully independent branches, lock files, and build artefacts
|
||||
- You want to run `/gsd-new-project` independently in each workspace with a wholly separate `.planning/` root, not a subdirectory of the main repo's `.planning/`
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Isolate work with workspaces](isolate-work-with-workspaces.md)
|
||||
- [The phase loop](../explanation/the-phase-loop.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [docs index](../README.md)
|
||||
Reference in New Issue
Block a user