gsd-workflow

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.

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)

<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 check
• gsd-post-phase.cjs <phase> — 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):

{
  "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