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// containing:

• _meta.yaml — schemaversion, plan slug, spec ref, targetrepo, 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/.md). A spec that lives in another repo MUST use the cross-repo form /: (e.g. derio-net/frank:docs/superpowers/specs/.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.T.S (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 --target-repo \ --spec docs/superpowers/specs/.md \ --phases-file \ --prose-file ` fr plan create ALSO appends a row to the spec's ## Implementation Plans` table — there is no separate spec-index step.

1. Iterate on the prose / per-phase yaml via the Edit tool.
2. Run self-review: fr plan self-review .
3. Hand off for execution:

• fr apply — render → observe → diff → preview (default

dry-run). Add --yes to actually create / update GitHub Issues.

• The implementing agent uses fr pickup --phase N to receive

the phase scope as markdown.

Rules

• TDD (superpowers:test-driven-development): red → green → refactor. Test

first (red → green), then an optional refactor step per task when there's duplication / naming / extraction to clean — stay green, add no behavior; skip it when there's nothing to clean. No speculative generality.

• Refactor step shape (optional): after a task's red→green steps

(P.T.S1 test, S2 implement), the default is a trailing optional refactor step (P.T.S3) for small cleanups; use a separate REFACTOR + quality gate task for larger ones. Omit it entirely when there's nothing to clean — trivial tasks carry no empty refactor step.

• 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.
• 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 ` scaffolds a sibling

-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 --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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: derio-net
• Source: derio-net/super-fr
• License: MIT

Install and usage instructions live in the source repository linked above.