# Dev Session

> Use when working through a multi-phase feature, bugfix, or GitHub issue that warrants tracked spec/plan/notes artifacts. Triggers: /dev-session command, /dev-session phase names (start/brainstorm/plan/execute/pr/retro/express), starting a new feature branch, picking up a GitHub issue.

- Skill: `lmorchard/dev-session` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add lmorchard/dev-session`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lmorchard/dev-session/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lmorchard (https://skillmd.com/u/lmorchard)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lmorchard/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.

| Argument | Phase file | Purpose |
|---|---|---|
| `start` | `phases/start.md` | Start or resume a session: branch + worktree + session dir |
| `brainstorm` | `phases/brainstorm.md` | Brainstorm a spec interactively (with codebase research substep) |
| `plan` | `phases/plan.md` | Write an implementation plan from the spec |
| `execute` | `phases/execute.md` | Execute the plan phase-by-phase with verification |
| `pr` | `phases/pr.md` | Self-review, squash, push, open PR, run Copilot review |
| `file` | `phases/file.md` | File the spec as a GitHub issue and stop (queue for later or parallel express) |
| `retro` | `phases/retro.md` | End the session with a learning-focused retrospective |
| `express` | `phases/express.md` | Interactive brainstorm → autonomous execution through PR |

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

| File | Purpose |
|---|---|
| `references/spec-template.md` | Skeleton for `spec.md`; used by `brainstorm` |
| `references/plan-template.md` | Skeleton for `plan.md`; used by `plan` |
| `references/pr-body-template.md` | Skeleton for the PR body; used by `pr` |
| `references/documentarian-prompt.md` | Negation rules for the codebase research subagent in `brainstorm` |
| `references/makefile-conventions.md` | Expected Makefile targets and fallbacks |
| `references/github-projects.md` | Optional Projects v2 board integration (CLAUDE.md schema, transition commands) |

## 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.