super-fr

Describe a feature, get back a reviewed pull request. Tell super-fr what you want, answer one short round of questions, and an agent designs it, writes it test-first, reviews its own work, and opens a single PR for you to merge — all inside an isolated workspace that never touches your checkout.

It's two Claude Code plugins (plus a small CLI) that wrap superpowers with phase-structured plans, mandatory git-worktree + devcontainer isolation, and an optional path to fan a plan's phases out to autonomous runners (VibeKanban today).

Built and dogfooded by derio-net; installable anywhere Claude Code runs.

Quickstart

1. Install

As a Claude Code plugin (recommended) — add to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "super-fr@derio-net": true,
    "super-fr-dispatch@derio-net": true
  }
}

For the full setup (skills + rules + the fr CLI + MCP config) in one line — no manual checkout; it manages a hidden source clone under ~/.cache/fr/src and re-running updates it:

curl -fsSL https://raw.githubusercontent.com/derio-net/super-fr/main/scripts/bootstrap.sh | bash

Prefer to read it first? curl … -o bootstrap.sh, inspect, then bash bootstrap.sh. Just want the CLI? uv tool install 'git+https://github.com/derio-net/super-fr#subdirectory=packages/fr'.

2. Run your first goal

In any repo (super-fr scaffolds a devcontainer profile the first time if one is missing):

/fr-goal add rate limiting to the webhook receiver

The agent isolates, brainstorms, asks its questions once, then drives spec → plan → test-driven implementation → review → a single PR for you to merge. That's the whole loop — everything below is detail you can reach for when you need it.

Skills

The two plugins ship ten skills. Most of the time you only type /fr-goal and the rest are invoked for you; this is the map of what each is and when it fires.

super-fr

Skill	What it does	How invoked	When
fr-goal	Brainstorm → spec → plan → TDD → reviewed PR, unattended	/fr-goal <description>	You want a feature built end-to-end without babysitting — the usual entry point
fr-brainstorming	superpowers brainstorming, inside isolation from the first command	/fr-brainstorming or auto (fr-goal step 1)	Designing a feature into a spec before building
fr-debugging	systematic-debugging in isolation → fix-PR	/fr-debugging or auto	A bug, failing test, or unexpected behavior to root-cause + fix
fr-plan	Phase-structured plan-as-folder + spec index	/fr-plan or auto (after a spec)	Turning an approved design into an executable plan
fr-execute	Implement one agentic phase (Phase > Task > Step), TDD	agent-facing; auto in fr-goal / dispatch	Carrying out assigned phase work (rarely called directly)
fr-isolation	Worktree + devcontainer lifecycle	/fr-isolation or auto	Running anything that must not touch your base checkout; post-merge cleanup
fr-init	Scan repo, interview, scaffold devcontainer profiles	/fr-init or auto (first isolated run)	First fr use in a repo with no devcontainer profile
fr-progress	Status board, drift audit, spec rollup	/fr-progress	"What's in progress?", auditing plan/spec drift

super-fr-dispatch

Skill	What it does	How invoked	When
fr-dispatch	Queue a merged plan's phases to a runner + reconcile Issues	/fr-dispatch (fr apply --to <runner>)	You merged a plan and want its phases run asynchronously
fr-runner	Operate/debug a runner: tick health, stuck phases, metrics	/fr-runner	A dispatched phase is stuck, or checking runner/bridge health

How it works

There are two ways work flows through super-fr. Both share the same artifacts — a spec (docs/superpowers/specs/) and a plan-as-folder (docs/superpowers/plans/<slug>/). Flow 1 is one continuous agent session working in isolation on your machine. Flow 2 queues merged plan phases to a runner that executes them asynchronously, one agent per phase.

Flow 1 — goal to PR, locally (/fr-goal)

The operator describes a feature, answers one batched round of questions, and gets back a single reviewed PR. Everything in between — brainstorming via superpowers, spec, plan, TDD implementation, code review — runs autonomously inside an isolated workspace.

flowchart TD
    Goal(["/fr-goal — feature description"]) --> Iso["fr isolation up<br/>git worktree + devcontainer"]
    Iso -. no devcontainer profile .-> Init["fr-init interview<br/>scaffold a profile"] -.-> Iso
    Iso --> BS["fr-brainstorming<br/>(wraps superpowers:brainstorming)"]
    BS --> QA["ONE batched Q&A<br/>(operator answers ≤4 questions)"]
    QA --> Spec["spec committed to<br/>docs/superpowers/specs/"]
    Spec --> Plan["fr-plan: phase-structured plan<br/>_meta.yaml + NN.yaml per phase"]
    Plan --> SR["fr plan self-review"]
    SR --> Exec["fr-execute (local mode)<br/>TDD per step; every command via<br/>fr isolation exec"]
    Exec --> Review["code review after each phase<br/>(superpowers:requesting-code-review)<br/>fix every finding"]
    Review --> PR["single PR<br/>(agent never self-merges)"]
    PR -. back-loaded manual phase .-> Manual["operator implements it<br/>(secrets, UI ops, deploys)<br/>and pushes to the same PR"] -.-> Merge
    PR --> Merge["operator reviews & merges"]
    Merge -. spec has a Test Plan .-> TP["post-merge Test Plan, driven together:<br/>agent runs the checks it can,<br/>operator confirms the rest"] -.-> Close
    Merge --> Close["fr archive + fr isolation down"]

Loading

Not quite everything is autonomous — two moments stay operator+agent driven around the merge. Manual work (secrets, UI ops, deploys) is back-loaded into the plan's last [manual] phase: the PR ships with it deliberately unimplemented, and the operator implements it and pushes to the same PR. (Front-loading is the rare exception, only when agentic work genuinely depends on the manual output: the run opens a spec+plan PR — the manual instructions are the deliverable — pauses, and resumes only on the operator's go.) And when the deliverable deploys, the spec carries a post-merge Test Plan (offered in the batched Q&A) that the agent drives interactively after the merge — it runs the checks it can reach, the operator confirms what it can't — before the run closes out with fr archive and fr isolation down.

Flow 2 — dispatch phases to a runner (fr apply --to vk)

Once a plan is merged, its phases can be queued to a runner instead of being executed locally. fr apply mirrors each phase to a GitHub Issue; a cron bridge daemon hands ready phases to VibeKanban, which spawns one agent workspace per phase. Each phase comes back as its own PR.

sequenceDiagram
    actor Op as Operator
    participant CLI as fr CLI
    participant GH as GitHub Issues
    participant Bridge as bridge daemon<br/>(fr_vk, cron tick)
    participant VK as VibeKanban
    participant Agent as runner agent

    Op->>CLI: fr apply <plan> --to vk (dry-run)
    CLI->>GH: observe issues / labels / PRs
    CLI-->>Op: mutation preview
    Op->>CLI: fr apply <plan> --to vk --yes
    Note over CLI,GH: reachability gate: plan + spec<br/>must be merged to origin/HEAD
    CLI->>GH: create phase Issues, set fr:ready + runner:vk labels
    CLI-->>Op: tracking_issue URLs written back to plan
    loop every tick
        Bridge->>GH: discover plans, observe ready phases
        Bridge->>VK: create card + start workspace
        Bridge->>GH: stamp fr:synced
    end
    Agent->>Agent: implement phase (TDD)
    Agent->>GH: open PR (one phase = one PR)
    Bridge->>VK: PR open → card "In review"
    Op->>GH: review & merge PR
    Bridge->>VK: PR merged → card "Done", archive workspace
    Bridge->>GH: close Issue

Loading

The flows compose: author a plan with Flow 1's front half (brainstorm → spec → plan → merge), then fan its phases out to a runner with Flow 2. Without --to, fr apply is tracking-only — Issues mirror the plan but no runner is involved.

Isolation: worktrees + devcontainers

Every run happens in an isolated workspace — there is no unisolated fallback. Isolation is two layers:

• Workspace isolation — a git worktree at ~/.cache/fr/worktrees/<repo>/<branch>, outside the base repo. The operator's checkout is never touched: no stray checkouts, stashes, or half-finished state.
• Environment isolation — a devcontainer per committed profile (.devcontainer/<profile>/devcontainer.json + .devcontainer/fr-profiles.yaml). Secrets stay host-side in ~/.config/fr/secrets/<repo>/<profile>.env and are injected per profile, so a run only sees the credentials its profile grants. The default profile is least-privileged (e.g. dev with no tokens); an admin profile can carry GH_TOKEN for in-container pushes.

The lifecycle is a plain shell CLI any agent or human drives identically:

fr isolation up --branch feat/rate-limit --profile dev   # worktree + container
fr isolation exec --branch feat/rate-limit -- uv run pytest -q
fr isolation status                                      # worktree, container, PR state
fr isolation down --branch feat/rate-limit               # after the PR merges

