tuyv PM planning — decompose ARCH into tasks
The pm agent's job is to take the architect's ARCH document and produce 2 things:
- A
PLAN-<feature>.mdfor humans - A sequence of
bd createtasks for senior-dev to claim
The plan is good if a fresh senior-dev (no prior context) can pick up the bd tasks and ship without coming back for clarification.
The decomposition rules
Rule 1. Tasks ≤ 4 hours
Anything bigger gets split. If the task is "build the auth system", split into:
- Schema migration for user table
- Signup endpoint with hashing
- Login endpoint with JWT issuance
- Logout / token revocation
- Tests
Each ≤ 4h. If you can't split, the task is unclear — go back to ARCH and clarify.
Rule 2. Single output artefact per task
Each task produces ONE of:
- A code file (new or modified)
- A database migration
- A test file
- A documentation update
- A config change
If a task produces multiple unrelated artefacts, split it.
Rule 3. Explicit dependencies via --blocks
When task B requires task A's output:
bd create "Task A: schema migration" -p P1
# returns id: my-proj-001-abc
bd create "Task B: signup endpoint" -p P1 \
--blocks-on my-proj-001-abc \
--label senior-dev
The pipeline orchestrator reads bd ready --assignee senior-dev to know
what's claimable. Tasks blocked on incomplete predecessors don't appear.
Rule 4. Acceptance criteria — what does "done" mean?
Every task description ends with a bulleted "Done when:" section.
## Done when:
- [ ] POST /signup returns 201 with user_id on success
- [ ] Bad email returns 400 with "invalid_email"
- [ ] Duplicate email returns 409 with "email_taken"
- [ ] Password is hashed with argon2 (no plaintext in DB)
- [ ] Unit test in `tests/<area>/<feature>.test.ts` covers all 4 cases
- [ ] `npm test` passes
Senior-dev knows EXACTLY what to ship and when to stop.
Rule 5. Owners and parallelism
If 3 tasks can run in parallel, mark each with the agent it goes to. Don't bundle them.
bd create "..." --label senior-dev
bd create "..." --label senior-dev # parallel
bd create "..." --label devops # parallel, different agent
The PLAN-*.md template
# PLAN — <feature>
Date: <ISO>
Architect ARCH: docs/architecture/ARCH-<feature>.md
Owner: pm
## Summary
2-3 sentences. What problem, what solution. Reference ARCH for detail.
## Cost estimate
(Follow skill: cost-model)
## Tasks
1. **<title>** [P1, ≤2h, senior-dev]
- Goal: <one-sentence>
- Done when: <bulleted criteria>
- bd id: <ID after create>
2. **<title>** [P1, ≤4h, senior-dev]
- Blocked on: 1
- Goal: ...
- Done when: ...
3. **<title>** [P2, ≤1h, qa-engineer]
- Blocked on: 1, 2
## Pre-mortem
(Follow skill: pre-mortem)
## Gates
(Follow GATES_BY_ARCHETYPE for this archetype + project_size)
- [ ] gate:plan — after pm finishes, before senior-dev starts
- [ ] gate:qa — after qa-engineer, before ship
- [ ] gate:ship — after security-officer, before devops
When pm should push back instead of plan
The pm agent is allowed — and EXPECTED — to refuse a plan if the ARCH is incomplete. Specifically:
❌ ARCH is missing acceptance criteria for the feature itself. Push back: "ARCH says 'build webhook handler' but doesn't specify what counts as success. Re-architect with explicit success criteria."
❌ ARCH doesn't specify the failure mode. Push back: "ARCH says 'handle errors gracefully' but doesn't say what 'graceful' means. Define: log + ack? log + retry? log + alert?"
❌ ARCH conflicts with existing ADRs. Push back: "ARCH proposes Postgres but ADR-005 mandated DynamoDB. Resolve before plan."
Push-back goes to the architect with bd update + label re-arch. The
plan is BLOCKED until ARCH is refined.
Anti-patterns
❌ Tasks named after components, not goals. "Build UserService" is ambiguous. "Add POST /signup endpoint that hashes password with argon2" is clear.
❌ No dependencies declared. Two tasks editing the same file with
no --blocks-on will conflict. Always declare.
❌ Estimating without doing one task. If you genuinely don't know how long task 1 takes, ask senior-dev to do task 1 first and report back. THEN estimate 2–N.
❌ Tasks > 8 hours. Split. No exceptions.