---
name: devplan
description: >
  Manage feature development plans across coding-agent sessions. Use this skill
  whenever the user mentions: a new feature, user story, or idea to implement;
  starting or finishing a coding session; wanting to see what's planned or in
  progress; asking about the development plan, next session, or current feature
  status. Also trigger when the user says things like "let's work on X", "what
  are we building next", "pick up where we left off", or "mark that done".
  This skill keeps everything organized in .devplans/ markdown files with a
  Babashka CLI for status management.
---

# devplan — Feature Development Plan Manager

## What this organizes

A project with a coding agent grows confusing fast: features accumulate, sessions
get lost, and it's hard to know what's in progress. This skill keeps it simple:
one markdown file per feature in `.devplans/`, each file tracking the feature's
goal, user story, acceptance criteria, and a log of development sessions.

**Plan statuses:** `proposed` → `ready` → `implementing` → `finished`  
**Session statuses:** `planned` → `done` | `discarded`

## The CLI tool

The Babashka script lives at:
`~/.claude/skills/devplan/scripts/devplan.bb`

Run it as: `bb ~/.claude/skills/devplan/scripts/devplan.bb <command>`

Or suggest the user add this alias to their shell profile for convenience:
```bash
alias devplan="bb ~/.claude/skills/devplan/scripts/devplan.bb"
```

**All commands (run from the project root, where `.devplans/` lives):**

```
devplan list                          # table of all plans with status/sessions
devplan show <name>                   # full plan content
devplan new <name> <title>            # create plan file from template
devplan status <name> <status>        # proposed | ready | implementing | finished
devplan session start <name> [goal]   # use existing planned session, or add new one
devplan session add <name> <goal>     # always add a new planned session
devplan session done <name>           # mark first planned session done
devplan session discard <name>        # mark first planned session discarded
```

## The lifecycle — how to use this skill

### 1. New idea or feature request

When the user describes a feature, user story, or next thing to build:

1. Run `devplan new <slug> <Human Title>` to create the plan file
2. Open the created file and fill in:
   - **Goal** — one paragraph, what this achieves and why it matters
   - **Motivation and Context** — why this matters, what situation drives it
   - **Acceptance Criteria** — concrete, checkable items
   - **Technical Notes** — relevant architecture, constraints, dependencies
3. Run `devplan status <name> ready` when the plan is complete enough to start
4. Show the user the plan and ask if they want to adjust anything

### 2. Starting a coding session

When the user wants to work on a feature:

1. Run `devplan list` to orient — show the user what's in progress
2. Run `devplan session start <name> "<specific goal for this session>"`
   - If a `planned` session already exists in the file (pre-written sessions), this reports
     it and does nothing — avoiding duplicate session entries
   - If no planned session exists, it creates a new one (same behavior as `session add`)
3. Run `devplan status <name> implementing` if it isn't already
4. Then proceed with the actual coding work

The session goal should be specific — not "work on auth" but "implement JWT middleware and protect /api routes".

### 3. After a coding session

When the work for a session is complete:

1. Write a short **Outcome** in the plan file under the session header (what was built, what decisions were made, what's left)
2. Check off completed acceptance criteria
3. Run `devplan session done <name>` (or `discard` if the session was abandoned)
4. If the feature is fully done, check all criteria and run `devplan status <name> finished`
5. Run `devplan list` so the user can see the updated state

### 4. Resuming after a break

When the user wants to pick up where they left off:

1. Run `devplan list` to show the current state
2. Run `devplan show <name>` on any `implementing` plans
3. Read the previous session outcomes to understand context
4. Propose the next logical session goal based on what remains

## Plan file format (for reference)

```
---
id: 001
name: user-auth
title: User Authentication
status: implementing
created: 2026-05-09
updated: 2026-05-09
---

# User Authentication

## Goal
...

## Motivation and Context
...

## Acceptance Criteria
- [x] Done criterion
- [ ] Open criterion

## Sessions

### Session 1 · 2026-05-09 · done
**Goal:** Set up user model and JWT generation
**Outcome:** Created User schema with bcrypt hashing, /register and /login endpoints returning JWT. Decided to store token in httpOnly cookie.

### Session 2 · 2026-05-09 · planned
**Goal:** Add JWT validation middleware and protect routes
**Outcome:** 
```

## Key principles

- Keep session goals tight — one clear thing per session is better than a sprawling agenda
- Write the Outcome immediately after a session while it's fresh — future sessions depend on this context
- The plan file is the source of truth; the CLI just manages metadata (status, session headers)
- It's fine for plans to stay `proposed` for a while — that's the backlog