Skip to content

BumpyClock/agent-templates / skills_archive/writing-plans

writing-plans

Unverified

Use when you have a spec or requirements for a multi-step task, before touching code

Writing Plans

Create implementation plans from approved specs/requirements before code. Plans must let skilled engineers/agents with near-zero repo context build safely.

Local rules

  • Follow stricter repo/user git policy.
  • In dotfiles, no commits unless user explicitly asks.
  • Use subagent-driven-development by default for approved controller-owned plans.
  • SDD handoffs: run reviewer loops at aggregation boundaries, not per peer leaf task. Task with children → implement safe ready children first, integrate under parent/subtree, run one combined read-only reviewer for that subtree covering spec compliance + code quality. Recursive for nested trees, bottom-up. Dispatch leaf-level reviewers only when caller explicitly asks, risk requires isolation, or stricter repo policy requires it.
  • Inline execution allowed for: tiny micro-flow fixes, urgent critical-path blockers, verification-only work, unavailable/forbidden subagents, explicit user request.
  • Isolated worktree → follow local git workflow instructions.
  • Referenced Superpowers skills unavailable → map locally: implementation/debugging → programming, frontend/web → web-development, git/GitHub → git-workflow.

Scope check

Spec covers independent subsystems → suggest separate plans. Each plan produces working, testable software on its own. No decomposition buried inside mega-plans.

Tasque source of truth

tsq is source of truth for SDD-backed or durable planning.

Controller-owned planned implementation:

  1. Create or reuse tsq parent task.
  2. Attach approved spec/requirements to parent.
  3. Decompose into small atomic child tasks.
  4. Encode readiness dependencies with tsq block.
  5. Encode preferred sequencing with tsq order.
  6. Attach final implementation plan to parent.
  7. Mark parent planned.

Tiny micro-flow fixes, urgent blockers, one-off verification, child-planner drafts don't need new tsq tasks unless caller asks or passes parent ID.

Never claim path, task ID, dependency, or tsq state not actually created.

Repo artifacts

tsq is canonical for implementation workflow state.

Repo plan/spec files are optional exports. Write only when:

  • user asks for saved doc,
  • repo convention requires one,
  • tsq unavailable.

Product/API/user docs still required when behavior changes.

File structure first

Before tasks, map files to create/modify + each file's responsibility.

Rules:

  • Clear boundaries, clear interfaces.
  • One file = one main responsibility where practical.
  • Files that change together live together.
  • Split by responsibility, not technical layer by default.
  • Follow existing repo patterns.
  • Touched file unwieldy → plan focused split only when it serves current goal.
  • No unrelated refactors.

File map drives task decomposition.

Atomic task decomposition

Decompose into small, atomic child tasks.

Each child task must have:

  • one owned scope,
  • clear files/modules,
  • acceptance criteria,
  • focused verification command,
  • smoke/live verification when user-visible behavior changes,
  • dependencies in tsq, not hidden in prose.

Prefer more small tasks over fewer large. Large one-shot tasks fail more often, reduce safe parallelism.

Parallelize ready tasks by default only when:

  • tsq block dependencies clear,
  • owned write sets disjoint,
  • shared contracts stable,
  • generated artifacts/config/migrations/global styles/snapshots cannot collide.

Use tsq block for readiness/safety dependencies. tsq order only for preferred sequencing.

Task granularity

Each step ≈ 2-5 minutes, one small action.

Prefer TDD loop when possible:

  • write failing test
  • run, confirm failure
  • implement minimum code
  • run, confirm pass
  • smoke/live verification when user-visible behavior changes
  • commit only if requested

Plan document header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For agentic workers:** Execute approved controller-owned plans with `subagent-driven-development` by default. Task implementers own atomic leaf tasks; reviewer loops run at parent/subtree aggregation boundaries, not per peer leaf task, with one combined read-only reviewer checking spec compliance and code quality for the integrated subtree. Integration owner owns final root integration. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task structure

Use exact file paths, verified code shapes, exact commands, expected output. Include complete code only when verified from repo context or provided by caller. Otherwise exact patch-level instructions with named symbols, target behavior, assertions, investigation steps.

### Task N: [Component Name]

**Tasque:** `<parent-id>` / `<child-id>` for SDD-backed or durable plans. For inline/non-durable plans, omit or write `Tasque: not used — <reason>`. Never fabricate IDs.

**Owned scope:**

