--- name: gsd-workflow description: Draht's Get Shit Done workflow — how to use /new-project, /discuss-phase, /plan-phase, /execute-phase, /verify-work, /next-milestone, /pause-work, /resume-work, /progress, /fix, /quick and the .planning/ directory structure to drive a project from idea to shipping. Use when the user asks how to plan work, structure a project, set up milestones, track progress, or wants to start using draht's workflow. --- # GSD (Get Shit Done) Workflow Draht's GSD workflow is a milestone → phase → plan → task hierarchy that lives in `.planning/` and is driven by slash commands + hooks. ## Directory Structure ``` .planning/ ├── PROJECT.md # what are we building ├── REQUIREMENTS.md # v1 / v2 / out-of-scope ├── ROADMAP.md # phases grouped into milestones ├── DOMAIN.md # bounded contexts + ubiquitous language (DDD) ├── TEST-STRATEGY.md # test framework, levels, coverage ├── STATE.md # current phase, status, last activity ├── CONTINUE-HERE.md # handoff doc (only when paused) ├── execution-log.jsonl # append-only task execution log ├── codebase/ │ ├── MAP.json # queryable knowledge graph (modules, symbols, edges, clusters) │ └── GRAPH_REPORT.md # skimmable graph digest (god nodes, surprising connections, rationale) ├── phases/ │ └── 01-phase-slug/ │ ├── 01-01-PLAN.md │ ├── 01-01-SUMMARY.md │ └── 01-02-PLAN.md └── phase-N-report.md # generated by post-phase hook ``` ## Graph-first orientation `.planning/codebase/MAP.json` + `GRAPH_REPORT.md` are the living map of the codebase. **Before you grep or walk the tree, query the living map.** This is the canonical reference block other skills point to. | Command | Use | |---|---| | `draht-tools graph-context ` | pkg/layer/cluster/importers/imports/sinks/rationale — orient on an area | | `draht-tools graph-impact ` | blast radius: reverse-dependents, entry points reached, sinks, boundary warnings | | `draht-tools graph-query ` | ranked symbol+doc search — replaces grep for "find the X" | | `draht-tools graph-callers/-callees [--depth N]` | who calls / is called, N hops | | `draht-tools graph-path ` | shortest import path between two files | | `draht-tools graph-hotspots` / `graph-clusters [--surprising]` | god nodes / structural clusters (structural ≠ semantic) | | `draht-tools map-graph [--quiet]` | (re)build MAP.json + GRAPH_REPORT.md (the post-phase hook owns refresh) | If `MAP.json` is absent, run `draht-tools map-graph` first. Subagents can't run `draht-tools` — the orchestrator runs the query and pastes the summary into the subagent prompt. ## The Cycle ### Project initialization (once) - **`/new-project`** — greenfield: questioning → domain model → requirements → roadmap - **`/init-project`** — existing codebase: map → extract domain → questioning → roadmap - **`/map-codebase`** — standalone codebase analysis ### Per-phase cycle (fresh session between each step) Each step is **graph-first** (see above): orient via `graph-context`/`graph-query`/`graph-impact` before grepping or walking the tree. 1. **`/discuss-phase N`** — capture decisions, gray areas, domain terms 2. **`/plan-phase N`** — create atomic execution plans (parallel via `architect` subagents). Architects emit `---END-PLAN---` to separate plan content from the `STATUS:` footer. 3. **`/execute-phase N`** — per-task three-stage loop: `implementer → spec-reviewer → reviewer`. TDD red→green→refactor inside each implementer task. Tasks within a plan are sequential; independent plans parallelize. 4. **`/verify-work N`** — parallel `verifier` + `security-auditor` + `reviewer` + `spec-reviewer` (phase-level compliance against the plan files), produce UAT report. Start a fresh session (`/clear`) between steps. Each command assumes a clean context. ### Milestone transition - **`/next-milestone`** — only after ALL phases in the current milestone are `complete` ### Session continuity - **`/pause-work`** — create `CONTINUE-HERE.md` with in-progress state - **`/resume-work`** — read handoff, verify state, continue - **`/progress`** — show current position in the roadmap ### Ad-hoc - **`/quick`** — small task with tracking. Implementer → spec-reviewer → (optional) reviewer. - **`/fix`** — bug fix with 4-phase systematic debugging (root cause → pattern → hypothesis → reproducing-test-first impl). Stops after 3 failed fix attempts. - **`/review`** — parallel `reviewer` + `security-auditor`, plus `spec-reviewer` when a plan is in scope. - **`/atomic-commit`** — analyze diff, split into atomic conventional commits (Red Flag block prevents mixed-concern commits). - **`/orchestrate`** — general-purpose specialist dispatch with parallel / chain / fan-out / two-stage modes. ## Subagent Roster | Agent | Purpose | |---|---| | `architect` | Plan structure before coding | | `implementer` | Write or change code (inside TDD cycle) | | `spec-reviewer` | Verify diff covers exactly what the spec asked — no more, no less | | `reviewer` | Code-quality review (correctness, conventions, domain language) | | `debugger` | Root-cause diagnosis | | `verifier` | Run lint / typecheck / tests, report results | | `security-auditor` | Security audit (injection, secrets, unsafe patterns) | | `git-committer` | Create atomic conventional commits | ## Subagent STATUS Protocol Every draht agent ends with one of four status lines. Orchestrating commands branch on it: - **`STATUS: DONE`** — proceed - **`STATUS: DONE_WITH_CONCERNS`** — proceed; log concerns. If correctness-related, address first. - **`STATUS: NEEDS_CONTEXT`** — provide missing info and re-dispatch the same agent - **`STATUS: BLOCKED`** — STOP. Do not retry the same agent on the same input. Adjust inputs or surface to user. For any spec-driven work, `spec-reviewer` runs **before** `reviewer`. Spec compliance prevents over/under-building; running quality review first lets spec gaps hide. ## Task Format (XML inside PLAN.md files) ```xml Task name Bounded context Aggregates/entities touched affected files RED phase — write failing tests first GREEN phase — minimal impl to pass tests REFACTOR phase — improve without breaking tests How to verify (tests pass + manual check) What "done" looks like as assertions ``` Task types: `auto`, `checkpoint:human-verify`, `checkpoint:decision`. ## Hooks The plugin ships workflow hooks under `${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/`: - `gsd-pre-execute.cjs ` — preconditions before execution (DOMAIN.md, plans, uncommitted changes) - `gsd-post-task.cjs [commit]` — record result + type check + tests + TDD cycle check - `gsd-post-phase.cjs ` — generate phase report, update ROADMAP status - `gsd-quality-gate.cjs [--strict]` — lint + typecheck + test + coverage against `.planning/config.json` threshold These are invoked from inside commands. In addition, two **lifecycle hooks** fire automatically regardless of command prose (registered in `hooks/hooks.json`): - `post-edit-check.cjs` — PostToolUse on Edit/Write: file-scoped lint feedback on every edit - `stop-quality-gate.cjs` — Stop: runs the quality gate when a turn ends with uncommitted source changes in a `.planning` project ## Configuration `.planning/config.json` (optional): ```json { "hooks": { "coverageThreshold": 80, "tddMode": "advisory", "qualityGateStrict": true, "stopGate": true } } ``` - `tddMode: "strict"` — post-task hook aborts on green: commit without preceding red: - `tddMode: "advisory"` — logs a warning instead - `qualityGateStrict` — **defaults to true**: the gate fails (exit 1) on any lint/type/test/coverage miss; set `false` to demote to warnings - `stopGate: false` — disable the automatic Stop-time quality gate - Hard stop: 3 recorded failures for the same task make `gsd-post-task.cjs` exit non-zero — the retry loop ends there ## Key Rules - One phase at a time, one cycle step per session - `/next-milestone` ONLY after every phase in the current milestone is verified - Fix plans include a reproducing test before any implementation - Never skip verification — it's the only thing that marks a phase complete