| 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 <file...> | pkg/layer/cluster/importers/imports/sinks/rationale — orient on an area |
draht-tools graph-impact <file...> | blast radius: reverse-dependents, entry points reached, sinks, boundary warnings |
draht-tools graph-query <term...> | ranked symbol+doc search — replaces grep for "find the X" |
draht-tools graph-callers/-callees <file> [--depth N] | who calls / is called, N hops |
draht-tools graph-path <from> <to> | 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.
/discuss-phase N — capture decisions, gray areas, domain terms/plan-phase N — create atomic execution plans (parallel via architect subagents). Architects emit ---END-PLAN--- to separate plan content from the STATUS: footer./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./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 — proceedSTATUS: DONE_WITH_CONCERNS — proceed; log concerns. If correctness-related, address first.STATUS: NEEDS_CONTEXT — provide missing info and re-dispatch the same agentSTATUS: 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)
<task type="auto">
<n>Task name</n>
<context>Bounded context</context>
<domain>Aggregates/entities touched</domain>
<files>affected files</files>
<test>RED phase — write failing tests first</test>
<action>GREEN phase — minimal impl to pass tests</action>
<refactor>REFACTOR phase — improve without breaking tests</refactor>
<verify>How to verify (tests pass + manual check)</verify>
<done>What "done" looks like as assertions</done>
</task>
Task types: auto, checkpoint:human-verify, checkpoint:decision.
Hooks
The plugin ships workflow hooks under ${CLAUDE_PLUGIN_ROOT}/scripts/:
gsd-pre-execute.cjs <phase> — preconditions before execution (DOMAIN.md, plans, uncommitted changes)gsd-post-task.cjs <phase> <plan> <task> <status> [commit] — record result + type check + tests + TDD cycle checkgsd-post-phase.cjs <phase> — generate phase report, update ROADMAP statusgsd-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 editstop-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):
{
"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 insteadqualityGateStrict — defaults to true: the gate fails (exit 1) on any lint/type/test/coverage miss; set false to demote to warningsstopGate: 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
