feat: skill plan — spec to executable plan with no-placeholders rule
This commit is contained in:
@@ -0,0 +1,216 @@
|
||||
---
|
||||
name: plan
|
||||
description: Use when a milestone spec exists in docs/specs/ and a new iteration is starting. Produces a placeholder-free, bite-sized implementation plan in docs/plans/ that the implement skill can execute task-by-task. Hard-gate before any implementation work.
|
||||
---
|
||||
|
||||
# plan — spec → executable plan
|
||||
|
||||
> **Violating the letter of these rules is violating the spirit.**
|
||||
|
||||
## Overview
|
||||
|
||||
A plan is the contract between design (spec) and execution
|
||||
(`implement`). It commits the file structure, names every file
|
||||
that will be created or modified, and decomposes work into bites
|
||||
small enough that a subagent can execute one in 2-5 minutes
|
||||
without making judgement calls outside its remit.
|
||||
|
||||
This skill adapts `superpowers:writing-plans` to the AILang
|
||||
project conventions: plans live at `docs/plans/<iteration>.md`,
|
||||
header references the parent spec, commit-per-task pattern
|
||||
matches the existing JOURNAL style.
|
||||
|
||||
## When to Use / Skipping
|
||||
|
||||
Triggers:
|
||||
- A spec at `docs/specs/<milestone>.md` is approved.
|
||||
- A new iteration within an active milestone is starting.
|
||||
|
||||
May be skipped when:
|
||||
- The work is a bug fix where the RED test from `debug` IS the
|
||||
plan (handoff goes straight to `implement` mini-mode).
|
||||
- The work is a trivial mechanical edit (one file, ≤30 LOC, no
|
||||
design judgement).
|
||||
|
||||
**Never skipped** for a standard iteration within an active
|
||||
milestone. "I know the milestone, plan from memory" is exactly the
|
||||
failure mode this skill prevents.
|
||||
|
||||
## The Iron Law
|
||||
|
||||
```
|
||||
NO PLACEHOLDERS — TBD, TODO, "implement later", "similar to Task N",
|
||||
or "add appropriate error handling" are PLAN FAILURES.
|
||||
EVERY STEP THAT CHANGES CODE INCLUDES THE CODE.
|
||||
EVERY STEP THAT RUNS A COMMAND INCLUDES THE COMMAND AND EXPECTED OUTPUT.
|
||||
```
|
||||
|
||||
Lifted verbatim from `superpowers:writing-plans`. Non-negotiable.
|
||||
|
||||
## The Process
|
||||
|
||||
### Step 1 — Read the parent spec
|
||||
|
||||
Read `docs/specs/<milestone>.md` in full. NOT from memory. Even if
|
||||
the spec is recent and you wrote it yourself, re-read it before
|
||||
planning.
|
||||
|
||||
The spec is the source of truth; the plan is the projection of one
|
||||
iteration's worth of work onto a task list.
|
||||
|
||||
### Step 2 — Map file structure
|
||||
|
||||
Before defining tasks, list every file the iteration will create or
|
||||
modify, and what each one is responsible for. This is where
|
||||
decomposition decisions are locked in.
|
||||
|
||||
```markdown
|
||||
**Files this plan creates or modifies:**
|
||||
|
||||
- Create: `crates/ailang-codegen/src/<new>.rs` — <one-line
|
||||
responsibility>
|
||||
- Modify: `crates/ailang-check/src/typeclass.rs` — adds
|
||||
<responsibility>
|
||||
- Test: `crates/ail/tests/e2e.rs` — adds <case>
|
||||
```
|
||||
|
||||
Files that change together stay in the same task. Files that change
|
||||
independently get separate tasks.
|
||||
|
||||
### Step 3 — Write tasks, bite-sized
|
||||
|
||||
Each task is a logical unit of change (one feature, one fix, one
|
||||
extension). Each task contains steps; each step is ONE action that
|
||||
takes 2-5 minutes:
|
||||
|
||||
```markdown
|
||||
### Task N: <Component Name>
|
||||
|
||||
**Files:**
|
||||
- Create: `<exact path>`
|
||||
- Modify: `<exact path>:<line range if known>`
|
||||
- Test: `<exact path>`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```rust
|
||||
#[test]
|
||||
fn test_<specific_behaviour>() {
|
||||
let result = function(input);
|
||||
assert_eq!(result, expected);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cargo test --workspace -p <crate> test_<specific_behaviour>`
|
||||
Expected: FAIL with "<exact expected message>"
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```rust
|
||||
fn function(input: T) -> U {
|
||||
// exact code
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `cargo test --workspace -p <crate> test_<specific_behaviour>`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add <paths>
|
||||
git commit -m "iter <X>.<n>: <subject>"
|
||||
```
|
||||
```
|
||||
|
||||
### Step 4 — Plan header
|
||||
|
||||
Every plan starts with this header:
|
||||
|
||||
```markdown
|
||||
# <Iteration Title> — Implementation Plan
|
||||
|
||||
> **Parent spec:** `docs/specs/<milestone>.md`
|
||||
>
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
|
||||
> to run this plan. Steps use `- [ ]` checkboxes for tracking.
|
||||
|
||||
**Goal:** <one sentence>
|
||||
|
||||
**Architecture:** <2-3 sentences>
|
||||
|
||||
**Tech Stack:** <key crates/libs touched>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### Step 5 — Self-review
|
||||
|
||||
Before committing the plan, run this checklist inline:
|
||||
|
||||
1. **Spec coverage:** every spec section has a task that implements
|
||||
it. If a section has no task, add one.
|
||||
2. **Placeholder scan:** grep for "TBD", "TODO", "implement later",
|
||||
"similar to Task", "add appropriate error handling". Any hit is
|
||||
a plan failure to fix.
|
||||
3. **Type consistency:** function names, type names, file paths
|
||||
referenced across tasks must match. `clearLayers()` in Task 3
|
||||
and `clearFullLayers()` in Task 7 is a bug.
|
||||
4. **Step granularity:** every step is 2-5 minutes. If a step is
|
||||
"implement the parser", split it.
|
||||
|
||||
Fix issues inline. No need to re-review — fix and commit.
|
||||
|
||||
### Step 6 — Commit and hand off
|
||||
|
||||
```bash
|
||||
git add docs/plans/<iteration>.md
|
||||
git commit -m "plan: <iteration> <subject>"
|
||||
```
|
||||
|
||||
Hand off to `implement` with: path to the plan file + optional
|
||||
task focus ("only Tasks 1-3 this run").
|
||||
|
||||
## Handoff Contract
|
||||
|
||||
| Direction | Carrier |
|
||||
|-----------|---------|
|
||||
| `brainstorm` → `plan` | path to `docs/specs/<milestone>.md` + iteration scope ("this iteration covers spec section X+Y") |
|
||||
| `plan` → `implement` | path to `docs/plans/<iteration>.md` + optional task-range focus |
|
||||
| `plan` → `brainstorm` (bounce) | spec contains placeholders or contradictions: name the offending section, request revision |
|
||||
|
||||
## Common Rationalisations
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "TBD in step 4 lets me ship the plan tonight, fill in tomorrow" | Half-decided plans get re-litigated mid-iteration, costing more than the night's sleep saved. Make the decision tonight or close the laptop. |
|
||||
| "Bundle Tasks 3 and 4, both small, single commit" | The red-green-refactor cycle is the unit of verification. Bundled commits make bisection lie. If 3 and 4 are inseparable, they're one task — rewrite the decomposition. |
|
||||
| "Spec is recent, I wrote it, plan from memory" | Memory diverges from disk. 15 minutes of re-reading is the cheapest insurance in the cycle. |
|
||||
| "Step 5 'implement the parser' is fine, I'll detail it at execution time" | Then it's not a step, it's a wish. Steps are bite-sized OR the plan isn't done. |
|
||||
| "Task 7 is similar to Task 4, just say so" | The executor may read tasks out of order. Repeat the code. |
|
||||
| "The spec has a TBD too, I can pass it through" | Bounce back to `brainstorm`. Plans inherit spec gaps; spec gaps are not plan placeholders. |
|
||||
|
||||
## Red Flags — STOP
|
||||
|
||||
- Any of: "TBD", "TODO", "fill in later", "similar to", "add
|
||||
appropriate <X>" — fix or bounce.
|
||||
- Steps that describe what to do without showing how
|
||||
- Function/type/path names that don't match across tasks
|
||||
- Step descriptions longer than the code they describe
|
||||
- Header missing parent spec reference
|
||||
- Self-review skipped because "the plan looks fine"
|
||||
|
||||
## Cross-references
|
||||
|
||||
- **Upstream pattern:** `superpowers:writing-plans` — source of the
|
||||
bite-sized + No-Placeholders rule.
|
||||
- **Input source:** `skills/brainstorm/SKILL.md` — produces the
|
||||
spec this skill consumes.
|
||||
- **Output target:** `skills/implement/SKILL.md` — runs the plan
|
||||
task-by-task.
|
||||
- **No private agents.** This skill is dialogue-driven (orchestrator
|
||||
+ spec).
|
||||
Reference in New Issue
Block a user