plan-dev

Files (6)

• SKILL.md
• evals.json · evals/
• review-doc.md · evals/files/
• trigger-evals.json · evals/
• phase-grouping-guide.md · references/
• validate_plan.py · scripts/

SKILL.md (first lines)

# 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:**
```bash
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:

| Field | Options |
|---|---|
| **Type** | `feat`, `fix`, `chore`, `docs`, `test`, `refactor` |
| **Area** | `backend`, `frontend`, `infra`, `tests`, `docs`, `ci` |
| **Complexity** | `simple` (1 commit), `moderate` (few files), `complex` (cross-cutting) |
| **Risk** | `low` (additive), `medium` (modifies existing logic), `high` (deletes/restructures) |

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

| Field | Meaning | Rule |
|---|---|---|
| `id` | `task-001`, `task-002`, … | Sequential, zero-padded |
| `title` | Imperative, one line | |
| `role` | Which role does it | One of `core/roles/*.md`: planner, orchestrator, implementer, test-engineer, reviewer, security-reviewer, performance-reviewer, debugger, integrator, research-agent |
| `depends_on` | Task ids that must complete first | Empty array = ready now |
| `scope` | Glob paths this task may **write** | Everything else is read-only for it. **Always `<dir>/**`, never a lone `*`** — see below |
| `validation_tier` | `edit` \| `worker` \| `integration` \| `delivery` | Implementation tasks are `worker`; the integration task is `integration` |
| `status` | `ready` when `depends_on` is empty, else `pending` | |
| `provider` | Optional, advisory | Metadata only — never encoded in a branch or path |

**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:

| Write | Not |
|---|---|
| `src/auth/**` — the auth subtree | `src/auth/*` (reads as one level, grants the subtree) |
| `docs/reference.md` — one literal file | `docs/*.md` (grants everything under `docs/`) |

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:

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers