super-fr: Instructions file for Claude Code

Agent instructions — super-fr

Internal working notes for agents maintaining this repo (super-fr itself, not a repo that merely installs it). User-facing rules the plugin ships to consumer repos live in plugins/super-fr/rules/; this file is for agents changing super-fr's own source. Claude Code reads this via CLAUDE.md's @AGENTS.md import; OpenCode reads it directly plus opencode.json's instructions array (.opencode/instructions/*.md — generated, see below).

Repo shape

uv workspace monorepo, version lockstepped across every manifest (see "Release / version bumping"). packages/:

• fr — the CLI/engine: plan-as-folder model, GitHub tracking (render → observe → diff → apply, single mutation path in apply.py, dry-run by default), isolation lifecycle. Entrypoint fr = "fr.cli:app".
  • fr journal (fr/journal/, commands/journal_cmd.py) — scope-keyed (spec|plan|debug) durable run-state under docs/superpowers/journals/{specs,plans,debug}/ (one subdir per scope so the tree is glanceable; archived to implemented/journals/<scope>/). add (create-only on --id — re-adding an existing id fails loudly and directs the caller to resolve) / resolve (appends a RESOLUTION RECORD closing a finding — fixed | refuted | deferred, the last needing --tracked-by <issue>; append-only, so the original entry is never rewritten) / render (raw, feeds PR bodies) / check (fail-closed on findings whose effective state — the fold of every record naming them, last one wins — is still open). fr plan create seeds a plan journal; parsing never depends on one (back-compat), and a journal with no resolution records folds to exactly what it did before resolve existed. fr-goal & fr-debugging write it as they run. The matrix's counterpart verb is fr acceptance set-status (in-place, beside add): a registry of CURRENT state, deliberately not a log.
  • fr models (fr/models.py, commands/models_cmd.py) — tier → model bindings (~/.config/fr/models.yaml, repo override > user) for fr-goal subagent dispatch; PhaseHeader.tier is the harness-neutral hint.
  • fr.bindings (fr/bindings/, 2026-10-06 spec model-binding-churn) — whether a bound model is still SERVED, beside fr/models.py (which stays the config layer). catalogue.py parses opencode models --verbose for lineage and price (never its status) and keeps last-known snapshots; probe.py asks the provider live (live/dead/unknown; dead only on positive provider evidence) and caches verdicts for 6 h; choose.py is pure — R4's family → tier → hint rules and is_autonomous, the one bound fr may act on unasked; health.py's check_bindings is the one report every caller reads; wording.py the one substitution line and journal decision body. The cache lives under $HOME/.cache/fr/models/ (FR_MODELS_CACHE_DIR overrides). Only OpenCode is probed: prober_for (the one factory, and the name tests monkeypatch) gives None elsewhere, which reports unprobed. Callers: fr models set/check, fr run start's notice, the gated brief's dead_bindings/binding_offers, and run_cmd._guard_dispatch_binding, which checks the exact tier both dispatch paths open and substitutes a dead USER binding autonomously (journal decision first, then the binding, restored on failure) or refuses.
  • fr-goal subagent execution (2026-07-22 spec): fr-goal dispatches each phase to the plugins/super-fr/agents/fr-phase-executor agent (serial, shared workspace); scripts/ensure-phase-executor-allowlist.sh (called by install.sh) allowlists it in the org agent-worktree hook, else fr-goal falls back to inline.
  • fr/workflow (2026-08-14 spec, workflow-shapes-and-workitem-dispatch) — the shape axis: model.py (WorkflowManifest/Step schema, parse_manifest), resolve.py (repo > shipped resolution — fr run start's real call site), check.py (fr workflow check: duplicate ids, dangling needs, cycles, unknown capabilities), artifacts.py (REPO_TRACKED_ARTIFACTS/IMPLIED_INPUTS_BY_UNIT/required_inputs — the vocabulary reachability derives from), reachability.py (path-level "is this on origin/HEAD", no item type — fr_dispatch's item-level gate calls into it, never the reverse), shapes.py (FR_GOAL_PHASE_DISPATCH — the default phase-granularity shape fr apply/the bridge still dispatch against; not yet resolved from a real manifest end to end, see the acceptance matrix). fr.capabilities (CAPABILITIES, the closed set requires: validates against) is a sibling of fr/workflow, not inside it; fr_dispatch.capabilities is a two-line re-export kept for import back-compat.
  • fr/verification (2026-10-06 spec, verification-strategies) — how a change is proven: model.py (StrategyManifest, closed placeholders), resolve.py (repo > env > wheel > marketplace, same order as workflows), check.py (fr verification check), spec_section.py (the spec's ## Verification grammar, a prose-only section counts as none), effective.py (effective_strategy/is_post_merge, the ONE place a row's strategy is decided, in R7's order), rows.py, and walk.py (fr verification walk: install through the repo's .fr/candidate-install into a tmp prefix, smoke, each row's scenario, a log bound to the run, strategy, manifest hash and code tree; fr/run/observed.py's allowlist decides which walk command deliver will witness). commands/verification_cmd.py also owns prerelease (the prerelease.yml dispatch). The matrix rows carry verify, scenario, issues, harnesses and walks (fr/acceptance/walks.py; matrix kind 4, record kind 8). Author-facing doc: docs/verification-strategies.md; this repo's own contract and scenarios are .fr/candidate-install and tests/scenarios/, run in CI by tests/integration/test_scenarios.py.
  • fr/run — the durable cursor (docs/superpowers/runs/<run-id>.yaml, git-tracked), driven by fr run {start,adopt,status,advance,resolve,check,cost} (model.py's RunState/StepRecord, commands/run_cmd.py). advance executes a kind: cli step directly and never a kind: agent one — it emits a dispatch brief instead; resolve is the only way an agent step's cursor moves past running. cost prints a run's cost per step and model from its usage file (fr/run/cost.py; run 7 moved every figure out of the cursor — the v5/v6 shape is frozen as fr.run.legacy.RunStateV6); deliver's derived proportionality evidence runs fr plan proportionality (fr/proportionality.py). plugins/super-fr/workflows/ ships the manifests this resolves (fr-goal.yaml, the pipeline /fr-goal itself now narrates); a repo may override one wholesale under docs/superpowers/workflows/<name>.yaml. Shipped manifests are NOT mirrored to OpenCode/Hermes like skills/rules are — fr run is a CLI surface every harness drives the same way, not a per-harness prompt. fr/run/liveness.py (2026-09-20 unit-record-unification §4.G, gh#518) is the ONE definition of "idle" — a run that is advanceable with nobody working on it: is_idle (pure) behind fr run check --idle (exit 3), plus --stalled-after (reported, never failed). It also owns the three predicates advance shares with it (gate_pending, next_step_id, hold_on). Two adapters call that CLI and re-derive nothing: plugins/super-fr/hooks/fr-run-idle-guard.sh (Claude Code Stop — BLOCKS; always exits 0, deliberately no set -e, because exit 2 from a Stop hook is itself a block and fr exits 2 on every refusal) and packages/fr-opencode-plugin/src/idle.ts (session.idle on 2.0.32, session.execution.succeeded on 2.1.x — CONTINUES; live-proven 2026-10-23, so enforced). Both act at most once per run position.
  • fr/tracker — the tracker protocol (model.py's Tracker Protocol
    • TrackedItem, a structural stand-in for WorkItem so fr never imports fr_dispatch; github.py's GithubTracker is the one concrete adapter). No second adapter exists yet — protocol-level only.
  • fr.harness (2026-09-18 spec, harness-parity-matrix) — a fourth closed vocabulary, sibling to fr/workflow and fr.capabilities: the shipped parity.yaml (src/fr/harness/parity.yaml, loaded via importlib.resources, never mirrored — it ships inside the fr wheel like any other package data) declares which enforcement/interaction surface is wired on which harness; observe.py reads the real registration files (hooks.json, .hermes/config.snippet.yaml, fr-opencode-plugin's marker comments) independently of the declaration, and check.py is the only bridge between the two. CLI: fr harness parity (commands/harness_cmd.py). prose.py's scan_prose is the sibling tool/argument-neutrality scanner (TOOL_VOCABULARY, ARGUMENT_VOCABULARY) over skill, agent and rule prose.
  • fr/triage (2026-09-21 spec, fr-triage) — backlog triage, split into a deterministic engine (fr triage {collect,check,render}, commands/triage_cmd.py) and a thin skill (plugins/super-fr/skills/fr-triage/) that holds only the judgement discipline. The split is forced: the OpenCode/Hermes mirrors copy only SKILL.md, so a script bundled beside a skill never reaches them — only the fr wheel reaches every harness. State lives in the scope's state directory, the workspace's .fr/triage-state/<scope>/ or $HOME/.cache/fr/triage/<scope>/ outside a clone (owner--repo or owner, lowercased; --dir overrides; a scope with a state repo is synced with refs/heads/fr-triage/<scope-id> by triage_cmd.resolve_state_dir, 2026-10-07 cloud-triage spec): facts.json (collect), judgements.yaml (the agent's, shape in spec §3.D), triage.html (render). It is never committed by default, so it is NOT an artifact kind. This repo keeps a durable copy of its own scope's inputs and history (judgements, origins, subsystems, snapshots, the architecture fragments' sources) in docs/triage/, moved by docs/triage/sync.sh export|import; the cache stays the working copy (see docs/triage/README.md). collect.py's Forge protocol (one implementation, ClientForge over the forge adapter) is the one place a second forge lands — that backend's adapter implementing the reads, not an edit to the collector. triage is in fr.artifacts.trigger.READ_ONLY_COMMANDS (it never touches a registered artifact), so the migration gate never refuses it. check always exits 0; its core sets are unranked (issues and PRs), settled, orphaned (the key names no repo collect read — the only set safe to act on without the forge) and unreachable (the forge would not show the issue, the repo was skipped, or the key was judged after the last collect). A DELETED issue is unreachable, not orphaned: collect views every judged key in a collected repo, so its failure is always recorded. The last set, stale dispatch, arrived with batches: an fr:in-progress issue whose batch marker comment is older than stale_dispatch_days, with no PR. Batches (2026-09-25 spec, triage-batches): fr triage batch {list,create,edit,cancel,suggest,dispatch,merge,drive} (commands/triage_batch_cmd.py) turn a group of judged issues into one fr-goal run with one PR. judgements.yaml carries batches: with engine-appended events (fr reads schemas 1–12 and writes 12, see the waves paragraph below) and facts.json schema 8 (open-PR join with files/head_oid, batch_prs, per-repo config from the target repo's .fr/triage.yaml). The engine is fr/triage/batch.py (stages, open-batch rule, the one writer, the §3.F merge order), batch_dispatch.py (brief, marker comment), batch_version.py (reservations) and batch_merge.py (reconcile, refusals, execution). dispatch, merge and cancel write the forge only with --yes, only through the GhClient adapter (§3.J; glab/tea raise UnsupportedForgeOperation, gh#611); git runs only in fr/triage/gitseam.py, which a tripwire keeps apart from the forge ban that globs every batch* module. triage_batch_cmd.py is fr's second find_spec-guarded soft point into fr_dispatch (test_import_direction.py _SOFT_POINTS). The board's decision views (2026-10-02 spec wave-driver, I): views.py is pure (needs_you, next_up, preselected_wave over a driver Snapshot built from facts alone, so the board and drive_pass read the same inputs), snapshot.py stores/diffs the per-render snapshots (render.py reads no clock; the command passes it), components.py holds the colour tokens, the phone gutter and the one tabs() component. Judgement.kind and Judgements.features load on any schema; check has an unplaced set. Origins and the architecture page (same spec, E and F): fr triage origins {collect,check,render} (origins.py; classification is the fr-origins skill's) and fr triage architecture render (architecture.py): the snapshot timeline, measured sections (line counts via the gitseam ls-tree/show at each subsystems.yaml ref), then authored architecture/ fragments in manifest order. Waves and the driver (2026-10-02 spec, wave-driver): judgements schema 3 adds wave/after per batch and the post_merge/closeout events; schema 7 adds audited replacement attempt/success/failure events that never change dispatch age or lifecycle; 8 adds claim_taken, which makes a taken member's claim owed (gh#1120); 9 the merge-train events; 10 the collected close-out (closeouts:, closeout_handback, closeout_hold, exit-gates R15/R27); current writers stamp 12 (read 1–12), adding recovery ownership/session audit metadata; 11 added archive_conflict (merge-truth R12). fr triage batch replace owns scope then pane locks, checkpoints and cross-store repair, never replaying uncertain submission; drive runs waves to completion. batch_drive.py is the pure pass (a Snapshot in, ordered merge, closeout, archive, dispatch, blocked, warn actions out; no fr_dispatch, no git, no process, the clock passed in); the command re-collects facts each pass (triage_cmd.collect_into), executes through dispatch_batch/merge_ready, fast-forwards and runs the repo's post_merge argument list through gitseam.Checkout, and starts each close-out as a unit="run" item with payload.kind: closeout. A drive.lock (pid, start time) refuses a second driver.
  • fr/usage (2026-09-25 spec, lean-cost-aware-process §5.A) — what a session or run cost, and on what, reconstructed from the harness's own records: readers/ (one per harness — Claude Code transcripts, OpenCode and Hermes SQLite opened read-only — each returning a UsageRecord and NEVER raising: a failure is unavailable, never a record of zeros), classify.py (pure (tool, command|path) -> activity), rollup.py (the harness's dollars split by fixed price ratios across activities and cursor step windows, plus turns), render.py (table / one HTML page, — for every missing figure). CLI: fr usage collect|report|backfill|compare (commands/usage_cmd.py; compare — usage/compare.py, 2026-10-06 spec cost-evidence §F — is the before/after tool: two sets of runs, selected by ISO date/timestamp or run id, over committed usage files, cursors of every version and plan journals; phases from the plan folder, --steps for the main session's per-step figures; pure engine, read-only, — for any missing input); the cache lives under $HOME/.cache/fr/usage/, so usage is in READ_ONLY_COMMANDS (backfill only writes archive files: it creates missing ones and prices sessions an archived one captured while they were still open, gh#756). Driver skill: fr-audit. Dollars always come from the harness; fr invents no list price. §5.B persists it: file.py is the usage artifact kind (docs/superpowers/usage/<run-id>.yaml, one capture per host, host label h-<sha256(run+hostname)[:8]>, an ALLOWLIST projection — never a model_dump of a record, which holds raw commands and paths), capture.py writes it at resolve --step deliver, a new host's first resolve and fr archive (never failing the step), backfill.py fills archived runs. Host-side rule (fr/isolation/where.py): fr run/fr usage execute on the harness host — fr isolation exec refuses them in devcontainer mode, and the run/usage groups refuse in-process on a devcontainer-mode workspace (target: devcontainer marker + container evidence), never on a host-worktree pod or an external marker.
  • fr/debt (2026-10-11 spec, debt-engine) — what a repo owes, as one DebtReport (model.py; schema_version: 1, frozen). engine.compute(repo_root, *, forge, now, stale_days) is pure given the forge and the clock: acceptance from load_matrix (an unreadable matrix is available: false, never zero), plans from fr.closeout.plan_sweep (archivable with merge age from git log on the default ref, stale when the plan dir, its run branch and its PR's updatedAt are all older than stale_days), and owed items folded by fold_owed(OwedSources), one per key (spec:, plan:, row:, issue:), precedence journal > row > plan > issue (a new source is one OwedSources field and one OWED_PRECEDENCE entry). debt_total() is the one definition of zero debt. render.py has text, markdown (markers <!-- fr-technical-debt --> and base64 fr-debt-figures) and parse_figures; forge.py adapts GhClient to the engine's DebtForge protocol. .fr/debt.yaml takes one key, stale_days. CLI: fr debt [--json] [--stale-days N] [--offline] (commands/debt_cmd.py), read-only, so debt is in READ_ONLY_COMMANDS; fr acceptance digest re-renders the report's Acceptance section. DEBT_STATUSES (acceptance/model.py) is the one status set open_rows, status and the digest count.
  • fr/record (2026-09-25 spec, lean-cost-aware-process §5.C) — step records: one YAML per agent step at docs/superpowers/runs/<run-id>.records/<step>[__<item>].yaml (artifact kind record, transient: committed while the step runs, deleted by the resolve that applies it). model.py (StepRecord; allowed_sections reads the step's emits: — journal:<scope>, plan:ticks, acceptance, the tokens in fr.workflow.artifacts), apply.py (apply_record — THE one bookkeeping write path: validate against the manifest and disk, build every write in memory, write atomically, run fr run resolve's own gates in process via run_cmd.resolve_in_process, restore every byte on a refusal, commit once, one line), template.py (the pre-filled record in the dispatch brief's record key and fr pickup, or "record in progress"), pr_body.py (deliver renders pr-body.md and refuses a live PR missing a required section, read via fr.gh.view_pr_body), gates.py (the refactor gate, moved here from fr plan self-review). CLI: fr run resolve --record; fr journal add/resolve, fr plan edit --tick/--complete-phase and fr acceptance add/set-status build one-entry records through the same engine.
  • Cloud triage (2026-10-07 spec, cloud-triage) — the wave driver and its workers in Claude Code cloud sessions. fr.forgeapi resolves the one host setting forge.api: rest | graphql (FR_FORGE_API, else ~/.config/fr/forge.yaml, else graphql); under rest, fr/real_ghrestclient.py (RealGhRestClient) is the GitHub client, REST routes only, because the cloud proxy refuses GraphQL. fr/triage/state_ref.py keeps a scope's durable state on the orphan branch refs/heads/fr-triage/<scope-id> (the cloud git proxy writes only refs/heads/*; fetch before read, reading the legacy refs/fr/triage/<scope-id> when the branch is absent; compare-and-swap push after every change, a push the remote refuses only a warning after a command's own work); privacy.py is the guard (leak_risk) that refuses a private repo's issue in a scope whose state repo is public, and every push; lease.py the one driver per scope; driver.py the driver adapter (host | cloud: runner, refusals, post_merge), fr triage drive pass|record its cloud entry; drift.py the pure version-drift planner (re-homes, the driver's self-update). fr.cloud (fr cloud doctor|setup-script) checks a cloud session's prerequisites and appends one remedy block to the failures they explain, only when CLAUDE_CODE_REMOTE=true. fr.agents + fr/artifacts/agents_kind.py are the agents artifact kind: .claude/agents/fr-{spec-reviewer,phase-executor}.md rendered from the wheel copy (scripts/sync-agents-data.py, tripwire test_tripwire_agents_data.py, whose sha pin makes an agent edit move the kind's version) by fr init agents. Operator doc: docs/cloud-setup.md.
  • fr/ops (2026-10-22 spec, fr-ops) — a plan's manual operations as typed, checkable, runnable records. model.py (Op, strict; LegacyOp, the # manual-operation step-block reader), load.py (ops.yaml plus step blocks plus the .fr/ops.yaml runbook; plan_has_ops, which fr.verification.exit reads to add devops to a run's gates), engine.py (status/order over an injected runner), apply.py, attest.py, evidence.py (op plan-journal entries, recorded_close), trust.py (R19: the operator's grant, OUTSIDE the repo), probe.py/mask.py (minimal-env, bounded probes; every reason sanitised), profile.py (ops: true profiles), helpers.py (seal/secret/clip/scratch), holds.py (what still holds a devops gate, by recorded evidence) and gate.py, the DevOps stage's sequencer: eight stages as data over host/workspace/forge/prompt ports, its state host-side (HostGateState); the ops workspace is PR-controlled, so an op closes there only by its live status and a journal closure or Test Plan outcome only when added on the ops branch after the recorded head. CLI: fr ops {status,apply,attest,trust,seal,secret,clip,scratch,gate} (commands/ops_cmd.py, commands/ops_gate_cmd.py); the whole group is gated by the artifact trigger. Every python -m fr fr starts runs with -P (no cwd on sys.path). Driver skill: fr-devops-gate; author doc: docs/ops.md.
• fr-dispatch — runner-agnostic protocol/tick framework. Runners register via the fr.runners entry-point group, not by editing this package. work_item.py (WorkItem, the item_id/parent_id identity grammar) and item_graph.py (build_items — the one item builder for all three decomposition units, run/phase/spec) are the dispatch-cutover core; reachability.py is the item-level gate wrapping fr.workflow.reachability.
• fr-vk, fr-cncd — runner adapters (vk, cncd) implementing that protocol. fr-cncd is real but predates its own README/CLAUDE mentions — don't assume tables in README.md are exhaustive; check packages/*/pyproject.toml and plugins/super-fr/skills/ against prose before trusting a list.
• fr-herdr — the herdr runner (entry point fr.runners: herdr), managed OpenCode lifecycle/restart adapter as well as Claude resume. Host-local descriptors/locks live in fr_herdr.managed, safe input in fr_herdr.opencode. Operator notes: docs/herdr-control-sessions.md, packages/fr-herdr/README.md. Optional SessionReplacer supports in-place Claude/OpenCode and model-only fresh replacement. Pending checkpoints exclude restart until explicit repair; installed synthetic scenarios are not evidence of the operator-owned live walk. Explicit absent-source batch replace --recover uses fr_herdr.recovery and global pane/tab/agent joins, pre-allocation server/item/source-keyed intent, a new herdr pane and observed session identity. Repair never allocates or sends input. Recovery HOLD overrides conflict/unfinished continuation on reconstruction and managed restart; the disposable actual-client walk is post-merge Tester. It was the first to take unit="run" work: fr triage batch dispatch builds it through fr_dispatch.registry.load_runner's from_env() and it opens a herdr tab, starts the harness on the batch's model and submits the brief. It never imports fr.triage, and fr never imports it (test_import_direction.py); fr_dispatch.testing holds the reusable run-unit contract it passes.
• fr-claude-cloud — the claude-cloud runner (entry point fr.runners: claude-cloud): a mailbox, not a backend. Every session action becomes a request in the scope's state (requests.yaml, sessions.yaml) that the cloud driver's agent executes with its session tools and records back (fr triage drive record); re-homing is its restart. Like fr-herdr, it never imports fr.triage.
• fr-opencode-plugin — the one non-Python package: TypeScript/Bun, an OpenCode 2.x plugin definition (export default { id, setup }; 1.x is not supported) porting the Claude Code hooks: the edit gate and the whole-line shell gate (fr-isolation-guard) on execute.before, the merged-PR push guard, the pipeline sentinel, session bind/unbind, the acceptance nag, the idle nudge, the fr binary pin, the child-session claim, and a TUI status line (src/tui/). Each ported hook carries a // super-fr-parity: marker fr harness parity reads. install.sh delivers it as ONE plugin directory (scripts/deliver-opencode-plugin.sh). Excluded from the uv workspace (pyproject.toml's [tool.uv.workspace].exclude) and has its own package.json/version, so uv run pytest does not cover it — but it IS wired into CI, as the opencode-plugin-test job (bun test). Run that locally inside packages/fr-opencode-plugin/ if you touch it.