{"id":50632928,"url":"https://github.com/derio-net/super-fr","last_synced_at":"2026-07-03T22:00:35.728Z","repository":{"id":358308162,"uuid":"1206909271","full_name":"derio-net/super-fr","owner":"derio-net","description":"Claude Code plugin suite: superpowers-wrapped planning, devcontainer+worktree isolation, goal-to-PR autonomy, and phase dispatch to VibeKanban runners","archived":false,"fork":false,"pushed_at":"2026-07-03T21:38:15.000Z","size":2343,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T22:00:17.171Z","etag":null,"topics":["agent-skills","ai-agents","automation","claude-code","claude-code-plugin","devcontainers","git-worktree","github-issues","vibekanban"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/derio-net.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T11:28:34.000Z","updated_at":"2026-07-03T21:33:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/derio-net/super-fr","commit_stats":null,"previous_names":["derio-net/superpowers-for-vk","derio-net/super-fr"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/derio-net/super-fr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derio-net%2Fsuper-fr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derio-net%2Fsuper-fr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derio-net%2Fsuper-fr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derio-net%2Fsuper-fr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/derio-net","download_url":"https://codeload.github.com/derio-net/super-fr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derio-net%2Fsuper-fr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35102741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","automation","claude-code","claude-code-plugin","devcontainers","git-worktree","github-issues","vibekanban"],"created_at":"2026-06-07T00:00:38.976Z","updated_at":"2026-07-03T22:00:35.714Z","avatar_url":"https://github.com/derio-net.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# super-fr\n\n[![GitHub Release](https://badgen.net/github/release/derio-net/super-fr/stable)](https://github.com/derio-net/super-fr/releases)\n[![CI](https://github.com/derio-net/super-fr/actions/workflows/ci.yml/badge.svg)](https://github.com/derio-net/super-fr/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**Describe a feature, get back a reviewed pull request.** Tell super-fr what you\nwant, answer one short round of questions, and an agent designs it, writes it\ntest-first, reviews its own work, and opens a single PR for you to merge — all\ninside an isolated workspace that never touches your checkout.\n\nIt's two Claude Code plugins (plus a small CLI) that wrap\n[superpowers](https://github.com/obra/superpowers) with phase-structured plans,\nmandatory git-worktree + devcontainer isolation, and an optional path to fan a\nplan's phases out to autonomous runners\n([VibeKanban](https://github.com/BloopAI/vibe-kanban) today).\n\nBuilt and dogfooded by [derio-net](https://github.com/derio-net); installable\nanywhere Claude Code runs.\n\n## Quickstart\n\n### 1. Install\n\nAs a Claude Code plugin (recommended) — add to `~/.claude/settings.json`:\n\n```json\n{\n  \"enabledPlugins\": {\n    \"super-fr@derio-net\": true,\n    \"super-fr-dispatch@derio-net\": true\n  }\n}\n```\n\nFor the full setup (skills + rules + the `fr` CLI + MCP config) in one line — no\nmanual checkout; it manages a hidden source clone under `~/.cache/fr/src` and\nre-running updates it:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/derio-net/super-fr/main/scripts/bootstrap.sh | bash\n```\n\nPrefer to read it first? `curl … -o bootstrap.sh`, inspect, then `bash\nbootstrap.sh`. Just want the CLI? `uv tool install\n'git+https://github.com/derio-net/super-fr#subdirectory=packages/fr'`.\n\n### 2. Run your first goal\n\nIn any repo (super-fr scaffolds a devcontainer profile the first time if one is\nmissing):\n\n```\n/fr-goal add rate limiting to the webhook receiver\n```\n\nThe agent isolates, brainstorms, asks its questions once, then drives\nspec → plan → test-driven implementation → review → a single PR for you to\nmerge. That's the whole loop — everything below is detail you can reach for\nwhen you need it.\n\n## Skills\n\nThe two plugins ship ten skills. Most of the time you only type `/fr-goal` and\nthe rest are invoked for you; this is the map of what each is and when it fires.\n\n### super-fr\n\n| Skill | What it does | How invoked | When |\n|-------|--------------|-------------|------|\n| `fr-goal` | Brainstorm → spec → plan → TDD → reviewed PR, unattended | `/fr-goal \u003cdescription\u003e` | You want a feature built end-to-end without babysitting — the usual entry point |\n| `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 |\n| `fr-debugging` | systematic-debugging in isolation → fix-PR | `/fr-debugging` or auto | A bug, failing test, or unexpected behavior to root-cause + fix |\n| `fr-plan` | Phase-structured plan-as-folder + spec index | `/fr-plan` or auto (after a spec) | Turning an approved design into an executable plan |\n| `fr-execute` | Implement one agentic phase (Phase \u003e Task \u003e Step), TDD | agent-facing; auto in fr-goal / dispatch | Carrying out assigned phase work (rarely called directly) |\n| `fr-isolation` | Worktree + devcontainer lifecycle | `/fr-isolation` or auto | Running anything that must not touch your base checkout; post-merge cleanup |\n| `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 |\n| `fr-progress` | Status board, drift audit, spec rollup | `/fr-progress` | \"What's in progress?\", auditing plan/spec drift |\n\n### super-fr-dispatch\n\n| Skill | What it does | How invoked | When |\n|-------|--------------|-------------|------|\n| `fr-dispatch` | Queue a merged plan's phases to a runner + reconcile Issues | `/fr-dispatch` (`fr apply --to \u003crunner\u003e`) | You merged a plan and want its phases run asynchronously |\n| `fr-runner` | Operate/debug a runner: tick health, stuck phases, metrics | `/fr-runner` | A dispatched phase is stuck, or checking runner/bridge health |\n\n## How it works\n\nThere are two ways work flows through super-fr. Both share the same artifacts —\na spec (`docs/superpowers/specs/`) and a plan-as-folder\n(`docs/superpowers/plans/\u003cslug\u003e/`). **Flow 1** is one continuous agent session\nworking in isolation on your machine. **Flow 2** queues merged plan phases to a\nrunner that executes them asynchronously, one agent per phase.\n\n### Flow 1 — goal to PR, locally (`/fr-goal`)\n\nThe operator describes a feature, answers one batched round of questions, and\ngets back a single reviewed PR. Everything in between — brainstorming via\nsuperpowers, spec, plan, TDD implementation, code review — runs autonomously\ninside an isolated workspace.\n\n```mermaid\nflowchart TD\n    Goal([\"/fr-goal — feature description\"]) --\u003e Iso[\"fr isolation up\u003cbr/\u003egit worktree + devcontainer\"]\n    Iso -. no devcontainer profile .-\u003e Init[\"fr-init interview\u003cbr/\u003escaffold a profile\"] -.-\u003e Iso\n    Iso --\u003e BS[\"fr-brainstorming\u003cbr/\u003e(wraps superpowers:brainstorming)\"]\n    BS --\u003e QA[\"ONE batched Q\u0026A\u003cbr/\u003e(operator answers ≤4 questions)\"]\n    QA --\u003e Spec[\"spec committed to\u003cbr/\u003edocs/superpowers/specs/\"]\n    Spec --\u003e Plan[\"fr-plan: phase-structured plan\u003cbr/\u003e_meta.yaml + NN.yaml per phase\"]\n    Plan --\u003e SR[\"fr plan self-review\"]\n    SR --\u003e Exec[\"fr-execute (local mode)\u003cbr/\u003eTDD per step; every command via\u003cbr/\u003efr isolation exec\"]\n    Exec --\u003e Review[\"code review after each phase\u003cbr/\u003e(superpowers:requesting-code-review)\u003cbr/\u003efix every finding\"]\n    Review --\u003e PR[\"single PR\u003cbr/\u003e(agent never self-merges)\"]\n    PR -. back-loaded manual phase .-\u003e Manual[\"operator implements it\u003cbr/\u003e(secrets, UI ops, deploys)\u003cbr/\u003eand pushes to the same PR\"] -.-\u003e Merge\n    PR --\u003e Merge[\"operator reviews \u0026 merges\"]\n    Merge -. spec has a Test Plan .-\u003e TP[\"post-merge Test Plan, driven together:\u003cbr/\u003eagent runs the checks it can,\u003cbr/\u003eoperator confirms the rest\"] -.-\u003e Close\n    Merge --\u003e Close[\"fr archive + fr isolation down\"]\n```\n\nNot quite everything is autonomous — two moments stay operator+agent driven\naround the merge. Manual work (secrets, UI ops, deploys) is back-loaded into\nthe plan's last `[manual]` phase: the PR ships with it deliberately\nunimplemented, and the operator implements it and pushes to the same PR.\n(Front-loading is the rare exception, only when agentic work genuinely depends\non the manual output: the run opens a spec+plan PR — the manual instructions\nare the deliverable — pauses, and resumes only on the operator's go.) And\nwhen the deliverable deploys, the spec carries a post-merge **Test Plan**\n(offered in the batched Q\u0026A) that the agent drives interactively after the\nmerge — it runs the checks it can reach, the operator confirms what it can't —\nbefore the run closes out with `fr archive` and `fr isolation down`.\n\n### Flow 2 — dispatch phases to a runner (`fr apply --to vk`)\n\nOnce a plan is merged, its phases can be queued to a runner instead of being\nexecuted locally. `fr apply` mirrors each phase to a GitHub Issue; a cron\nbridge daemon hands ready phases to VibeKanban, which spawns one agent\nworkspace per phase. Each phase comes back as its own PR.\n\n```mermaid\nsequenceDiagram\n    actor Op as Operator\n    participant CLI as fr CLI\n    participant GH as GitHub Issues\n    participant Bridge as bridge daemon\u003cbr/\u003e(fr_vk, cron tick)\n    participant VK as VibeKanban\n    participant Agent as runner agent\n\n    Op-\u003e\u003eCLI: fr apply \u003cplan\u003e --to vk (dry-run)\n    CLI-\u003e\u003eGH: observe issues / labels / PRs\n    CLI--\u003e\u003eOp: mutation preview\n    Op-\u003e\u003eCLI: fr apply \u003cplan\u003e --to vk --yes\n    Note over CLI,GH: reachability gate: plan + spec\u003cbr/\u003emust be merged to origin/HEAD\n    CLI-\u003e\u003eGH: create phase Issues, set fr:ready + runner:vk labels\n    CLI--\u003e\u003eOp: tracking_issue URLs written back to plan\n    loop every tick\n        Bridge-\u003e\u003eGH: discover plans, observe ready phases\n        Bridge-\u003e\u003eVK: create card + start workspace\n        Bridge-\u003e\u003eGH: stamp fr:synced\n    end\n    Agent-\u003e\u003eAgent: implement phase (TDD)\n    Agent-\u003e\u003eGH: open PR (one phase = one PR)\n    Bridge-\u003e\u003eVK: PR open → card \"In review\"\n    Op-\u003e\u003eGH: review \u0026 merge PR\n    Bridge-\u003e\u003eVK: PR merged → card \"Done\", archive workspace\n    Bridge-\u003e\u003eGH: close Issue\n```\n\nThe flows compose: author a plan with Flow 1's front half (brainstorm → spec →\nplan → merge), then fan its phases out to a runner with Flow 2. Without\n`--to`, `fr apply` is tracking-only — Issues mirror the plan but no runner is\ninvolved.\n\n## Isolation: worktrees + devcontainers\n\nEvery run happens in an isolated workspace — there is **no unisolated\nfallback**. Isolation is two layers:\n\n- **Workspace isolation** — a git worktree at\n  `~/.cache/fr/worktrees/\u003crepo\u003e/\u003cbranch\u003e`, outside the base repo. The\n  operator's checkout is never touched: no stray checkouts, stashes, or\n  half-finished state.\n- **Environment isolation** — a devcontainer per committed profile\n  (`.devcontainer/\u003cprofile\u003e/devcontainer.json` + `.devcontainer/fr-profiles.yaml`).\n  Secrets stay host-side in `~/.config/fr/secrets/\u003crepo\u003e/\u003cprofile\u003e.env` and are\n  injected per profile, so a run only sees the credentials its profile grants.\n  The default profile is least-privileged (e.g. `dev` with no tokens); an\n  `admin` profile can carry `GH_TOKEN` for in-container pushes.\n\nThe lifecycle is a plain shell CLI any agent or human drives identically:\n\n```bash\nfr isolation up --branch feat/rate-limit --profile dev   # worktree + container\nfr isolation exec --branch feat/rate-limit -- uv run pytest -q\nfr isolation status                                      # worktree, container, PR state\nfr isolation down --branch feat/rate-limit               # after the PR merges\n```\n\n**Exec-bridge discipline:** file edits happen on the host (the worktree is\nhost-visible); every build, test, lint, and run command goes through\n`fr isolation exec -- …` inside the container. `down` refuses while the\nlinked PR is still open (unless `--force`), so cleanup can't race the\noperator's final pushes.\n\nA repo without a profile is a blocker, not a degraded mode: the `fr-init`\nskill scans the repo, interviews the operator (profiles, tools, credential\nkey names, working patterns), and scaffolds profiles via `fr init scaffold`.\nFirst run per repo pays this once.\n\n## Reference\n\n### `fr` CLI\n\nEveryday:\n\n| Command | Purpose |\n|---------|---------|\n| `fr apply` | Render + observe + diff + apply a plan to GitHub (dry-run by default; `--to \u003crunner\u003e` queues phases) |\n| `fr status` | Read-only plan report (allowlist-safe; never mutates) |\n| `fr isolation` | Isolated workspaces: `up`, `exec`, `status`, `down` |\n| `fr plan` | Plan editing: `create`, `edit` (tick steps, complete phases), `self-review`, `rework` |\n| `fr archive` | Move finished plans (and specs) to `implemented/` |\n| `fr skills` | Condensed overview of the skills + CLI surface |\n\nMaintenance:\n\n| Command | Purpose |\n|---------|---------|\n| `fr init` | Devcontainer profile scaffolding (`scaffold`) |\n| `fr repos` | Instrument locally-checked-out repos with a `plan-config.yaml` (`sync`; never clones) |\n| `fr repair` | Normalize stale plan/spec refs **and strip dead `plan-config.yaml` keys** (dry-run; `--yes` to write) |\n| `fr migrate` | Plan format migration (v1→v2; also strips dead `plan-config.yaml` keys) |\n| `fr undispatch` | Close a plan's tracking Issues and null the fields |\n| `fr pickup` | Output phase scope (markdown) for an agent |\n| `fr spec` | Spec status reporting |\n\n### Plan model\n\n- **One plan = one repo's worth of work.** Plans live in the repo they modify.\n- **One phase = one GitHub Issue = one PR.** Phases are scoped for reviewability.\n- **Cross-repo features use multiple plans**, coordinated through the shared\n  spec's \"Implementation Plans\" section (maintained by `fr-plan`).\n\nA plan is a folder, not a file:\n\n```\ndocs/superpowers/plans/\u003cYYYY-MM-DD-slug\u003e/\n├── _meta.yaml    # slug, spec ref, target repo, schema version\n├── _prose.md     # human-readable narrative\n├── 01.yaml       # phase 1: tasks + steps (P1.T1.S1 IDs), depends_on, tag\n└── 02.yaml       # phase 2 …\n```\n\n### Label lifecycle\n\nPhases queued to a runner (`fr apply --to \u003crunner\u003e`) carry exactly one\nprotocol-owned lifecycle label, projected from GitHub state on every tick:\n\n```\nfr:ready ──→ fr:in-progress ──→ fr:pr-ready ──→ (closed)\n   │\n   └─ fr:blocked   while depends_on phases are incomplete\n```\n\nPlus two markers: `fr:synced` (handed to the runner — the idempotency stamp\nthat prevents re-dispatch) and `manual` (human-only phase, never routed to an\nagent). Tracking-only Issues (no `--to`) carry no lifecycle label.\n\n**Reachability gate:** `fr apply --yes` refuses to dispatch unless the plan\nand spec are merged to `origin/HEAD` — the runner works from its own checkout\nof main, so anything not on main would be invisible to it.\n\n### Per-repo profile\n\nEach repo can **optionally** define `docs/superpowers/plan-config.yaml` to set\nthe plan filename pattern, required headers, and status values the plan\nvalidator enforces. It's read only by `scripts/validate-plans.sh`, which falls\nback to sane defaults when the file is absent — so a repo works without it.\n\nTo drop this file into a set of already-checked-out repos at once — without\ncloning anything — use `fr repos sync`:\n\n```bash\nfr repos sync derio-net/super-fr owner/other          # dry-run preview (default)\nfr repos sync derio-net/super-fr owner/other --yes     # write plan-config.yaml in place\n```\n\nRepos resolve via `$FR_REPOS_DIR` / `~/repos/\u003cname\u003e` (a missing checkout is a\nwarning, not a failure) or a manifest at `~/.config/fr/repos.yaml`; positional\nargs are appended to that manifest unless `--no-save`. `fr repair` and\n`fr migrate` also normalize this file, stripping any legacy keys the toolchain\nno longer reads.\n\n### Components\n\n| Package | What it is |\n|---------|------------|\n| `fr` | The CLI: plan-as-folder engine, GitHub tracking (render → observe → diff → apply), isolation |\n| `fr-dispatch` | Runner protocol + tick framework (library, runner-agnostic) |\n| `fr-vk` | VibeKanban adapter: MCP client, card/workspace dispatch, bridge daemon |\n\n## Requirements\n\n- [superpowers](https://github.com/obra/superpowers) plugin (super-fr wraps its\n  brainstorming, TDD, and review skills)\n- GitHub CLI (`gh`) authenticated\n- Docker (devcontainers for isolation)\n- [uv](https://docs.astral.sh/uv/) (for the `fr` CLI)\n- [VibeKanban](https://github.com/BloopAI/vibe-kanban) MCP server — only for\n  dispatch (`npx vibe-kanban@latest --mcp`)\n\n## For maintainers\n\nContributor workflow, the release/version-bump rule, the bridge-audit rule, and\nthe CI gate are documented in [`CLAUDE.md`](CLAUDE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderio-net%2Fsuper-fr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderio-net%2Fsuper-fr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderio-net%2Fsuper-fr/lists"}