- May edit: `exact/path/or/module`
- Must not edit: `exact/path/or/module`

**Files:**

- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Dependencies:**

- Blocks: `<none | child-id>`
- Blocked by: `<none | child-id>`
- Ordered after: `<none | child-id>`

**Acceptance criteria:**

- [Specific observable outcome]
- [Specific regression that must stay fixed]

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

- [ ] **Step 4: Run focused verification**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Run smoke/live verification when user-visible**

Run: `exact command or manual check`
Expected: PASS / observed expected behavior

- [ ] **Step 6: Commit if requested**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

Adjust steps to fit repo, keep each step one action.

No placeholders

Plan failures. Never write:

  • TBD, TODO, implement later, fill in details
  • Add appropriate error handling
  • Add validation
  • Handle edge cases
  • Write tests for the above without actual test intent and code shape
  • Similar to Task N — repeat code; tasks may be read out of order
  • Steps describing code changes without code or exact patch-level direction
  • References to undefined types, functions, methods, props, commands, files
  • Fabricated code blocks, commands, APIs, paths, or tsq IDs

Required detail

Every plan needs:

  • Exact file paths.
  • Owned files/modules per child task.
  • Complete code only when verified from repo context; otherwise exact patch-level direction.
  • Exact commands with expected output.
  • Tests/verification for each behavior, with enough test-design detail for someone weak at test design.
  • Smoke/live verification for user-visible behavior.
  • Docs/changelog steps when behavior/API/user flow changes.
  • DRY, YAGNI, TDD where useful.
  • Commits only when requested by user.

Independent review

After writing plan, review against spec. Mandatory.

  1. Spec coverage — every requirement maps to task(s). Add missing tasks.
  2. Placeholder scan — remove failures listed above.
  3. Type/signature consistency — names used later match definitions earlier.
  4. Buildability — implementer can follow without repo lore or guessing.
  5. Test coverage — every task has tests verifying its behavior.
  6. Task decomposition — tasks small, focused, independently reviewable.
  7. Atomicity — tasks small enough for one subagent to own safely.
  8. Owned scope — every atomic child has clear may-edit and must-not-edit boundaries.
  9. Dependencies — readiness blockers use tsq block; preference order uses tsq order.
  10. Parallel safety — ready tasks have disjoint owned scopes and stable shared contracts.
  11. Verification — focused checks and smoke/live checks present where needed.
  12. Scope control — plan does not add unrequested behavior.

Fix issues inline. No need to re-review from scratch.

Plan review gate

After writing plan into tsq, dispatch plan-reviewer for controller-owned planned implementation.

Pass:

  • tsq parent task ID
  • plan text/spec attached to parent
  • child task list
  • dependency graph
  • constraints or ignored areas, if any

Iterate only on blocking issues. Re-run until Status: Approved.

Blocker needs product/API/scope decision, tsq state invalid, or reviewer cannot run → stop, ask caller/controller. Do not start implementation until approved or explicitly waived by controller.

Plan-reviewer must verify:

  • task decomposition atomic enough,
  • dependencies explicit in tsq,
  • ready tasks parallelizable safely,
  • owned scopes clear,
  • review loops at parent/subtree aggregation boundaries instead of per peer leaf task, one combined reviewer pass covering both spec compliance + code quality per integrated subtree unless caller explicitly requested leaf-level or two-stage review,
  • verification includes smoke/live checks where needed.

Inside planner subagent → do not dispatch review. Return plan, tell caller/controller to run plan-reviewer.

Execution handoff

After plan-reviewer approves controller-owned planned implementation, invoke subagent-driven-development by default.

Inline execution allowed for:

  • tiny micro-flow fixes,
  • urgent critical-path blockers,
  • verification-only work,
  • unavailable/forbidden subagents,
  • explicit user request.

No execution-choice prompt when SDD clearly applies. Start SDD with reviewer loops at aggregation boundaries. For each parent/subtree: dispatch safe ready leaf implementers, integrate outputs, run one combined reviewer over integrated subtree. Combined reviewer prompt: spec compliance first, then code quality, return one PASS/FAIL with evidence. Report:

Plan-reviewer approved `tsq` parent `<id>`. Starting SDD: dispatching safe ready leaf tasks concurrently where write sets disjoint and shared contracts stable, then reviewing integrated parent/subtree boundaries with one combined reviewer per aggregation point.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall