# Fr Plan

> Write phase-structured plans with operator collaboration. Use when: "write a plan", "fr plan", "create a plan". Invoked by brainstorming handoff.

- Skill: `derio-net/fr-plan` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add derio-net/fr-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/derio-net/fr-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: derio-net (https://skillmd.com/u/derio-net)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/derio-net/fr-plan

---


# fr-plan

Produce implementation plans through collaborative dialogue. Conversational
parts stay here; mechanical parts delegate to the `fr plan` CLI.

**Announce at start:** "I'm using fr-plan to create the implementation plan."

## Format (v2 plan-as-folder)

A plan is a directory under `docs/superpowers/plans/<slug>/` containing:

- `_meta.yaml` — schema_version, plan slug, spec ref, target_repo, vk_version,
  created date, optional rework metadata (`parent_plan`, `prior_rework`,
  `origin_items`).
  - **`spec` ref notation:** a same-repo spec is a plain repo-relative path
    (`docs/superpowers/specs/<file>.md`). A spec that lives in **another repo**
    MUST use the cross-repo form `<owner>/<repo>:<path-in-that-repo>` (e.g.
    `derio-net/frank:docs/superpowers/specs/<file>.md`). Without the
    `owner/repo:` prefix, `fr apply`'s reachability gate treats it as a missing
    same-repo file and refuses to dispatch. `fr plan self-review` warns when a
    same-repo-form spec doesn't resolve locally (#248).
- `_prose.md` — the human-readable narrative. Tooling never parses this; it's
  for humans (and the implementing agent).
- `NN.yaml` (one file per phase, two-digit zero-padded: `01.yaml`, `02.yaml`,
  …, `99.yaml`) — phase header, tasks, steps, and per-step state. Per-phase
  files prevent merge conflicts when parallel branches tick different phases.
  Phases are numbered **from 1**: `01.yaml` is the first phase; `00.yaml`
  (phase 0) fails parse — `fr plan create` rejects it pre-flight.

Every step id follows `P<n>.T<n>.S<n>` (phase number, task number, step
number). The renderer / observer / diff / apply chain depends on this shape.

## Procedure

1. Read context (recent commits, existing plans, spec file).
2. Confirm scope. Decompose if too large.
3. Propose 2-3 approaches with tradeoffs. Recommend one.
4. Present plan structure section by section, get approval.
5. Scaffold the plan folder:
   ```bash
   fr plan create --slug <YYYY-MM-DD-slug> --target-repo <owner/repo> \
       --spec docs/superpowers/specs/<spec-file>.md \
       --phases-file <phases.yaml> \
       --prose-file <prose.md>
   ```
   `fr plan create` ALSO appends a row to the spec's `## Implementation Plans`
   table — there is no separate spec-index step.
6. Iterate on the prose / per-phase yaml via the Edit tool.
7. Run self-review: `fr plan self-review <plan-dir>`.
8. Hand off for execution:
   - `fr apply <plan-dir>` — render → observe → diff → preview (default
     dry-run). Add `--yes` to actually create / update GitHub Issues.
   - The implementing agent uses `fr pickup <plan-dir> --phase N` to receive
     the phase scope as markdown.

## Rules

- TDD (`superpowers:test-driven-development`): red → green → refactor — or a recorded `no-refactor-because:`
  (task id) in the plan journal. No speculative generality; no silent skipping.
- **Refactor step shape:** trailing `P<n>.T<n>.S3` after red→green for small cleanups, a
  separate `REFACTOR + quality gate` **task** for larger ones. Omit only with justification;
  `fr plan self-review` enforces it (single-step tasks, manual phases, ticked tasks exempt).
- **Walking skeleton first:** the first agentic phase smokes delivery infrastructure (CI green
  on a trivial test, minimum runtime exercised, fixtures captured never constructed). Mark it
  `skeleton: true` — self-review errors without it (override: spec-scope `skeleton-override-*`).
- **Pure agentic phases:** an agentic phase must be fully agent-completable
  end-to-end. Collect ALL manual work (secrets, UI operations, deploy actions,
  cluster-dependent config) into a dedicated `[manual]` phase — never author a
  manual step into an agentic phase planning to defer it. `fr plan
  self-review` enforces this with error severity (#252).
- **Acceptance linkage:** a phase that advances a matrix row carries
  `acceptance: [row-ids]` in its header. `fr plan self-review` errors when the
  spec has a Test Plan but zero linked rows (matrix present) and on unknown
  ids. Planning may ADD rows (`fr acceptance add`, origin = spec) when decomposition exposes a missed
  business acceptance — flagged as an addition, defended at PR time, never ironed over.
- No placeholders: every step has actual code, commands, expected output.
- Bite-sized steps: 2-5 minutes each. Prefer 4–6 phases: every additional phase re-reads the
  accumulated handoff, so cost grows superlinearly with phase count (`fr run status` shows the
  per-phase accounting).
- Use BEGIN/END markers for full-file embeds, not nested fences.
- **Cross-repo completeness:** If the spec lists multiple plans across repos,
  write ALL of them before offering the execution handoff. For each target
  repo: scaffold the plan in that repo's `docs/superpowers/plans/` directory.
  `fr plan create` updates the spec table automatically.

## Dependency declarations

Each per-phase yaml declares its blockers via `phase.depends_on: [N, ...]`
(integers, comma-separated when multiple).

- Root phases: `depends_on: []`.
- Non-root phases: `depends_on: [1, 2]` for fan-in.
- Deps are backward-only: phase N may only reference phases < N.
- Cycles are caught by `fr plan self-review`.

## Rework plans

After a parent plan ships, defer surfaced-but-unrealised items into a separate
rework plan — do not reopen the parent.

- `fr plan rework <parent-plan-dir>` scaffolds a sibling
  `<parent-slug>-rework-N/` folder, adds `parent_plan` (and `prior_rework` if
  N>1) to its `_meta.yaml`, and appends a row to the spec table.
- `fr plan rework-add <rework-dir> --item ... --source ... --track ...`
  appends an entry to `_meta.origin_items`. `--track` is free-form (canonical
  tokens `development`, `operations`, `decision`; compounds like
  `decision → development` accepted).
- `fr plan rework-list [--include-archived]` surfaces open reworks.

## Integration

Upstream: brainstorming hands off via fr-plan-override. Downstream:
`fr apply` for GitHub-side work; `executing-plans` for the agent loop.