https://github.com/derio-net/super-fr
Claude Code plugin suite: superpowers-wrapped planning, devcontainer+worktree isolation, goal-to-PR autonomy, and phase dispatch to VibeKanban runners
https://github.com/derio-net/super-fr
agent-skills ai-agents automation claude-code claude-code-plugin devcontainers git-worktree github-issues vibekanban
Last synced: 9 days ago
JSON representation
Claude Code plugin suite: superpowers-wrapped planning, devcontainer+worktree isolation, goal-to-PR autonomy, and phase dispatch to VibeKanban runners
- Host: GitHub
- URL: https://github.com/derio-net/super-fr
- Owner: derio-net
- License: mit
- Created: 2026-04-10T11:28:34.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T21:38:15.000Z (9 days ago)
- Last Synced: 2026-07-03T22:00:17.171Z (9 days ago)
- Topics: agent-skills, ai-agents, automation, claude-code, claude-code-plugin, devcontainers, git-worktree, github-issues, vibekanban
- Language: Python
- Size: 2.23 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# super-fr
[](https://github.com/derio-net/super-fr/releases)
[](https://github.com/derio-net/super-fr/actions/workflows/ci.yml)
[](LICENSE)
**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](https://github.com/obra/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](https://github.com/BloopAI/vibe-kanban) today).
Built and dogfooded by [derio-net](https://github.com/derio-net); installable
anywhere Claude Code runs.
## Quickstart
### 1. Install
As a Claude Code plugin (recommended) — add to `~/.claude/settings.json`:
```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:
```bash
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 ` | 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 `) | 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//`). **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.
```mermaid
flowchart TD
Goal(["/fr-goal — feature description"]) --> Iso["fr isolation up
git worktree + devcontainer"]
Iso -. no devcontainer profile .-> Init["fr-init interview
scaffold a profile"] -.-> Iso
Iso --> BS["fr-brainstorming
(wraps superpowers:brainstorming)"]
BS --> QA["ONE batched Q&A
(operator answers ≤4 questions)"]
QA --> Spec["spec committed to
docs/superpowers/specs/"]
Spec --> Plan["fr-plan: phase-structured plan
_meta.yaml + NN.yaml per phase"]
Plan --> SR["fr plan self-review"]
SR --> Exec["fr-execute (local mode)
TDD per step; every command via
fr isolation exec"]
Exec --> Review["code review after each phase
(superpowers:requesting-code-review)
fix every finding"]
Review --> PR["single PR
(agent never self-merges)"]
PR -. back-loaded manual phase .-> Manual["operator implements it
(secrets, UI ops, deploys)
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:
agent runs the checks it can,
operator confirms the rest"] -.-> Close
Merge --> Close["fr archive + fr isolation down"]
```
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.
```mermaid
sequenceDiagram
actor Op as Operator
participant CLI as fr CLI
participant GH as GitHub Issues
participant Bridge as bridge daemon
(fr_vk, cron tick)
participant VK as VibeKanban
participant Agent as runner agent
Op->>CLI: fr apply --to vk (dry-run)
CLI->>GH: observe issues / labels / PRs
CLI-->>Op: mutation preview
Op->>CLI: fr apply --to vk --yes
Note over CLI,GH: reachability gate: plan + spec
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
```
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//`, 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//devcontainer.json` + `.devcontainer/fr-profiles.yaml`).
Secrets stay host-side in `~/.config/fr/secrets//.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:
```bash
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 ` 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//
├── _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 `) 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`:
```bash
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/` (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](https://github.com/obra/superpowers) plugin (super-fr wraps its
brainstorming, TDD, and review skills)
- GitHub CLI (`gh`) authenticated
- Docker (devcontainers for isolation)
- [uv](https://docs.astral.sh/uv/) (for the `fr` CLI)
- [VibeKanban](https://github.com/BloopAI/vibe-kanban) 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`](CLAUDE.md).