Exec-bridge discipline: file edits happen on the host (the worktree is host-visible); every build, test, lint, and run command goes through fr isolation exec -- … inside the container. down refuses while the linked PR is still open (unless --force), so cleanup can't race the operator's final pushes.

A repo without a profile is a blocker, not a degraded mode: the fr-init skill scans the repo, interviews the operator (profiles, tools, credential key names, working patterns), and scaffolds profiles via fr init scaffold. First run per repo pays this once.

Reference

fr CLI

Everyday:

Command	Purpose
fr apply	Render + observe + diff + apply a plan to GitHub (dry-run by default; --to <runner> queues phases)
fr status	Read-only plan report (allowlist-safe; never mutates)
fr isolation	Isolated workspaces: up, exec, status, down
fr plan	Plan editing: create, edit (tick steps, complete phases), self-review, rework
fr archive	Move finished plans (and specs) to implemented/
fr skills	Condensed overview of the skills + CLI surface

Maintenance:

Command	Purpose
fr init	Devcontainer profile scaffolding (scaffold)
fr repos	Instrument locally-checked-out repos with a plan-config.yaml (sync; never clones)
fr repair	Normalize stale plan/spec refs and strip dead plan-config.yaml keys (dry-run; --yes to write)
fr migrate	Plan format migration (v1→v2; also strips dead plan-config.yaml keys)
fr undispatch	Close a plan's tracking Issues and null the fields
fr pickup	Output phase scope (markdown) for an agent
fr spec	Spec status reporting

Plan model

• One plan = one repo's worth of work. Plans live in the repo they modify.
• One phase = one GitHub Issue = one PR. Phases are scoped for reviewability.
• Cross-repo features use multiple plans, coordinated through the shared spec's "Implementation Plans" section (maintained by fr-plan).

A plan is a folder, not a file:

docs/superpowers/plans/<YYYY-MM-DD-slug>/
├── _meta.yaml    # slug, spec ref, target repo, schema version
├── _prose.md     # human-readable narrative
├── 01.yaml       # phase 1: tasks + steps (P1.T1.S1 IDs), depends_on, tag
└── 02.yaml       # phase 2 …

Label lifecycle

Phases queued to a runner (fr apply --to <runner>) carry exactly one protocol-owned lifecycle label, projected from GitHub state on every tick:

fr:ready ──→ fr:in-progress ──→ fr:pr-ready ──→ (closed)
   │
   └─ fr:blocked   while depends_on phases are incomplete

Plus two markers: fr:synced (handed to the runner — the idempotency stamp that prevents re-dispatch) and manual (human-only phase, never routed to an agent). Tracking-only Issues (no --to) carry no lifecycle label.

Reachability gate: fr apply --yes refuses to dispatch unless the plan and spec are merged to origin/HEAD — the runner works from its own checkout of main, so anything not on main would be invisible to it.

Per-repo profile

Each repo can optionally define docs/superpowers/plan-config.yaml to set the plan filename pattern, required headers, and status values the plan validator enforces. It's read only by scripts/validate-plans.sh, which falls back to sane defaults when the file is absent — so a repo works without it.

To drop this file into a set of already-checked-out repos at once — without cloning anything — use fr repos sync:

fr repos sync derio-net/super-fr owner/other          # dry-run preview (default)
fr repos sync derio-net/super-fr owner/other --yes     # write plan-config.yaml in place

Repos resolve via $FR_REPOS_DIR / ~/repos/<name> (a missing checkout is a warning, not a failure) or a manifest at ~/.config/fr/repos.yaml; positional args are appended to that manifest unless --no-save. fr repair and fr migrate also normalize this file, stripping any legacy keys the toolchain no longer reads.

Components

Package	What it is
fr	The CLI: plan-as-folder engine, GitHub tracking (render → observe → diff → apply), isolation
fr-dispatch	Runner protocol + tick framework (library, runner-agnostic)
fr-vk	VibeKanban adapter: MCP client, card/workspace dispatch, bridge daemon

Requirements

• superpowers plugin (super-fr wraps its brainstorming, TDD, and review skills)
• GitHub CLI (gh) authenticated
• Docker (devcontainers for isolation)
• uv (for the fr CLI)
• VibeKanban MCP server — only for dispatch (npx vibe-kanban@latest --mcp)

For maintainers

Contributor workflow, the release/version-bump rule, the bridge-audit rule, and the CI gate are documented in CLAUDE.md.