plan-dev

Turn a raw task, spec, or review doc into one objective and a dependency-aware task DAG — reviewed by the user before anything is written down.

Why this skill exists

Jumping from "here's a big task" straight to code loses sequencing: risky changes land beside safe ones, reviewers get unrelated diffs, and nothing is trackable. The older version of this skill fixed that but baked in a second problem — it treated one phase = one GitHub issue = one PR. That is wrong for most real objectives: it fragments a single user goal into many PRs, many CI runs, and no place where the combined diff is ever reviewed.

So the output changed. The plan is now an objective plus a task graph: each task declares what it depends on, which files it may write, which validation tier it runs, and which role should do it. That is exactly what orchestrate-dev needs to run tasks in parallel and what deliver-dev needs to ship them as one PR. GitHub issues are still available — as an export, for when the work needs to be visible to people outside the session.

Validation tier

Tier 0. This skill writes plan state; it runs no tests, makes no commits, and pushes nothing.

Input

Parse $ARGUMENTS as one of:

• Free-text task or feature description
• File path to a spec, review doc, or requirements file
• A GitHub issue URL or number to decompose into sub-tasks
• A bullet list of fixes or changes

If empty, prompt: "What should I plan? Paste a task description, file path, or GitHub issue URL."

Required execution flow

1. Fetch and read the input

GitHub issue number or URL:

gh issue view <number> --json title,body,labels,comments

gh is optional. If it is unavailable, ask the user to paste the issue text rather than guessing at it.

File path: read the file fully before proceeding. Other URL: use WebFetch.

Classify each piece of work:

2. Name the objective

One objective per invocation. Give it:

• an id — lowercase slug, e.g. auth-system;
• a title — one sentence of what the user actually wants;
• base_branch — the repo's default branch. Resolve it, never guess it: bash skills/dev-workflow/_shared/scripts/default-branch.sh;
• integration_branch — objective/<id>;
• a delivery.strategy — single-pr by default.

Only choose a strategy other than single-pr when one of the enumerated exceptions in core/policies/delivery.md applies (truly independent deliverables, security isolation, deployment sequencing, explicit user request, or a size/risk threshold). When you do, record delivery.exception_reason naming which one — an unexplained multi-PR plan is the defect this skill exists to prevent.

3. Decompose into tasks

Each task is a work unit, not a delivery unit: it ends at commit + handoff, never at a PR.

Every task declares:

Writing a scope: use **, never a lone *. The check that keeps a worker inside its area is bash pattern matching, where * also matches /. So src/* — the obvious way to write "files directly under src" — actually authorises src/deep/nested/secret.txt as well, and src/*.ts authorises src/a/b.ts. There is no single-level matcher available, so a lone * never means what it looks like it means:

The ** form is sound in the other direction: src/auth/** does not match src/authorization/ or src/auth-backup/, because the literal / after auth stops it. scripts/validate_plan.py rejects any single-* segment, so an accidental one fails at plan time rather than silently widening a worker's write boundary at run time.

Parallelizable is derived, not declared: a task is parallelizable when it has no dependency path to another ready task and its scope does not overlap that task's. Two concurrent tasks sharing write scope is a merge conflict waiting to happen — either narrow the scopes or add a dependency. scripts/validate_plan.py enforces exactly this.

Sizing:

• 2–6 tasks for a typical objective; more than ~8 usually means the objective is really two objectives.
• A task touching >10 files should be split.
• Do not mix a risky refactor and an unrelated feature in one task.

4. Present the plan for review — then STOP

Print the objective, the task table, and the DAG:

## Objective: auth-system — Implement authentication system
Base: main → integration branch: objective/auth-system
Delivery: single-pr

| Task | Role | Depends on | Scope | Tier | Parallel |
|---|---|---|---|---|---|
| task-001 | implementer | — | src/auth/** | worker | yes (with 002) |
| task-002 | implementer | — | migrations/** | worker | yes (with 001) |
| task-003 | implementer | 001, 002 | src/api/routes/** | worker | no |
| task-004 | test-engineer | 003 | tests/** | worker | no |
| task-005 | integrator | 004 | — | integration | no |

Wave 1: task-001, task-002   (parallel)
Wave 2: task-003
Wave 3: task-004
Wave 4: task-005 — integrate, review combined diff, hand to deliver-dev

### task-001 — Add JWT validation middleware
- Files: src/auth/middleware.ts (new), src/auth/index.ts
- Verification: `npm test -- src/auth`; a request with a bad bearer token returns 401

Then say exactly:

"Review the plan above. Reply approved to write it out, or tell me what to change (e.g. 'merge task-001 and task-002', 'add a security review task', 'split task-003')."

Write nothing until the user explicitly approves. Apply feedback and re-display as many times as needed.

5. Multi-platform verification note (agent-kit repos)

REPO_ROOT="$(git rev-parse --show-toplevel)"
bash "$REPO_ROOT/skills/dev-workflow/_shared/scripts/detect-multi-platform-repo.sh" "$REPO_ROOT"

When this exits 0, the integration task's verification must include make repo-standards-gate, and any task touching skills/, hooks/, plugin manifests, or docs/engineering/build-and-release/platform-targets.json must note: update platform-targets.json + README Row 3 when platform behaviour changes.

6. Write the objective state (primary output)

OBJ_DIR=".dev-files/objectives/<id>"
SHARED_DIR="$REPO_ROOT/skills/dev-workflow/_shared/scripts"

# Preferred: the shared helper owns the layout and the schema versions
bash "$SHARED_DIR/objective-state.sh" init "<id>" --title "<title>" --base-branch "<base>"
bash "$SHARED_DIR/objective-state.sh" add-task "<id>" <task-json-file>

If objective-state.sh is unavailable, write the files directly — the layout is the contract, not the helper:

.dev-files/objectives/<id>/
├── objective.json      # core/workflow/objective-schema.json
├── plan.md             # the human-readable plan you just showed
└── tasks/task-00N.json # core/workflow/task-schema.json

Then validate before reporting success:

python3 "$REPO_ROOT/skills/dev-workflow/plan-dev/scripts/validate_plan.py" ".dev-files/objectives/<id>"

Fix every error it reports. A plan that fails this check is not a plan — the graph checks (missing dependency, cycle, parallel tasks sharing write scope) are the ones a human reviewer reliably misses.

.dev-files/ is normally gitignored. Only check it in when the project explicitly wants durable workflow state.

7. Export to GitHub issues — optional

Local state is the source of truth. Issues are for visibility to people who are not in this session and for cross-machine resume.

Export automatically when the user's own request asked for it ("create issues for…", "turn this into tickets") — that is what they asked for and it must keep working. Otherwise ask once:

"Written to .dev-files/objectives/<id>/. Also export to GitHub issues for tracking? (yes / no)"

When exporting, one issue per task:

gh issue create \
  --title "<task title>" \
  --label "<type>" --label "agent:any" \
  --body "$(cat <<'EOF'
## Summary
<what this task does and why it is a coherent unit>

## Objective
`auth-system` — task `task-001` of 5. Delivery: one PR for the whole objective.

## Scope (writable paths)
- `src/auth/**`

## Depends on
<"None (ready)" or "task-002 (issue #N)">

## Verification — tier: worker
- [ ] <targeted check>

## Resume
- **Done:** (none yet)
- **Next:** <first step>
- **Decisions:** (none yet)
- **Blocked:** none
- **Branch:** (unset — assigned at worker start)
- **Worktree:** (unset)
- **Last agent:** (unset)

## Agent routing
- **Role:** implementer
- **Owner:** agent:any

🤖 Generated with Claude Code
EOF
)"

Record each issue URL back into the task's notes (or objective.notes) so a resume on another machine can find it.

8. Report

Objective auth-system written to .dev-files/objectives/auth-system/
  5 tasks, 4 waves, 2 parallelizable
  validate_plan.py: PASS
  GitHub issues: #42 #43 #44 #45 #46   (or "not exported")

Next: /orchestrate-dev auth-system     — run the graph, integrate, one PR
      /start-dev task-001              — run a single task by hand (no PR: the objective owns delivery)

Hard rules

• Never write state before user approval. The review gate is mandatory.
• Never assume a task becomes a PR. One objective = one PR unless a named exception in core/policies/delivery.md applies.
• Never emit a task without depends_on, scope, validation_tier, and role. A task missing any of them cannot be scheduled or isolated.
• Never mark tasks parallel when their scopes overlap. Add a dependency or narrow the globs.
• Never write a scope with a lone *. It grants the whole subtree under the enforcing matcher; use <dir>/** or a literal path.
• Never put unrelated work in one task. Single coherent theme each.
• Never write code, commit, or push. This skill plans only.
• Always run validate_plan.py on the written objective before reporting success.
• Always keep GitHub export optional — but always honour an explicit "create issues" request.
• Diagrams in a plan are Mermaid per rules/dev/documentation-standards.md — the canonical init line from config/docs/mermaid-init.txt first, never box-drawing. A task whose scope includes README.md or docs/** inherits the footer requirement; name bash scripts/check-doc-standards.sh in its verification.

What NOT to do

Wrong — one issue per task, one PR per issue:

Phase 1 → issue #42 → PR #101
Phase 2 → issue #43 → PR #102
Phase 3 → issue #44 → PR #103

Three CI runs, three reviews, and nobody ever reviews the combined change. Right: one objective, five tasks, one PR.

Wrong — mega-task:

task-001: implement the entire authentication system (15 subtasks)

Split into 3–5 tasks with real dependencies.

Wrong — a scope that grants more than it appears to:

task-001  scope: src/*

Reads as "files directly under src"; actually authorises every file under src/, at any depth. Write src/** if that is what you mean, or name the files.

Wrong — parallel tasks over the same files:

task-001  scope: src/auth/**   depends_on: []
task-002  scope: src/auth/**   depends_on: []

Two workers, same files, guaranteed conflict. validate_plan.py rejects this.

Wrong — vague task:

- [ ] Fix the login bug

Name the files and the exact change.

Quick reference: decomposition cheat sheet

Supporting files

Load references/phase-grouping-guide.md when the input has 20+ items, spans a monorepo, or the dependency shape is non-obvious (diamonds, near-cycles).

Handoff

/orchestrate-dev <objective-id>   # run the graph → integrate → one PR
/start-dev <task or description>  # single task; no PR while the objective is active
/switch-dev handoff #N            # if issues were exported and you are switching tools