skills: add writing-implementation-plans, receiving-code-review, finishing-development-branches
Evaluated obra/superpowers and JuliusBrussee/caveman for gaps in the existing library. These three fill real ones (plan-to-delegate handoff, evidence-based review triage, completion vs. integration authority); adapted for this fleet's Gitea/RLS/multi-delegate conventions. Everything else in both repos duplicated existing skills or didn't fit (see README Provenance note on caveman). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: writing-implementation-plans
|
||||
description: Use when requirements are settled and a multi-step change needs an implementation plan that memoryless delegates can execute without access to the originating conversation.
|
||||
license: MIT
|
||||
source: https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md
|
||||
---
|
||||
|
||||
# Writing Implementation Plans
|
||||
|
||||
A plan is an executable handoff, not a summary of intent. The worker may be a
|
||||
fresh CLI delegate with no conversation history, and individual tasks may be
|
||||
assigned out of order. If the plan leaves a choice implicit, the worker will
|
||||
have to invent it.
|
||||
|
||||
## Before writing tasks
|
||||
|
||||
1. Read the settled spec or requirements and inspect the actual code paths,
|
||||
tests, project instructions, and established patterns involved.
|
||||
2. Resolve contradictions and material unknowns before planning. Marking them
|
||||
`TBD` only moves the design decision to a less-informed delegate.
|
||||
3. Map every file to create or modify and give each one a clear
|
||||
responsibility. Avoid unrelated restructuring.
|
||||
4. Split work into independently testable vertical slices. Fold setup,
|
||||
migrations, wiring, and documentation into the slice that needs them;
|
||||
don't create standalone tasks that leave the system unusable.
|
||||
5. Identify shared files and state. Tasks that edit the same bootstrap file,
|
||||
schema, migration sequence, or live environment are sequential unless the
|
||||
design removes that collision. See `parallel-delegate-shared-files`.
|
||||
|
||||
## Plan header
|
||||
|
||||
Start with:
|
||||
|
||||
```markdown
|
||||
# <Feature> Implementation Plan
|
||||
|
||||
**Goal:** <one sentence>
|
||||
|
||||
**Architecture:** <two or three sentences describing the approach and boundaries>
|
||||
|
||||
**Stack and environment:** <relevant runtimes, services, jail/container, database>
|
||||
|
||||
## Global constraints
|
||||
|
||||
- <exact version, naming, compatibility, security, tenant-isolation, and scope rules>
|
||||
|
||||
## Verification
|
||||
|
||||
- <commands for targeted tests, full regression tests, and any real end-to-end check>
|
||||
```
|
||||
|
||||
Copy exact values from the requirements. For multi-tenant work, state the
|
||||
tenant/RLS invariants explicitly; never let a worker infer them from nearby
|
||||
code. For remote or production-adjacent work, state the exact host/jail,
|
||||
whether mutation is authorised, and how secrets must be read without being
|
||||
printed.
|
||||
|
||||
## Task contract
|
||||
|
||||
Each task must stand alone:
|
||||
|
||||
```markdown
|
||||
### Task N: <independently testable outcome>
|
||||
|
||||
**Depends on:** <prior task outputs, or "none">
|
||||
|
||||
**Files:**
|
||||
- Create: `exact/path`
|
||||
- Modify: `exact/path` — <symbol or section>
|
||||
- Test: `exact/path`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: <exact names, signatures, schemas, or artifacts>
|
||||
- Produces: <exact names, signatures, schemas, or artifacts>
|
||||
|
||||
**Requirements:**
|
||||
- <observable behavior and edge cases>
|
||||
|
||||
**Steps:**
|
||||
- [ ] Write the failing test for <behavior>.
|
||||
- [ ] Run `<targeted command>`; expect <specific failure proving the test is red-capable>.
|
||||
- [ ] Implement the smallest change that passes it.
|
||||
- [ ] Run `<targeted command>`; expect <specific success>.
|
||||
- [ ] Run `<broader command>`; expect no regressions.
|
||||
- [ ] Commit only this task's files with `<message or project convention>`.
|
||||
|
||||
**Report:** <facts and evidence the delegate must return>
|
||||
```
|
||||
|
||||
Write exact commands and concrete expected signals. Include code or
|
||||
pseudocode only where it removes a real ambiguity; don't turn the plan into a
|
||||
second implementation. When a task brief will be extracted from the plan,
|
||||
repeat its binding constraints instead of saying “same as above.”
|
||||
|
||||
## Self-review before delegation
|
||||
|
||||
- Trace every requirement to a task and every task to the goal. Remove gaps
|
||||
and scope creep.
|
||||
- Search for placeholders and vague steps: `TBD`, `TODO`, “handle errors,”
|
||||
“add validation,” “write tests,” “similar to Task N.” Replace each with an
|
||||
explicit decision or action.
|
||||
- Check that interface names and types match across tasks.
|
||||
- Check ordering: a task must not consume an artifact that does not exist yet.
|
||||
- Check concurrency: no parallel tasks may edit the same file or mutate the
|
||||
same shared environment.
|
||||
- Check verification: every claimed outcome has a command or observation that
|
||||
could prove it false.
|
||||
- Have the user approve material architectural or scope decisions before
|
||||
implementation begins.
|
||||
|
||||
When dispatching tasks, still apply `delegate-brief-writing`: the extracted
|
||||
task plus relevant global constraints, confirmed facts, credentials handling,
|
||||
verification, and report contract form the self-contained brief.
|
||||
Reference in New Issue
Block a user