Dev Session

Dev Session

Structured workflow for development sessions. Each session moves through phases that produce inspectable artifacts (spec.md, research.md, plan.md, notes.md) so context survives across sessions and can be reviewed independently of the code.

Dispatcher

Parse the first argument and read ONLY the matching phase file. Ignore the others.

If no argument is given, find the most recent session directory, read spec.md/plan.md/notes.md to assess current state, and suggest the most appropriate next phase.

Producer / consumer pattern

Front-loading the high-attention work (research + brainstorm) and parallelizing the autonomous work later is the key workflow this skill supports:

1. Producer: start → brainstorm → file files a well-specified issue, then stops. Repeat across several sessions in one focused work block.
2. Consumer: later, run /dev-session express <issue-url> against any of those filed issues — possibly several in parallel. Express detects the embedded spec via the <!-- dev-session:spec --> marker and skips brainstorm, going straight to plan + execute + PR.

This separates "thinking" (you, focused) from "doing" (agent, autonomous).

Shared conventions

Session directory. Session docs live in docs/dev-sessions/{timestamp}-{slug}/ with spec.md, research.md, plan.md, and notes.md. {timestamp} is $(date +"%Y-%m-%d-%H%M"). Derive {slug} from the current git branch name (strip prefixes like feature/, fix/, chore/); otherwise ask for a short description.

CLAUDE.md override. Before creating session artifacts, check the project's CLAUDE.md for a "Dev Sessions" section or any mention of a non-default session directory. Some projects override the location — respect it if specified.

Worktrees. Prefer doing session work in a git worktree at .worktrees/{branch-name}/ (relative to the project root) rather than switching branches in-place. Worktrees isolate the session from the main checkout, enabling concurrent agents and uninterrupted dev servers in other branches.

• Preferred: if superpowers:using-git-worktrees is available, invoke it. It handles directory priority, gitignore verification, dependency install auto-detection, and a baseline test run.
• Fallback: see the inline procedure in phases/start.md.
• Fall back to in-place branch switching only if the project can't support a worktree (uncommitted changes that must stay visible, tooling that requires a fixed path) or the user asks for it.

Worktree gotcha. Untracked files in the main checkout are NOT visible from worktrees. Always create the session directory inside the active worktree, not in the main checkout, and verify it's there before writing artifacts. Always fetch and rebase from origin/main before creating the branch the worktree will track.

Documentarian agent dispatch. When dispatching a subagent (Explore or general-purpose) for codebase research, use the negation rules in references/documentarian-prompt.md. This keeps research factual and prevents the agent from rationalizing toward a chosen solution.

Makefile-first. Verification commands (make lint, make test, make check) assume a project Makefile per references/makefile-conventions.md. If a project lacks one, run native tooling and offer to scaffold the targets the skill expects. If a target the skill names is missing, add it before relying on it.

GitHub Project board (optional). If the project's CLAUDE.md declares a Projects v2 board (see references/github-projects.md), file / start / pr move issues across the board at phase boundaries (Ready → In Progress → In Review). Skipped silently when not configured.

Test-driven by default. In execute, write a failing test first, watch it fail, write minimal code to pass, watch it pass, refactor. The user may opt out for specific phases (pure refactoring, doc changes, infrastructure scaffolding without behavior), but the default is TDD.

Subagent-driven execution. When superpowers:subagent-driven-development is available, prefer it for execute — fresh subagent per phase, two-stage review (spec compliance + code quality), no context pollution. Fall back to inline only when the skill is unavailable or the user explicitly asks for it.

Feel-driven features want a prototype, not autonomous execution. When a feature is dominated by subjective visual/animation/interaction feel (waveforms, transitions, easing, layout density, game-juice) — the kind a spec genuinely can't pin down — do NOT route it through autonomous execute/express. Those lock in visual defaults (shapes, animation model, placement) that the feel-work then discards, and the two-stage reviews dutifully verify a v1 nobody wanted. Instead, during brainstorm flag it as feel-driven and plan an interactive-prototype phase: build a disposable, slider-driven harness (a single self-contained HTML/Canvas page in a gitignored tmp/), iterate with the user until the look is locked, then port the final values into production code + tests once. Seeing beats specifying. (Heuristic: if you find yourself writing "tune by eye" or "TBD, adjust later" into the spec, it's feel-driven.)

Verification before completion. Never claim a phase is done, tests pass, or a build succeeds without having run the verification command in the current message and read the output. Evidence before claims, always. No "should pass" / "I'm confident" / "looks correct" without fresh evidence. This applies in execute (per-phase) and pr (before opening).

References

When NOT to use (The Ceremony Threshold)

Do not blindly generate disk artifacts for every task. Respect the Ceremony Threshold:

• Small/Tactical (< 3 steps, PR reviews, bug fixes, single-file refactors): DO NOT use this skill or generate physical artifacts. Use the internal todowrite tool to track steps silently and keep state entirely in-context. Just do the work.
• Large/Architectural (new features, multi-session work, high ambiguity): Use this skill to structure the workflow and create inspectable artifacts.
• Exploratory or research-only work without an implementation goal.
• Work where the user has explicitly opted out of the structured flow.