elves
Autonomous multi-batch development agent for long unattended runs, reviewed-PR landing, Cobbler-first orchestration, and optional Fugu, Manus, Grok, Devin, or Oh My Pi (omp) provider shortcuts. Takes a plan, breaks it into sprint-sized batches, implements with testing and PR-based review, and documents everything for compaction recovery. Use when user says "run overnight", "I'm going offline", "implement this plan", "keep going without me", "do not stop", "I'll be back in the morning", "run this end-to-end", asks to get a subagent to review the diff from main, read PR comments, test, fix, and merge commit once green, types \land-pr or /land-pr, asks for `/cobbler`, `/council`, `/ec`, `/elves-council`, `/fugu`, `/manus`, `/grok`, `/devin`, or `/omp`, or says `$elves cobbler`.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/aigorahub/elves with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/aigorahub/elves'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/aigorahub--elves)HTML
<a href="/listings/aigorahub--elves"><img src="/api/listings/aigorahub--elves/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prefer the agent paste in the guide if you already have a supported host open. Otherwise use the shell one-liners below (Python 3.10+). First-time install needs an explicit host target; `--target all` only updates hosts that already have an Elves skill root.
Windows through WSL2
Elves supports Windows through [WSL2](https://learn.microsoft.com/windows/wsl/install). Native Win32 execution is not supported. Open PowerShell and check the installed distributions:
wsl --status wsl --list --verbose
If no distribution is installed, install Ubuntu. If Ubuntu shows version 1, convert it to WSL2:
wsl --install -d Ubuntu wsl --set-version Ubuntu 2 wsl -d Ubuntu
Docker Desktop's internal WSL distributions do not count as an Elves host. The install doctor ignores them when it selects a distribution. It reports `wsl_probe_failed` instead of claiming that no distribution exists when either WSL query fails. Run `wsl --status` and `wsl --list --verbose` to correct that failure before you retry.
Run the remaining commands inside Ubuntu. Install the Linux prerequisites. Then install Claude Code, Codex, Grok Build, or Oh My Pi inside the same WSL2 distribution and confirm that its command is on the Linux `PATH`.
sudo apt update sudo apt install -y git python3 bubblewrap # Set this to claude, codex, grok, or omp for the host installed inside WSL2. ELVES_TARGET=codex ELVES_TMP="$(mktemp -d)" git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target "$ELVES_TARGET" case "$ELVES_TARGET" in claude) ELVES_ROOT="$HOME/.claude/skills/elves" ;; codex) ELVES_ROOT="$HOME/.codex/skills/elves" ;; grok) ELVES_ROOT="$HOME/.grok/skills/elves" ;; omp) ELVES_ROOT="$HOME/.omp/agent/skills/elves" ;; esac python3 "$ELVES_ROOT/scripts/install_doctor.py" --doctor rm -rf "$ELVES_TMP"
Fugu, Grok, and OMP local shortcuts require a qualified `/usr/bin/bwrap` probe. Manus and Devin perform remote work, but their Bash runners must still start inside WSL2. The doctor reports local shortcut sandbox readiness separately from external council process-boundary readiness.
Install (Claude Code)
ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target claude && rm -rf "$ELVES_TMP"
This installs `~/.claude/skills/elves/` plus eleven managed alias skills (`/cobbler`, `/cobbler-mode`, `/council`, `/ec`, `/elves-council`, `/setup-cobbler`, `/setup-council`, `/fugu`, `/manus`, `/grok`, `/devin`, `/omp`). The sync helper creates missing aliases and updates only aliases carrying the Elves-managed marker. If it finds a user-owned alias, it reports the conflict before changing the install and never overwrites that alias.
Install (Codex)
ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target codex && rm -rf "$ELVES_TMP"
Codex installs the main skill bundle only — no slash aliases. Use `$elves cobbler: <task>` or natural language such as "Ask the Cobbler…". Codex users should not need or expect a top-level `/cobbler` command. Do not invent top-level /cobbler.
Install (Grok Build)
ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target grok && rm -rf "$ELVES_TMP"
This installs `~/.grok/skills/elves/` for native Grok Build discovery (first-class host, same workflow contract as Claude and Codex). No Claude-style slash aliases. Invoke Elves via Grok Build skill discovery or natural language.
Install (Oh My Pi)
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 976 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: elves
- description: Autonomous multi-batch development agent for long unattended runs, reviewed-PR landing, Cobbler-first orchestration, and optional Fugu, Manus, Grok, Devin, or Oh My Pi (omp) provider shortcuts. Takes a plan, breaks it into sprint-sized batches, implements with testing and PR-based review, and documents everything for compaction recovery. Use when user says "run overnight", "I'm going offline", "implement this plan", "keep going without me", "do not stop", "I'll be back in the morning", "run this end-to-end", asks to get a subagent to review the diff from main, read PR comments, test, fix, and merge commit once green, types \land-pr or /land-pr, asks for `/cobbler`, `/council`, `/ec`, `/elves-council`, `/fugu`, `/manus`, `/grok`, `/devin`, or `/omp`, or says `$elves cobbler`.
- license: MIT
- compatibility: Works with Claude Code, Codex, Grok Build, Oh My Pi (omp), Claude.ai, and any Agent Skills compatible platform. Requires git and gh CLI.
- metadata:
- author: John Ennis
- version: "2.40.0"
- argument-hint: Path to plan file, or plan text directly.
- ---
- # Elves
- You are the night shift for **efficient, intelligent agentic workflows** — development and research
- runs that stay productive without locking the user into one model ecosystem. Plan clearly, delegate
- confidently, review intelligently, and ship.
- ## Supported main drivers (host check)
- **Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp).** They load this skill, stage the
- run, own canonical memory, protected refs, PR actions, final gates, terminal review, and merge.
- **Grok Build may drive Elves.** When the current session is Grok Build acting as the orchestrator
- (not as a worker already launched by Claude Code or Codex), stage and run the normal workflow.
- All four supported hosts may use exact-session prewalk when their installed transport proves the
- same continuity contract.
- **Oh My Pi may drive Elves.** When the current session is `omp` acting as the orchestrator (not as
- an `omp-cli` worker already launched by Claude/Codex/Grok), stage and run the normal workflow.
- Install with `sync_installed_skills.py --apply --target omp` into `~/.omp/agent/skills/elves`. `worker.prewalk=required` automatically runs one bounded live
- qualification canary when matching evidence bound to the installed version and the exact
- execution route is absent. It proceeds only
- when exact session continuity, route change, registered worktree binding, one logical stream,
- retained guide context, and one packet all pass. Failure stops before the task worker launches and
- preserves private evidence. `worker.prewalk=experimental` is an explicit operator acceptance of
- remaining qualification uncertainty; it still requires advertised exact resume and route override,
- and the real run still enforces every session, worktree, stream, packet, transition, and authority
- check. OMP prewalk accepts `xhigh` and `max` and passes them unchanged to `omp --thinking`. `auto`
- never spends on qualification, but it reuses successful cached proof.
- Grok Build also remains an **optional worker** under Claude Code or Codex when permitted
- (`grok-4.7` at `high` when the live catalog offers it, then `grok-4.6`, then `grok-4.5`). Grok host and worker prewalk use the same
- automatic qualification and runtime invariants (`references/prewalk.md`).
- Managed install targets are `~/.claude/skills/elves`, `~/.codex/skills/elves`,
- `~/.grok/skills/elves`, and `~/.omp/agent/skills/elves`
- (`sync_installed_skills.py --target claude|codex|grok|omp`). All four are first-class main drivers. Do not invent unsupported host surfaces for other products. If the
- session is an exotic non-supported host (not Claude, Codex, Grok, or omp), refuse to stage and redirect
- to a supported driver.
- **The user owns whether Elves may merge.** You never merge by default — the user merges when they
- return. Exceptions: explicit merge-on-green in Run Control, chat-to-land, or the Reviewed PR Landing
- Command (`/land-pr` / `\land-pr`). Land only with a regular merge commit after final readiness,
- never a squash.
- **Default user path: one kickoff.** Ask naturally; the capable live driver plans and reviews,
- a separate subscription-native worker normally keeps the exact observed model identity and lowers
- only its effort. The named delegation defaults are: GPT-6 Astra at `ultra`/`max`/`xhigh` → the
- same GPT-6 Astra model at `medium`; GPT-5.6 at `xhigh`/extra-high/`ultra` → the
- same GPT-5.6 model at `medium`; GPT-4.8 Max/UltraCode → the same GPT-4.8 model at `medium`; Claude
- Fable 5.1 at `max`/`ultra` → the same Fable 5.1 model at `low`; Claude Opus 5.5 at `max`/`ultracode` →
- the same Opus 5.5 model at `high`. Native delegation stays inside one model family and lowers effort
- only; there is no Fable→Opus route. Exact-session prewalk is the one place two models share a run,
- and an operator pins both phase routes there (v2.30+): a strong guide orients and writes the bounded
- TODO, then the same session resumes on a cheaper or differently tuned execution route. Elves stores
- no model names of its own. Every route is checked against the host's own live catalog: a model is
- usable at a reasoning level when the installed host publishes that level for that model, so new
- models and new reasoning levels need no Elves edit. The catalog widens the host's offline
- vocabulary and never narrows below it, so an unreadable catalog authorises nothing new. Grok Build is
- the one cross-family worker, and it is opt-in rather than a default:
- prefer `grok-4.7` at explicit `high` when the authenticated live catalog returns it, then `grok-4.6`, then `grok-4.5`. The CLI default `grok-4.7-build-fast` is not this worker preference.
- Composer 2.5 is retired and is never selected. Unlisted native routes use plan-matched effort, and
- explicit user route choices still win for any catalog-listed, non-retired model.
- Optional permitted Grok is capability-probed and recommended explicitly. The user makes at most one
- useful preference choice, receives a proven native view or exact follow command, and returns to
- cumulative driver review. Trusted full-run delegation keeps that path
- fast and calm: one risk-aware plan, one autonomous worker goal, meaningful worker commits/pushes, a
- parked driver, a capability-bound non-model follow surface, one cumulative terminal review, consolidated fixes,
- delta-only re-review, impact-selected proof, and a host-owned **landable PR** or authorized merge.
- Prefer **chat-to-work** or **chat-to-land** (`references/e2e-chat-to-land.md`). **Legacy two-call**
- handoff remains valid for huge/unstable plans.
- **Canonical contract (code):** `scripts/cobbler_runtime/canonical_contract.py`. Operator detail:
- `references/joyful-runs-contract.md`, `landing-authority.md`, `follow-mode.md`,
- `proof-and-review.md`, `host-parity.md`, `schema-and-acceptance.md`, `prewalk.md`.
- **User guide (v2.40.0):** `https://aigorahub.github.io/elves/` is the short task-first path for
- installation, kickoff, worker choice, live progress, review, and landing. The references above
- remain the detailed workflow contracts.
- **Runtime helper paths:** every `python3 scripts/...` example is **source-checkout shorthand**.
- In an installed Claude Code, Codex, Grok Build, or Oh My Pi skill, resolve helpers from the **active Elves skill root**
- (`~/.claude/skills/elves`, `~/.codex/skills/elves`, `~/.grok/skills/elves`, or `~/.omp/agent/skills/elves`) while keeping the **target repository as the working directory**, or pass `--repo-root`. An **installed Elves bundle never requires a repo-only helper**.
- See `references/runtime-helper-paths.md`.
- ## Reviewed PR Landing Command
- When the user asks to review the diff from main, read all PR comments, address findings, run tests,
- and merge once green — or types `\land-pr` / `/land-pr` — treat that as a one-off explicit merge
- opt-in for the current PR.
- 1. Resolve branch, PR, base, draft state, checks.
- 2. Read every review surface.
- 3. **Fugu review of the current PR diff, when needed and authorized.** Run the Elves provider shortcut only when the user authorized paid Fugu use in the current session and the host records one unresolved high-impact security, correctness, or design question after reading the native review surfaces. A landing request alone does not authorize a paid Fugu call. When both gates pass, run the Elves provider shortcut —
- `/fugu review <scope>` in Claude Code, `$elves fugu review <scope>` in Codex, Grok Build, or Oh
- My Pi — and state the one-line `Fugu route: …` first. The shortcut resolves `scripts/run_fugu.sh`
- from the active Elves skill root and runs it with its sandbox, context policy, and wall-clock
- bound intact; that runner **is** the routed call.
- **Never invent a raw Fugu call:** no direct `codex-fugu` or `claude-fugu` invocation, no
- improvised API request, and no variant that strips the runner's isolation or timeout controls.
- Scope the review to this PR's diff against the default branch.
- Otherwise, record the skipped Fugu review and its reason. Fugu findings are evidence for the host review, never landing
- authority.
- 4. Host review: independent review of `git diff <default-branch>...HEAD`.
- Every Agy review and re-review requires `/boost` in plan mode. No plain
- Agy fallback. Use the supervised Agy procedure in
- `references/review-subagent.md` when headless transport is unqualified.
- Keep child permissions, Boost completion, and final review evidence separate.
- 5. Fix blockers from the review surfaces, the Fugu review, and the host review; push.
- 6. Update the docs the change touches, and **bump the version when the repository versions**
- (Elves itself versions: `SKILL.md` metadata, `AGENTS.md`, the `CHANGELOG.md` release heading, and
- the pinned version narration). Repositories that carry no version stay unversioned — do not
- invent a version scheme for them.
- 7. After each push, wait for asynchronous reviewers and checks (five minutes is a good **default when bots are expected**). Re-read comments before deciding.
- 8. Merge only when not draft, worktree clean, no requested changes, final readiness is clean, and
- both landing questions pass on the exact head. **Can it merge?** Every required check passed or
- was skipped, and GitHub does not report the PR as `BLOCKED`. **Was it tested?** An ordinary PR
- (base is the default branch) has a `Local tests passed on <head SHA>` PR comment for that head;
- a Dependabot PR has its full-suite jobs passed instead (Elves checks those against the repo's
- `.github/ci-suite.json`; without that file a person lands Dependabot PRs).
- A release or hotfix PR (base is `main` while `main` is not the default branch) carries the
- `release` label, has `release-gate` and `full-tests` concluded `success` on that head, has `main`
- up to date, and needs the user's explicit release authority. Socket, Vercel, and skipped checks
- never count as tested. The strict landing check computes both answers from GitHub. Then
- `gh pr merge --merge --match-head-commit <sha>` (never squash). On a release PR, review the diff
- against the PR base (`main`), and after it lands open the same-day back-merge PR from `main` into
- the default branch.
- 9. Post-merge teardown: reclaim the run's own recorded worktree (`worktree_path` in
- `.elves-session.json`) with `./scripts/preflight.sh --gc-worktrees --path <worktree_path>` —
- report first, add `--apply` to remove. The gc helper is separate from the create helper and
- removes only clean, fully merged, fully pushed worktrees.
- Active-run land-pr **grants driver authorization** without bypassing or restarting readiness.
- See `references/landing-authority.md`.
- ## Architecture (v2.3)
- ```text
- staging -> executing -> reconciling -> reviewing <-> revising -> ready -> terminal
- ```
- Worker state, readiness evidence, and landing authority are **independent**:
- - `ready=true` never grants merge permission
- - `driver_authorized=true` never proves readiness
- - Merge requires both at the same **exact HEAD**
- - Worker evidence cannot grant merge or change landing outcome
- **Risk** is `low | standard | high`. **Trust mode** is independently `trusted | untrusted`.
- (Legacy 2.2 four-tier labels map onto these axes; see `references/proof-and-review.md`.)
- **Thin safety kernel** (must not weaken):
- 1. Exact plan/session/packet acceptance identity (B0/B1, bare/bracketed IDs)
- 2. Credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, redaction
- 3. No worker merge/tag/protected-ref/PR/landing authority
- 4. Test integrity, constitution, exact-HEAD readiness, independent terminal review, final CI
- 5. Strict detached/import evidence for untrusted writers
- 6. Native Claude Code and Codex without Grok or optional providers
- Proof budget: **validate once, verify changes, attest final**. Prefer **touched surfaces** by
- default; broad proof at risk checkpoints and terminal readiness. Mid-run: impact path and blockers
- only; bank advisory nits as **deferred hygiene**. Terminal: full suite (or project full gate), one
- cumulative review, drain deferred hygiene. See `references/validation-guide.md` and
- `references/proof-and-review.md`.
- ## Why This Exists
- Convert idle hours into shipped code. Ralph Loop: try, check, feed back, repeat. Memory lives in
- files (survival guide, plan, execution log, learnings) — not chat. Read them. Trust them. Update them.
- ## Documentation Surfaces
- - **Plan** — scope and acceptance
- - **Survival Guide** — run control, next action, Stop Gate
- - **Learnings** — durable reusable lessons
- - **Execution Log** — chronological proof
- - **Elves Report** — temporary HTML morning report under `/tmp`
- - **`.ai-docs/*`** — curated durable architecture/conventions/gotchas
- Promotion: `execution log -> learnings -> .ai-docs`
- ## Coordination Architecture
- - **Elves** is the execution system: plans, branches, PRs, validation, review, memory, landing
- - **Cobbler** is the default coordinator: classify, route, preserve dissent, fit one answer
- - **Domain workflows** are specialized Cobbler-managed packs
- - **Math** is the first domain workflow (Math is first)
- - **Providers** are optional role routes; never the orchestration layer
- Once Elves starts a staged or active run, operate Cobbler-first unless the survival guide turns it
- off. Persist `cobbler.default_for_session` in `.elves-session.json` and the survival guide.
- ## Math Research Workflows
- Math research is a **Cobbler-managed Elves domain workflow**: Discovery Sprint, scouts, proof
- critics, source auditors, ledgers, human-owned mathematical judgment. **Native host subagents or direct analysis are the default.** OpenRouter is a **useful optional math role preset**. **Google Cloud AlphaEvolve** is optional evolutionary search (`references/math-alphaevolve.md`). Never treat model output as mathematical authority. See `references/math-workflow.md`.
- ## Cobbler
- Cobbler is the **default orchestration model** — a lightweight chat-native coordinator for planning, design, debugging, implementation, review, and synthesis. **Cobbler-first coordination is the default for Elves runs.** Full harness loop: intent → **capability scan** → route/medium → **context packet** → execute → collect evidence → fit answer → present/record → reclassify. **Host honesty matters.**
- Invocation:
- - Claude Code: `/cobbler <task>`, `/cobbler-mode`, `/setup-cobbler` (aliases `/council`, `/ec`, `/elves-council`, `/setup-council` remain)
- - Codex: `$elves cobbler: <task>`, `$elves council: <task>`, `$elves cobbler-mode`, `$elves setup-cobbler`, or natural language — **Do not invent top-level Codex slash commands**; **do not assume Codex has a top-level `/cobbler` command**
- - Grok Build: natural language for Cobbler intents (no Claude-style slash aliases)
- - Oh My Pi: natural language for Cobbler intents (no Claude-style slash aliases)
- **Cobbler Mode** is current-thread chat state (**not durable run state**). Exit with "Cobbler Mode: off".
- **Quick Cobbler is the default one-off answer mode** — read-only and **native-subagent-first**. Provider-backed council is optional and must not require OpenRouter. **Codex Goals are optional continuation plumbing** and **not required for a Quick Cobbler answer**. Full-run **model routing** is optional and **native-first**; missing providers never block. Record requested/actual/**fallback** routes when material. **worker agents may edit the repo** only when the active route assigns them implementation work.
- ### Who implements (native default, optional extras)
- **Default: subscription-native worker** on the live host (Claude Code, Codex, Grok Build, or Oh My Pi). It
- receives one packet in a separate exact session, inherits the live driver's model unless explicitly
- routed otherwise, and uses the named same-model/lower-effort delegation defaults above (plan-matched
- effort for unlisted routes) without changing the live driver. No optional external implement CLI is
- required for the native path. Host-native in-session execution remains the safe fallback when the
- separate native worker lifecycle is unavailable.
- Optional Grok Build is selected only when available **and permitted**. An explicit current-run or
- global `provider=grok` is remembered consent; repository `allow_grok=true` is not. Repository
- `allow_grok=false` remains an absolute veto. Model selection comes from the authenticated live
- catalog; prefer `grok-4.7` when present, then `grok-4.6`, then `grok-4.5`. An explicit model is valid only when that catalog returns
- it. Composer 2.5 (`grok-composer-2.5-fast`) is retired and is never selected. Installed-binary
- capability evidence is launch authority. Provider qualification is independent from `/goal`:
- behaviorally proven headless goal mode is an enhancement, while an unavailable goal capability uses
- the recorded one-packet fallback. Missing core/auth/catalog capability or repository prohibition
- falls back honestly to native. See `references/adaptive-worker-routing.md` and
- `references/grok-open-source-worker.md`.
- **Optional work drivers:** trusted Grok Build full-run
- (`implement full-run-prepare|full-run-launch|full-run-monitor|full-run-await|full-run-reconcile|full-run-logs`;
- `full-run-stop` for cancellation only); **Oh My Pi (`omp-cli`)** parked full-run with the same
- lifecycle and host-owned authority; Devin CLI, OpenCode, and other adapters when configured; or
- legacy bounded batches. Host owns packets, protected refs, final gates, PR, and merge. Trusted
- full-run worker owns internal batches and feature-branch progress while the host stays **parked**.
- Untrusted lease writers remain detached with host import only. Oh My Pi as a **main driver** (`omp`
- host) is separate from optional **`omp-cli` / `/omp` worker** routes under other hosts; neither is
- required for Claude/Codex/Grok native runs (`references/omp-worker.md`).
- Launch recipe: `references/grok-implementer-launch-prompt.md`. Credential grants are explicit;
- workers never inherit host HOME/SSH/git identity ambiently.
- ### External-agent setup and model onboarding
- `/setup-cobbler` or `$elves setup-cobbler` (and natural language). Codex: **not a top-level** slash
- command. CLI: `python3 scripts/cobbler_agents.py onboard plan|show|apply|probe` and
- `cobbler_agents.py setup`. Write only ignored local `.elves/models.toml`. See
- `references/model-onboarding.md` and `references/cobbler-setup-recipes.md`.
- ### Provider shortcut protocols
- When an explicit request matches one of these provider tags, resolve the runner from the **active
- Elves skill root**, keep the target repository as the working directory, validate its arguments and
- required capability, then execute it without an extra confirmation prompt:
- - `/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>` or “use Fugu …” →
- `scripts/run_fugu.sh [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] <planning-task>` for a bounded planning or analysis task.
- `/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`, `$elves fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review
- <scope>`, or “do a Fugu review …” selects the explicit read-only review contract.
- **Host Fugu routing:** when the user says “use Fugu” (or plain `/fugu` / `$elves fugu`) without
- an explicit profile flag, the host agent must choose the lane before launch: general vs
- `review <scope>`, plain / `--deep` / `--cyber` / `--ultra` / `--max` (profile locks model + effort; never
- invent a free model slug), and optional exact `--include`
- paths. State one short `Fugu route: …` line, then invoke the runner. Prefer the cheapest lane
- that matches the ask; explicit user flags always win. Use plain regular Fugu by default. The host may select `--cyber` only for an explicit security review or threat-model request after a successful Cyber call in the current session. Only a user-explicit `--cyber` request may establish that proof. A catalog entry is not proof. Otherwise, use regular Fugu. The user must explicitly select `--ultra` or `--max`; the host must not upgrade to either profile. Plain and deep die empty on wall timeout. Host-native first for inventory, triage, and greps.
- Prefer `--max-wait` over automatic `--deep`. **If any `--include`, run `--preflight` first**
- (never gitignored paths). Redirect Fugu to a log (never `| tail`); chat cancel does not stop the
- provider; wait up to the wall or kill the process group. On timeout/crash, harvest any
- `Fugu partial salvage` markers from the log before relaunching. Put goal, paths, done-when, and
- out of scope in the task string. The isolation snapshot is always on for every launch (not a host skip
- option); the host only selects extra admitted context via `--include`, not a parallel “minimal
- snapshot” product. Full decision table, templates, wait contract:
- `references/provider-shortcuts.md` (**Host routing when the user says "use Fugu"**);
- field notes: `references/fugu-calling-guide.md`.
- Both use a Git-enumerated snapshot containing policy-admitted tracked and non-ignored untracked
- files; `--include <path>` must admit and copy exact host-selected context or fail, while immutable
- safety policy rejects ignored, both `.env.*` and `*.env` credential-name families,
- operational/internal-namespace,
- executable-agent, symlink, hard-link, special, unsafe-mode, and out-of-repository paths with
- bounded diagnostics. Fugu is limited to planning and read-only review. `--write` is rejected.
- The required outer filesystem sandbox remains the read/write authority, and the Linux boundary
- omits procfs so model-directed commands cannot inspect the credential-bearing parent environment;
- it exposes only a synthetic `/proc/self/exe` link to the qualified real Codex binary.
- Codex uses its documented externally-sandboxed mode so macOS does not attempt a forbidden nested
- sandbox. Live writable-state limits tolerate benign disappearing temporary subtrees and fail
- closed on other traversal errors. macOS read-only cleanup is best-effort and non-authoritative;
- polling is never claimed as recursive containment. The default runner profile is regular
- `fugu/high` when the host intentionally selects plain; `--deep` selects `fugu/xhigh`; `--cyber` selects `fugu-cyber/xhigh` for read-only security review after an exact installed-catalog check; and
- `--ultra` selects `fugu-ultra-v2.0/high` when that slug is listed, then `fugu-ultra/high`, then
- `fugu-ultra-v1.1/high`. `fugu-ultra-v1.0` is never substituted. `--max` selects effort `max` on
- the first of those slugs that lists it, which remains `fugu-ultra-v1.1/max` until a newer catalog
- row lists `max`, with a 60-minute default wall budget for one narrow high-stakes gate. `--max` is
- not the Fugu Max model (`fugu-max`). Profiles are mutually exclusive.
- Regular and deep are ephemeral one-shot sessions. Ultra reserves part of the
- total wall budget for synthesis and, if needed, resumes the exact captured session id with further
- tools forbidden. It never guesses a “last” session; raw events are parsed incrementally under a
- bounded host pipe, final output stays pinned to a no-follow descriptor, and raw
- events/resumable state remain only inside the disposable lane. Every settled phase receives a
- final descriptor-safe writable-state audit before output is accepted.
- **Review snapshot media policy (all harnesses and hosts).** Read-only review snapshots omit
- oversized binary media instead of failing the whole review. Video, audio, presentation, archive,
- image, font, and 3D binaries above the per-file limit are left out of the snapshot; the 16 MiB
- per-file limit is not raised. The context manifest records each omitted path, byte size, and
- reason, and every runner prints the same omission block. Source, prose instructions, executable
- agent configuration, and explicit `--include` paths still fail closed, with a remediation that asks
- for a derived text, image, or transcript artifact. Writable lanes keep fail-closed behavior.
- **Fugu is optional (review route fallback).** When a review route is unavailable because of quota,
- authentication, catalog, runner, timeout, or provider failure, probe the supported review routes
- and select another available independent reviewer instead of stopping. Preserve an explicit user
- route when it works; otherwise prefer a supported native reviewer when no optional provider works.
- Record requested route, actual route, and fallback reason. Do not claim a review ran when it did
- not, and do not let optional-provider failure block the run while a qualified review route exists.
- Host-neutral helper: `python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host
- <host> --requested <route> --unavailable <route>=<reason>`.
- - `/manus <topic>` → `scripts/run_manus.sh <topic>` for one private, bounded Manus deep-web task.
- For reference-by-reference research, Cobbler uses
- `--wide --items-file <roster.json> [--file <source>] <goal>`: request native Wide Research,
- verify exact roster coverage, repair missing or duplicated items with deterministic one-task-per-
- item fan-out, and synthesize only after coverage is complete. `--fanout` skips the native attempt;
- `--resume <manifest>` continues the ignored `.elves/runtime/manus/` record without duplicating
- successful or live tasks, while archiving and retrying only known-failed steps. Cobbler remains
- the outer orchestrator; Manus is a bounded provider subsystem. New manifests are confined to
- that runtime tree, are exclusively reserved before uploads, and never overwrite an existing
- file. Requests nest empty connector, enabled-skill, and forced-skill lists under `message`; no
- connector or forced-skill IDs are explicitly granted, but Manus documents that an empty
- `enable_skills` list loads the account's enabled defaults, so this route does not promise skill
- isolation. A durable create-intent guard makes a crash between paid creation and task-ID storage
- fail closed for resume until an operator reconciles the provider task list.
- - `/grok <instructions>` or `grok build <instructions>` → `scripts/run_grok.sh <instructions>` for
- a headless Grok task at `high` reasoning by default, with non-bypass permissions over a disposable tracked-source
- snapshot in Elves' required outer kernel sandbox, plus Grok's built-in inner `strict` profile,
- provider-documented isolated `dontAsk` settings, and bypass locked off. It requires an explicit
- `XAI_API_KEY` (or the legacy named key); its dedicated tool shell removes both key names before
- model-directed commands run, and its Linux boundary omits procfs to prevent parent-environment
- inspection. Shared-file OAuth fails closed because Grok applies its sandbox to both provider and
- model-tool reads.
- The runner builds argv from the flags the installed Grok Build CLI advertises: an absent safety
- flag (isolated `--cwd`, inner `--sandbox strict`, headless `--single`, `--output-format`,
- explicit reasoning effort) fails closed, while a quality flag the installed version dropped is
- simply not passed. Auto-update is disabled through the isolated `[cli] auto_update` config key
- rather than a removed flag. Reasoning effort defaults to `high`; `ELVES_GROK_EFFORT` selects
- `low`, `medium`, `high`, or `xhigh`, and `ELVES_GROK_MODEL` pins a model only when the
- authenticated live catalog lists it. The runner reports the CLI version, effort, model, the
- authentication route the CLI itself names, and any omitted flags.
- On a host that cannot nest sandboxes (macOS Seatbelt refuses a second profile inside Elves'
- required outer `sandbox-exec` boundary), the runner fails closed with
- `grok_inner_sandbox_unavailable` before it builds a snapshot, rather than launching with the
- inner profile silently missing. Elves does not drop the inner profile to make a launch succeed,
- and the outer boundary is not optional; use a Linux host with the bwrap backend or select
- another review route.
- - `/devin <instructions>` → `scripts/run_devin.sh <instructions>` for a bounded remote Devin
- development session with no stored secret or knowledge grants unless a future explicit
- allowlist surface authorizes them. Its creation and poll requests use bounded response bodies and
- share a hard wall-clock wait budget; zero wait retains create-and-return behavior.
- - `/omp <instructions>` → `scripts/run_omp.sh <instructions>` for a bounded headless Oh My Pi
- worker/shortcut under Claude/Codex/Grok (not the interactive main-driver path), run-scoped
- `--profile` and private HOME/XDG isolation, never spell the CLI `opm`, never pass omp product
- `--prewalk` as Elves prewalk. Prefer explicit model pin via `ELVES_OMP_MODEL`. See
- `references/omp-worker.md`. Its Linux boundary omits procfs and has no `/proc` view.
- Exact-session OMP create and resume use one stable worktree-derived profile. Isolated profiles
- do not inherit host OAuth. Auth preflight reads a loopback broker from the environment or
- persistent `auth.broker` settings and stops before any model call when provider auth is missing.
- The slash spellings are Claude Code managed aliases. Codex uses `$elves fugu|manus|grok|devin|omp …`
- or natural language; **never invent top-level Codex slash commands**. These are optional paid
- provider routes, not the native default, and never grant merge, protected-ref, secret, or
- approval-bypass authority. Full transport, timeout, auth-name, and follow-link contracts:
- `references/provider-shortcuts.md`.
- ## Strategic Forgetting
- chats are for execution; handoff docs are for memory. Rewrite live survival-guide sections in place. Archive long execution-log history. Promote only reusable lessons to `learnings.md` and stable truths to `.ai-docs/*`. During long runs, perform **memory and resource hygiene** between batches. Leave a concise reactivation handoff before ending a long finite run. Do not mutate app databases mid-run.
- ## Code Quality Philosophy
- 1. Root cause over band-aids
- 2. Centralize over duplicate
- 3. Extend over create
- 4. Architecture first
- 5. Proactive pattern detection
- 6. Progressive repo conditioning
- 7. No unjustified hardcoded constants
- 8. Runaway detection (5+ fruitless edits → stop and reframe)
- 9. Favor boring technology
- 10. **Anti-accretion:** no new repo meta-tooling, coined terms, or config keys without an explicit
- plan acceptance criterion that names the user-visible overnight-run value. Prefer deleting or
- quarantining unused surface over adding process around it.
- Reviewers: the current codebase is source of truth, not training data. Pass today's date to review
- subagents.
- ## Coordinator-to-Implementer Handoff Standard
- Before every worker turn (one packet for a trusted full-run), write a stand-alone packet:
- 1. intent / why
- 2. non-obvious rationale
- 3. Build On targets
- 4. owned surfaces
- 5. forbidden surfaces
- 6. acceptance evidence
- 7. failure modes / pitfalls
- 8. HEAD / run-doc paths / route-session identity / output format
- Incomplete handoffs are blocking coordinator defects. Canonical run docs stay host-owned.
- **Commit cadence and phase roles.** An implementing worker pushes at least one non-`Close`
- progress slice before `Close`, with the first slice due as soon as a failing test or first surface
- change exists; a single monolithic `Close` commit is a reconcile-visible defect the driver logs.
- Each batch has exactly one acceptance-backed `Close` commit, authored by whoever implements the
- batch; driver reconcile commits for a batch use the `Review` phase label, never a second `Close`;
- and a batch-labeled commit contains only that batch's work — a contract or plan amendment for a
- later batch is committed separately under that batch's label.
- **Worker failure recovery.** Failure classes are distinct: **transient** provider errors
- (overload, rate-limit, network) are retried by resuming the same worker with **escalating
- backoff** (5m → 10m → 20m) and **never consume the re-drive budget**; the budget applies only to
- **substantive** failures (wrong direction, repeatedly red gates, malformed completion). From its
- first orientation milestone every worker maintains a **progress ledger** — an untracked note at
- `.elves/runtime/worker-progress-<batch>.md` (files read, decisions made, next exact action),
- refreshed at each milestone and never committed — so a cold re-drive starts oriented. Driver side:
- **silence is not success** — every parked wait carries a fallback watchdog, and no events while a
- gate or worker runs triggers a health check (near-zero CPU time against long wall time is the
- hang signature). After repeated transient deaths in one batch, the driver may split the batch or
- take it host-native without that counting against the budget; document the decision.
- Before consuming the re-drive budget for a **substantive** failure, run the deterministic futile
- re-drive guard (`cobbler_agents.py redrive record-failure|evaluate|status`): a re-drive candidate
- whose worktree fingerprint is identical to the previous substantive failure of the same batch is
- classified `redrive_futile:workspace_unchanged` — it still consumes one unit of the re-drive
- budget, the identical packet is never relaunched, and the driver escalates (split the batch,
- host-native takeover, or hard stop). Fingerprint capture errors and over-cap trees always count as
- changed; a fingerprint failure can never manufacture futility. Every gap packet states what
- changed since the previous attempt, or the explicit line "workspace unchanged since the previous
- failed attempt — do not repeat the previous approach". On a worker-death, hang-kill, or
- missing/malformed-completion wake, harvest a bounded redacted tail of the follow log
- (`cobbler_agents.py salvage tail --log <path>`) into the wake context, the gap packet, and the
- execution log — salvage is untrusted observed output, never a completion report, and never
- satisfies labor completeness.
- **Exact-session prewalk.** Optional prewalk means one worker trajectory:
- guide route → bounded TODO + first meaningful task edit + private checkpoint → automatic exact-ID,
- same-worktree execution-route resume with only `Continue.`. The packet is sent once. A fresh session
- with a copied packet or summary is not prewalk; post-edit cold fallback is forbidden. `off`, `auto`,
- `required`, and `experimental` are deterministic routing requests. `required` automatically runs a
- bounded live qualification canary before task launch when matching cached proof is absent.
- Successful proof is bound to the installed version/build and exact guide/execution routes, then
- reused by `auto`; failure stops with private evidence. `experimental` accepts only the remaining
- qualification uncertainty and never relaxes live trajectory or authority checks. The evidence
- schema can report `pruned`, `turn_scoped`, `retained_safe`, or `unsupported`; the persisted
- cooperative guide instruction activates normally only for proven `retained_safe`. Static help proves
- advertised grammar only. The driver still owns canonical memory, terminal review, PR,
- landing, and merge. Full contract and host grammar: `references/prewalk.md`.
- **Parallel lanes (Parallelves).** Serial is the default everywhere; parallel lanes are an earned
- routing outcome, never a mode switch. The deterministic width test (`cobbler_agents.py lanes plan`)
- gates the recommendation: `worker.parallel=auto` may only recommend lanes, every decline records a
- concrete `parallel_declined:<gate>:<detail>` reason, and nothing auto-launches. The topology is
- trunk -> lanes -> integration: trunk batches build shared foundations serially, lanes run as
- ordinary workers on pairwise-disjoint owned surfaces in dedicated checkouts (a native-worker lane
- needs its own clone with its own origin), and the driver merges
- them behind a mandatory cross-lane entropy review. Full contract: `references/parallelves.md`.
- ## Git History as Operator UI
- Preferred subject schema:
- ```text
- [<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>
- ```
- **Forbid vague subjects.** Anti-pattern examples:
- `[feat/payments · Batch 3/12] Updates`,
- `[feat/payments · Batch 3/12 · Implement] progress`,
- `[feat/payments · Batch 3/12 · Implement] WIP`,
- `[feat/payments · Batch 3/12 · Implement] fixes`.
- Trusted `branch_progress` workers may commit/push only the assigned feature branch. Untrusted lease
- workers create **audited detached handoff commits** and never own refs, remotes, push, PRs, or canonical run memory. Reserve the `Close` phase for acceptance-backed batch completion.
- **Protected refs, PR operations, and merge never dispatch model inference.**
- Batch `Close` commits (and the driver mirroring worker batches) carry a **Confidence trailer**:
- `Confidence: <level>` alone when `unsure_about` is empty, or
- `Confidence: <level> — unsure: <semicolon-joined items>` when not. An empty unsure list is a valid,
- complete answer — a positive assertion, never a lazy default; the trailer is review triage only,
- never authority. Example:
- `Confidence: medium — unsure: retry backoff bounds in queue.py; whether the legacy CSV importer still hits the new validator`.
- ## Effort Standard
- Do not be lazy. Work as hard as you can for the full run on **plan acceptance and blockers**. Same
- drive on the last product batch as the first. Prefer deeper progress on the planned path over the
- minimum acceptable change.
- Hard work does **not** mean mid-run nit perfection, nested full reviews, or re-running a large full
- suite between ordinary batches. Correctness on the impact path is non-negotiable; polish and
- full-suite attestation belong at terminal readiness (deferred hygiene).
- ## Out-of-Scope Findings
- A run notices things the plan does not cover. There are three destinations, and only one is right
- for work outside the plan:
- | What was noticed | Destination | Settled |
- | --- | --- | --- |
- | In-scope nit, polish, full-suite attestation | deferred hygiene | terminal readiness, this run |
- | Adjacent bug, test or doc, time remaining | Scout Mode | this run, as a commit |
- | Worth doing, outside the plan | **GitHub issue** | a later run |
- Out of scope means the plan does not cover it and widening a batch to include it would change what
- the user accepted. Do not fix it, do not widen the batch, and do not drop it. **File it**:
- ```bash
- gh issue list --search "<keywords>" --state all --limit 5 # never file a duplicate
- gh issue create --title "<imperative and specific>" --body "<body>" --label enhancement
- ```
- The body carries what and where (`file:line`), why it matters, why it was out of scope for this
- run, and the branch or PR that found it. Never a secret value: cite the location and the credential
- type, and recommend rotation.
- Record every issue URL in the execution log and list them in the terminal report, so the run names
- what it deferred instead of leaving it in a transcript nobody re-reads. Without `gh` or without a
- repository, write the same entries to the run notes and say so in the report.
- A run that files more than a handful is describing a different project than the one it was asked to
- build. Say that in the report rather than filing thirty issues.
- ## Run Mode
- Persist under `## Run Control`. **Finite** (default) ends at completion. **Open-ended** continues
- until explicit stop or true blocker — checkpoints are not completion.
- ### Open-ended rules
- After every checkpoint, continue. Final Completion is disabled unless the user stops you. A final
- response is forbidden while Stop Gate says `Stop allowed right now: no` or
- `continuation_guard.stop_allowed: false`.
- ### Pre-Final Guard
- Before any final response: Did the user ask to stop? What does Run Control say? Does the Stop Gate
- allow stopping? Is work remaining? Audit the current state against every requirement at the
- current HEAD — do not rely on intent, partial progress, or memory of earlier work. If not
- justified, continue.
- ## Discovery
- Use this phase when the goal is open-ended and no task has been named yet: "what should we work on
- next", a structural-debt survey, a UX or security sweep, bug hunting, or backlog generation. When
- the user already named the work, skip straight to Planning.
- Discovery is **read-only on source**. It may run the repository's own read-only checks (type-check,
- lint in check mode, dependency audit, a cheap side-effect-free test run) but writes nothing outside
- `advisor-plans/`. It runs before `staging` and is not a worker state: there is no readiness
- evidence, no landing authority, and nothing to merge. Implementation happens later, through the
- normal batch loop, once the user picks what to build.
- The read-only boundary **overrides open-ended escalation**. Discovery shares its use cases with
- `references/open-ended-guide.md`, and that guide sends a saturated run into Scout Mode, which
- commits code. That escalation does not apply here. When findings saturate during Discovery,
- broaden the survey or file issues; do not enter Scout Mode, fix adjacent bugs, or modify source
- until the user selects work.
- Method lives in `references/audit-playbook.md`: nine categories with what to look for in each, and
- a depth rule that scales the pass to repository size. Two contracts from that reference are
- binding:
- - **Evidence.** A finding cites `file:line` and a concrete effect. "Probably has N+1 queries
- somewhere" is not a finding; `orders/api.ts:142 issues one query per order item inside a loop`
- is. Never reproduce a secret value; cite the location and credential type, and recommend rotation.
- - **Leverage.** Rank by impact divided by effort, discounted by confidence and by how risky the fix
- is. "Not worth doing" is a valid verdict and is recorded with one line of reasoning, so the
- maintainer knows it was considered.
- Selected findings become self-contained executor plans in `advisor-plans/`, one per finding, using
- `references/finding-plan-template.md`. Each plan assumes an executor with zero context: it has not
- seen this session, the survey, or the other plans. A plan that says "the pattern discussed above"
- is broken. That template is per-finding and is distinct from `references/plan-template.md`, which
- shapes a batched run.
- Findings the user does not select are filed with `gh issue create` rather than carried in memory or
- fixed opportunistically, in the shape and with the guards described under **Out-of-Scope
- Findings**. Discovery differs only in volume: a survey is expected to produce several issues, where
- an ordinary run should produce few.
- ## Planning
- Interactive by default; autonomous expansion of brief prompts is allowed with user approval before
- execution. Required: plan, survival guide, learnings, execution log, active branch.
- Plans express **intent, acceptance, risk, caution, affected surfaces, constitution impacts, focused
- tests, review focus, dependencies**, and optional checkpoints — **without implementation
- choreography**. See `references/plan-template.md`.
- ## Driver and helper teams
- Use one driver with bounded helpers for a shared task, independent proposals then
- critique for brainstorming, and separate writer lanes for implementation. Canonical
- commands and gates: `references/agent-teams.md`. The `team` and `team-lanes` CLI
- commands work on every supported host. Saved role choices use existing preferences.
- Stage exact driver and helper identities. Record all substantive contributors.
- The independent landing reviewer must be outside that set. A fresh same family
- reviewer is valid. Use the qualified Agy plan mode and Boost harness when selected.
- Review routing and final readiness enforce contributor exclusion and exact commit
- evidence. Worker reports cannot rewrite the driver ledger or callback configuration.
- Lantern callbacks are optional. Pull reports at named driver checkpoints. Never
- prompt a working or parked seat. Keep the one packet prewalk transition. Persist
- report results before acknowledgement and reconcile ambiguous effects before retry.
- Only the driver integrates lane results or performs authorized landing.
- ## Staging
- Launch only when: plan cleaned, run docs current, branch/PR recorded (or the supported pending
- draft checkpoint below is recorded), preflight green, acceptance
- contract reconciled, run mode/non-negotiables recorded, no unresolved planning blockers. In single-
- kickoff E2E, continue immediately once launch-ready.
- For an authorized implementation run, the driver opens or reuses the draft
- implementation PR at the first useful pushed commit, preferably a staging
- commit, before bulk execution. Do not wait for implementation to finish.
- The driver owns PR creation and bot requests; workers keep their existing
- feature-branch commit and push authority. Read-only audits and issue harvests
- do not create PRs. Check the configured bot trigger and draft support. Use a
- documented review request only when permitted. If draft review is unavailable,
- record that limit and keep the incomplete PR in draft. Never mark it ready
- only to start a bot. See `references/review-subagent.md` for early review rules.
- If staging has no useful diff, record PR creation as pending and arrange a
- safe worker checkpoint at its first useful push only when the installed route
- supports it and all staging gates permit it. Otherwise prepare a useful staging
- diff and open the draft before launch. The driver creates a pending draft
- there before bulk work resumes. Do not wait for the whole worker run or send
- prompts into a working or parked seat. Confirm a bot review, bot-owned check,
- or queued bot job; unrelated CI is not proof that bot review started.
- Record the PR URL/number, base branch, and exact current head. After resume,
- look up the existing PR by repository and branch before creating another.
- The checkpoint uses the original worker packet. It must not change the exact
- prewalk session transition or add a second packet; the transition remains `Continue.`.
- If Run Control `Work driver` ≠ host-native (or the run may be delegated), the standalone
- coordinator→implementer packet is written and its path recorded in Run Control and as
- `worker_packet_path` in `.elves-session.json` — staging is not launch-ready without it. The
- per-batch handoff block in the plan and the consolidated staging packet are not substitutes; see
- `references/schema-and-acceptance.md`. `acceptance_contract.py validate` warns (advisory, never
- blocking) when a delegable session lacks the recorded path. A session may opt into strict explicit
- handoff v1 by declaring top-level `handoff` state and the matching leading Markdown or JSON packet
- capsule; once declared, state/ownership/repository drift is blocking.
- The capsule does not turn a cold handoff into exact-session prewalk.
- ### Preflight
- ```bash
- git remote get-url origin
- git push --dry-run 2>&1 | head -3
- gh auth status 2>&1 | head -3
- python3 "$ELVES_SKILL_ROOT/scripts/acceptance_contract.py" validate \
- --repo-root . --session .elves-session.json
- ```
- **One run owns one branch and one checkout.** Prefer a dedicated worktree when other agents may
- touch the repo (`./scripts/preflight.sh --create-worktree <branch> --base origin/main`; `--dry-run`
- first). The helper prints the branch, worktree path, base ref, and collision tripwire, and does not reuse, delete, or repair existing worktrees. `START_TIP` is the collision tripwire.
- A parallel native-worker lane needs its own clone with its own origin; a second worktree shares refs, and launching another native worker there is refused with `native_worker_shared_refs_active_run` — see `references/parallelves.md` for the operator recipe.
- ## Trusted full-run path (normal happy path)
- 1. Stage once.
- 2. One packet; launch trusted worker (`branch_progress`).
- 3. **Park.** Follow sanitized stream by default (`full-run-await`; `--quiet` opt-out). No model
- inference; no timed chat updates. See `references/follow-mode.md`.
- 4. Worker commits/pushes meaningful progress slices with concrete subjects.
- 5. Native Grok goal mode only when capability-proven; otherwise record honest one-packet fallback.
- 6. Wake on death, hangs, malformed completion, safety, blockers, material scope/assumption change,
- checkpoint, user input, or exit. Pushed progress survives recovery from the verified tip.
- 7. Reconcile once. One cumulative terminal review. Consolidate blockers. Revise. Delta re-review.
- 8. Attest readiness at exact HEAD. Terminal: landable PR, or merge only if authorized at that HEAD.
- Host-native and legacy bounded routes still run the full per-batch loop below. Healthy trusted
- full-runs do **not** do per-batch driver review.
- ## Core Loop (host-native / legacy bounded / worker-internal quality)
- ### 1. Orient
- Survival guide → `.elves-session.json` → learnings → plan → execution log → `.ai-docs/manifest.md`
- → constitution → TODO.
- ### 2. Verify Green
- Run gates; capture test baseline. Fix breaks before new work.
- ### 3. Rollback Ref
- Host-owned `refs/elves/rollback/<run-id>/<session-id>/bN-…` (or single `b0` for trusted full-run).
- ### 4. Contract
- Behaviors, Build on, acceptance criteria, blast radius. Stable IDs `B#-A#` / `[B#-A#]`.
- ### 5. Implement
- Pre-implementation survey. Extend existing utilities. Write tests. Commit with progress subjects.
- ### 6. Validate
- Impact path: changed surface → affected consumer → selected test. Touched-surface proof by default;
- broad at high-risk checkpoints and **terminal** (full suite or project full gate). Do not re-run a
- large full suite between ordinary batches when the impact path is green. Bug-fix protocol for
- blockers: category → category test → fix all. Queue pure advisories under **Deferred hygiene**
- (survival guide + execution-log digest); drain at terminal. Details:
- `references/validation-guide.md`.
- ### 7. Review
- Mid-run: contract walk for this batch; no nested full product re-review of settled work. Terminal:
- one cumulative review only.
- Reviewers read worker confidence trailers/report fields **first** and allocate attention
- accordingly: flagged `unsure_about` areas get a deeper pass. The signal is triage, never
- authority — it does not skip gates or waive review in either direction. A successful trusted
- full-run terminal monitor/await returns `review_context.review_prompt_block`; the coordinator
- attaches that machine-produced block verbatim to Final Readiness. For native Claude Code and Codex
- workers, build the same triage table from every `Confidence:` trailer in the cumulative commit
- history. The reviewer must return a **Confidence-Guided Review** section that names the deeper
- passes performed, or explicitly records that signals were partial/absent and baseline review was
- used. Claude Code and Codex use this identical contract.
- Independent feedback. Walk contract. Enforce code quality. Medium/high blast radius: regression
- pass. Fix blocking; advisory does not delay readiness (bank mid-run advisories as deferred hygiene).
- Resolve PR threads. **PENDING-DOCS** is not clean. **Public API surface snapshots are optional regression evidence.** Use existing structured sources before inventing scanners. If no credible source exists, record `unavailable` with the reason instead of fabricating a snapshot. A missing snapshot source is not blocking unless `required: true` was explicitly set in the survival guide. `required: true` is valid only when explicitly set by the user or project survival guide. Do not infer required mode from project type, provider config, framework choice, or the presence of API files. Snapshot artifacts are run artifacts, not product docs. Temporary snapshot artifacts should not remain in final product PR diffs unless the user explicitly asks. Record shapes and field names, not secrets, bearer tokens, cookies, customer payloads, or production sample data. A snapshot proves public surface shape only; it is not a substitute for tests, E2E checks, review, or the human-owned constitution. Record the public API surface delta when configured.
- ### 8. Legality Check
- If a constitution exists: PASS / WARN / FAIL / UNCHANGED per intention. FAIL blocks.
- ### 9–12. Document, survival guide, commit/push, re-read
- After every host-owned commit and push, re-read the survival guide before doing anything else.
- Do not wait for user acknowledgment.
- ### 13. PR Loop
- Outside parked full-run: nonblocking new/unresolved poll after host pushes. Terminal readiness waits
- for required checks/reviewers. Trusted parked worker pushes defer host PR polling until wake.
- Open the draft before parking for bulk execution. Bot feedback enters driver review at the next
- safe checkpoint, wake, or terminal reconciliation. Routine comments do not
- interrupt a healthy worker. Early bot review never replaces final independent
- review of the cumulative diff at the exact head.
- ### 14–15. Drift check when evidence warrants; continue or stop
- ## Scout Mode
- After planned batches, with time remaining: adjacent bugs, tests, docs. Commit format:
- `[<branch> · Scout] <verb> <what changed>`.
- ## Forbidden Commands
- Never: `git reset --hard`, `git checkout .`, `git clean -fd`, force push, rebase on shared branches,
- `rm -rf` outside scope, operating on another agent's checkout. Stop on unexpected tip moves
- (collision) outside the exact registered trusted full-run exception.
- ## Merge Conflicts
- Rule out collision first. Otherwise fetch and merge (no rebase). Complex conflicts → Hard Stop.
- ## Test Integrity
- Never weaken, delete, or skip a test merely to obtain green. Legitimate behavior-driven updates
- with preserved/improved coverage and evidence are allowed.
- ## Compaction Recovery
- 1. Survival guide (Stop Gate + Run Control first)
- 2. `.elves-session.json` / `continuation_guard`
- 3. Learnings → plan → execution log → `.ai-docs` → constitution
- 4. Resume the single next required action immediately
- ## Completion Contract
- Landable is **plan Acceptance with proof** — not green CI + `status: complete`.
- Before batch `status: complete`: **impact** gates green for this batch (not necessarily full-suite
- mid-run), regression attestation on the impact path, non-empty
- `acceptance: [{id, criterion, met, evidence}]`, PR feedback triaged for blockers, legality clean for
- FAIL, docs current for owned surfaces, deferred hygiene updated, session JSON updated, commit
- pushed. **God-file rule:** structure locks alone do not complete a split batch unless plan
- Acceptance allows characterization-only. Prefer **one batch per close commit**. Terminal readiness
- still requires full suite (or project full gate) and drained deferred hygiene.
- Landing check (installed):
- ```bash
- python3 "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py" \
- --session <session-path> --repo-root .
- ```
- Session `plan_path` is authoritative; explicit `--plan` is only an equality assertion. An installed
- Elves bundle never requires a repo-only helper.
- A repository may track `.elves/landing-profile.json` for bounded declarative project-specific
- checks. Schema v1 accepts path co-change checks and post-merge declarations but rejects executable
- checks. A missing profile is neutral; a present invalid or blocking-failed profile blocks
- readiness. The host recomputes live results and binds exact profile bytes, HEAD, resolved base and
- merge base, and normalized outcomes to a host-owned digest; worker reports cannot override them.
- Profiles never grant merge, tag, release, protected-ref, connector, secret, or posting authority.
- Hosts may record observations, synthesize candidates, and explicitly promote checks, or waive one
- blocking check at the exact HEAD; learning state is gitignored runtime data and never auto-promotes.
- See `references/project-landing-profiles.md`.
- ## Constitution and the Legality Check
- Correctness (gates) ≠ plan compliance (review) ≠ legality (judge). The human owns constitutional
- intentions. Agent drafts; human owns.
- ## Proof and convergent review (v2.3)
- See `references/proof-and-review.md`.
- - Impact-selected verification; evidence inputs + invalidation scope for reuse
- - Mid-run impact path only; terminal full suite + deferred hygiene drain
- - One cumulative review: completeness, constitution, declared risks, concrete regressions
- - Consolidate blockers before revision; advisory does not delay readiness
- - Re-review = revision delta + unresolved blockers only
- - New blockers need serious regression / acceptance or constitution breach / security / data
- integrity / revision-introduced failure
- - Cleanup-only operational changes do not invalidate product proof
- - Stop on sufficient exact-tip evidence, not absence of reviewer suggestions
- ## Readiness Gate
- Branch-level: execution log current, local proof green on current tip, project landing checks green
- at the current tip when a profile is present, preview/artifact proof when applicable, plan
- Acceptance with proof, landing check clean, final cumulative review clean, PR
- comments/checks polled, legality clean, strategic forgetting done, git clean.
- Complete-without-merge and complete-and-merge share **one** readiness pipeline.
- ## Elves Report
- For substantial finite runs, generate static HTML before handoff covering **problems found**,
- **lessons learned**, batch timeline, verification proof, residual risks, and human next steps.
- Default path: `/tmp/elves-report-<repo-slug>-<yyyy-mm-dd>.html`. Use collapsible `<details>` sections for batch timelines. Keep committed examples and reusable templates non-identifying.
- Surface the **Elves Report path** in the final notification. No external assets/scripts. See
- `references/elves-report-template.html`.
- ## Final Completion
- Finite mode only. Acceptance-bearing Final Readiness Review **before** operational-artifact
- cleanup. The strict landing check runs on committed session evidence even when the target repository
- ignores `.elves-session.json`; see `references/schema-and-acceptance.md` for the force-add and
- cleanup sequence. Independent review subagent when available. Then remove survival guide / execution
- log / `.elves-session.json` from the PR (keep plan by default; keep learnings). Post-cleanup tip
- attestation. Notify with report path. Merge only if authorized — regular merge commit only.
- After an authorized merge, tear down the run's own recorded worktree (`worktree_path`):
- `./scripts/preflight.sh --gc-worktrees --path <worktree_path>`, report first, then `--apply`;
- the `cleanup.worktrees` preference in `config.json.example` records whether teardown runs
- on merge, stays report-only, or never runs.
- ## Staying Unattended
- Never block on prompts. Non-interactive flags. Document decisions. Gates and helper subprocesses
- run with closed stdin and explicit timeouts — a silent hang is a failure, not progress. See
- `references/autonomy-guide.md`.
- ## Ride-Along Protocol
- Messages prefixed `[ride-along]`, `ride-along:`, or `ra:`: handle in 1–3 sentences and continue.
- Explicit **stop** still halts.
- ## Hard Stops
- Genuine blocker; merge requested without authorization; destructive action listed as non-negotiable;
- collision on branch tip. Everything else: judgment + Decisions made.
- ## Structured Session Data
- `.elves-session.json` holds `batches` with per-id acceptance evidence, `master_acceptance`,
- `continuation_guard`, optional `cobbler` session state, `model_routes`, `review_comments`. After
- compaction, trust this file for status. When staging creates a dedicated worktree, record its
- path as `worktree_path` alongside `run_id` so post-merge teardown can tell the run's own
- worktree from operator-created ones (the schema tolerates extra keys).
- ## Persistent Preferences
- Safe worker convenience is shared by both hosts at
- `${XDG_CONFIG_HOME:-~/.config}/elves/config.json`. Use `cobbler_agents.py preferences
- show|set|reset`; writes are private and atomic. Repository safety vetoes outrank everything;
- convenience precedence is explicit run intent, repository defaults, global preferences, then
- built-ins. Credentials or merge/destructive/protected-ref/approval-bypass authority are rejected.
- `config.json` when present also carries legacy batch sizing, notifications, review method,
- default branch, and cleanup.
- Cobbler under top-level `cobbler` (wins over legacy `council`). See `config.json.example`.
- ## Skill Memory
- Learnings and `.ai-docs` outlive a single run. Keep them curated. Id-tagged learnings
- (`- [L3] …`) are managed by the learnings ledger
- (`cobbler_agents.py learnings validate|apply|rollback|digest|migrate`): creates require an
- evidence pointer (execution-log entry or commit) and may record an `(expect: …)` validation
- note; retire moves entries under Retired Learnings (creating that section at EOF when missing),
- never deletes; every applied edit appends before/after to the tracked `learnings-history.jsonl`
- sidecar with inverse-edit rollback (**one history row per edit** — one `rollback` undoes only
- the latest row; repeat to walk further); the file is written before history so a crash cannot
- invent phantom applied edits; and the bounded `## Digest` block is read first at orient, pulling
- full entries on demand. Freehand dated learnings stay fully valid; `migrate` is explicit and
- idempotent; the ledger never reflows, reorders, or rewrites content it did not edit.
- ## v2.24 run tools (host-neutral)
- The five v2.24 helpers — futile re-drive guard (`redrive`), learnings ledger (`learnings`),
- observed-usage ledger (`usage`), salvage previews (`salvage`), and the continuity watchdog
- manager (`continuity`) — are **host-neutral CLI helpers** with identical semantics on Claude
- Code, Codex, Grok Build, and Oh My Pi. Invoke as
- `python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" <verb> …` from any host; do **not** invent
- per-host slash surfaces for them. They are advisory instruments (never landing, merge,
- credential, or routing authority). Continuity only writes OS timer templates — Elves never
- activates them. Usage is filled only by `usage aggregate --records-file`; close and reconcile
- do not write `usage_observed`. Usage ceilings are checkpoints, never stops. See the guide's "v2.24 run tools"
- section, `references/host-parity.md`, and `AGENTS.md` (Codex adapter pointer).
- `review-route` joins them as a host-neutral helper on the same CLI surface and the same honesty
- boundary: it selects an available review route and records requested route, actual route, and
- fallback reason. It never claims a review ran and never carries landing, merge, or credential
- authority.
- ## v2.22 runtime helpers (planning harvest, compact output, lanes)
- - **Any-model worker pin:** `resolve_user_specified_worker_model` + handoff cache keys
- (`scripts/cobbler_runtime/worker_routing.py`; `references/adaptive-worker-routing.md`).
- - **Planning harvest:** `scripts/cobbler_runtime/planning_harvest.py` (beacons, discovery, modes,
- lean summary, task sandbox, canvas, mission prep, goal assessor, review filter, merge-recovery lock).
- - **Tool output compact:** `scripts/cobbler_runtime/tool_output_compact.py`.
- - **Parallelves:** `validate_lane_staging` + `LaneSupervisor` in `parallel_lanes.py`.
- - **Fugu module:** `scripts/cobbler_runtime/fugu.py` (shim `run_fugu.sh`).
- ## Optional surfaces (outside normal critical path)
- Reports, notifications, provider routes, media generation, legacy bounded execution, and untrusted
- lanes remain useful but are not the default happy path.
- ## Host parity
- Claude Code, Codex, Grok Build, and Oh My Pi (omp) provide the same workflow and prewalk safety contract.
- Exact-session prewalk preserves the same qualification, trajectory, checkpoint, visibility,
- fallback, and authority semantics on every host; supervised transport syntax may differ.
- The v2.24 run tools (`redrive`, `learnings`, `usage`, `salvage`, `continuity`, `review-route`) share one CLI
- surface and one honesty boundary on every host — see **v2.24 run tools (host-neutral)** above
- and `references/host-parity.md`.
- **Codex Goals** are optional continuation plumbing — distinct from **Grok Build goal mode**.
- ## Compatibility notes
- - Missing optional provider access never blocks a native run.
- - Record `implementation_lane: fast | untrusted` when using external work drivers.
- - Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp). Required prewalk qualifies the
- installed transport automatically; experimental prewalk is explicit and still fail-closed during
- the real trajectory. Grok as an optional worker under Claude/Codex remains consent-gated.
- - Compatibility: `$elves setup-council` remains supported.
README.md · README · 745 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Elves
- 
- Elves is an open-source Agent Skill for handing planned development or research work to a separate
- worker without locking the run to one model provider. The capable Claude Code, Codex, Grok Build, or
- Oh My Pi (omp) driver plans and reviews; a subscription-native (or optional external) worker
- implements; durable run files let the work survive context compaction. You write the plan and own
- the merge decision. The agent does the middle.
- **Current release: v2.40.0**. See [`CHANGELOG.md`](CHANGELOG.md) for version history. Coined terms
- are defined once in [`references/glossary.md`](references/glossary.md).
- Implementation runs get a draft PR at the first useful pushed commit,
- preferably during staging, before bulk execution. The driver opens or reuses
- it and checks whether configured bots review drafts. It uses a permitted
- documented bot request when needed. If draft review is unavailable, it records
- that limit and keeps unfinished work in draft. Bot feedback enters driver
- review at safe boundaries. Final independent review still applies. Workers
- do not gain PR authority. Read-only audits and harvests do not open PRs.
- If staging has no useful diff, a planned worker checkpoint gives the driver
- control at the first useful push when the installed route and staging gates
- permit it. Otherwise useful staging changes must supply the draft before launch.
- The driver opens the draft before bulk
- work continues. It checks for the bot's own review, check, or queued job.
- **New to Elves?** Use the [practical user guide](https://aigorahub.github.io/elves/) — especially
- **[Paste this to your agent](https://aigorahub.github.io/elves/#agent-onboarding)** at the top.
- That copy-ready block installs Elves for Claude Code, Codex, Grok Build, and/or Oh My Pi (omp)
- (whichever is available) and orients you. The guide also covers the first run, worker choice, live
- progress, review, and landing. This README is the repository reference: shell install, safety
- model, operations, and an index into the detailed contracts under [`references/`](references/).
- **Supported main drivers:** Claude Code, Codex, Grok Build, and Oh My Pi (omp). All four are first-class hosts:
- native skill install, doctor validation, automatic required-mode prewalk qualification, and
- explicit experimental prewalk. Grok Build is also an optional *worker* under Claude/Codex when
- permitted. Oh My Pi is also a main driver (`omp` → `~/.omp/agent/skills/elves`) and an optional
- worker under other hosts. Managed install targets: `claude`, `codex`, `grok`, `omp`.
- See the guide FAQ
- [I opened Grok Build and tried /elves](https://aigorahub.github.io/elves/#troubleshooting).
- ---
- ## Quick start
- Prefer the agent paste in the guide if you already have a supported host open. Otherwise use the
- shell one-liners below (Python 3.10+). First-time install needs an explicit host target; `--target
- all` only updates hosts that already have an Elves skill root.
- ### Windows through WSL2
- Elves supports Windows through [WSL2](https://learn.microsoft.com/windows/wsl/install). Native
- Win32 execution is not supported. Open PowerShell and check the installed distributions:
- ```powershell
- wsl --status
- wsl --list --verbose
- ```
- If no distribution is installed, install Ubuntu. If Ubuntu shows version 1, convert it to WSL2:
- ```powershell
- wsl --install -d Ubuntu
- wsl --set-version Ubuntu 2
- wsl -d Ubuntu
- ```
- Docker Desktop's internal WSL distributions do not count as an Elves host. The install doctor
- ignores them when it selects a distribution. It reports `wsl_probe_failed` instead of claiming
- that no distribution exists when either WSL query fails. Run `wsl --status` and
- `wsl --list --verbose` to correct that failure before you retry.
- Run the remaining commands inside Ubuntu. Install the Linux prerequisites. Then install Claude
- Code, Codex, Grok Build, or Oh My Pi inside the same WSL2 distribution and confirm that its command
- is on the Linux `PATH`.
- ```bash
- sudo apt update
- sudo apt install -y git python3 bubblewrap
- # Set this to claude, codex, grok, or omp for the host installed inside WSL2.
- ELVES_TARGET=codex
- ELVES_TMP="$(mktemp -d)"
- git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
- python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target "$ELVES_TARGET"
- case "$ELVES_TARGET" in
- claude) ELVES_ROOT="$HOME/.claude/skills/elves" ;;
- codex) ELVES_ROOT="$HOME/.codex/skills/elves" ;;
- grok) ELVES_ROOT="$HOME/.grok/skills/elves" ;;
- omp) ELVES_ROOT="$HOME/.omp/agent/skills/elves" ;;
- esac
- python3 "$ELVES_ROOT/scripts/install_doctor.py" --doctor
- rm -rf "$ELVES_TMP"
- ```
- Fugu, Grok, and OMP local shortcuts require a qualified `/usr/bin/bwrap` probe. Manus and Devin
- perform remote work, but their Bash runners must still start inside WSL2. The doctor reports local
- shortcut sandbox readiness separately from external council process-boundary readiness.
- ### Install (Claude Code)
- ```bash
- ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target claude && rm -rf "$ELVES_TMP"
- ```
- This installs `~/.claude/skills/elves/` plus eleven managed alias skills (`/cobbler`,
- `/cobbler-mode`, `/council`, `/ec`, `/elves-council`, `/setup-cobbler`, `/setup-council`, `/fugu`,
- `/manus`, `/grok`, `/devin`, `/omp`). The sync
- helper creates missing aliases and updates only aliases carrying the Elves-managed marker. If it
- finds a user-owned alias, it reports the conflict before changing the install and never
- overwrites that alias.
- ### Install (Codex)
- ```bash
- ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target codex && rm -rf "$ELVES_TMP"
- ```
- Codex installs the main skill bundle only — no slash aliases. Use `$elves cobbler: <task>` or
- natural language such as "Ask the Cobbler…".
- Codex users should not need or expect a top-level `/cobbler` command. Do not invent top-level /cobbler.
- ### Install (Grok Build)
- ```bash
- ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target grok && rm -rf "$ELVES_TMP"
- ```
- This installs `~/.grok/skills/elves/` for native Grok Build discovery (first-class host, same
- workflow contract as Claude and Codex). No Claude-style slash aliases. Invoke Elves via Grok Build
- skill discovery or natural language.
- ### Install (Oh My Pi)
- ```bash
- ELVES_TMP="$(mktemp -d)" && git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves" && python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target omp && rm -rf "$ELVES_TMP"
- ```
- This installs `~/.omp/agent/skills/elves/` for native Oh My Pi discovery (first-class host, same
- workflow contract as Claude, Codex, and Grok Build). No Claude-style slash aliases. Invoke Elves
- via omp skill load or natural language. Elves prewalk is not omp product `--prewalk`. OMP prewalk
- accepts `xhigh` and `max` and passes those levels unchanged to `omp --thinking`.
- ### Optional provider shortcuts
- Focused provider tasks do not require a full Elves run. The contracts below
- are unchanged; this section is the readable index. Full requirements, auth
- environment names, timeouts, and follow behavior live in
- [`references/provider-shortcuts.md`](references/provider-shortcuts.md).
- #### Commands
- Claude Code:
- - `/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`
- - `/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`
- - `/manus <topic>`
- - `/grok <instructions>`
- - `/devin <instructions>`
- - `/omp <instructions>`
- Codex uses the equivalent `$elves fugu|manus|grok|devin|omp …` forms or natural language.
- #### Fugu
- Plain Fugu supports planning and analysis. `fugu review` keeps the read-only P0-P3 review
- contract. Both receive a bounded snapshot of policy-admitted tracked and non-ignored untracked
- files. Fugu is limited to planning and read-only review. The runner rejects `--write`.
- Profiles:
- - regular `fugu/high` (default)
- - `--deep` → `fugu/xhigh`
- - `--cyber` → `fugu-cyber/xhigh`
- - `--ultra` → `fugu-ultra-v2.0/high` when listed, then `fugu-ultra`, then `fugu-ultra-v1.1`
- - `--max` → `fugu-ultra-v1.1/max` for one narrow high-stakes gate on a 60-minute default wall budget. This is effort `max`, not the Fugu Max model `fugu-max`.
- Plain regular Fugu is the default. The host may select Cyber only for explicit security review or threat-model intent after a successful Cyber call in the current session. Only a user-explicit Cyber request may establish that proof. Otherwise, it uses regular Fugu. The user must explicitly select Ultra or Max.
- `--include` records an exact host-selected path but cannot override exclusions for ignored
- trees, credentials, operational state, executable agent configuration, unsafe links/file types, or
- repository escapes; the exact path must actually be admitted and copied, and gitignored includes
- fail closed before the provider launches (use `--preflight` to check). Both `.env.*` and
- `*.env` dotenv-name families plus host-owned internal namespaces are always excluded. macOS read-only cleanup is best-effort,
- not proof of recursive descendant absence.
- Use `--max-wait` before automatic `--deep`; if any `--include`, run `--preflight` first; prefer
- redirect to a log (never `| tail`).
- **Host Fugu routing:** when the user says “use Fugu” without an explicit
- profile flag, the host agent uses plain by default. It may select deep for regular Fugu xhigh work, or Cyber for explicit security intent. It must not select Ultra or Max without an explicit user flag. It chooses planning vs review and optional `--include` paths
- before launch, and states a short `Fugu route: …` line;
- explicit flags always win. The isolation snapshot is always on; the host only adds exact admitted
- context via `--include`. See `references/provider-shortcuts.md`
- (**Host routing when the user says "use Fugu"**) and `references/fugu-calling-guide.md`.
- Regular/deep calls are ephemeral; Ultra and max reserve synthesis time and resume only the
- exact isolated session with further tools forbidden. Session state and raw events never leave the
- lane; events cross a bounded host-owned pipe, final output remains pinned to a no-follow
- descriptor, and every settled phase receives a final descriptor-safe writable-state audit. Codex's documented externally-sandboxed mode avoids an invalid nested macOS sandbox while
- Elves' required outer boundary remains authoritative.
- Fugu's Linux boundary likewise omits procfs around its credential-bearing
- launcher and exposes only a synthetic `/proc/self/exe` symlink to the qualified real Codex
- executable.
- #### Manus, Devin, and Oh My Pi
- Manus supports a normal private
- task plus Cobbler-managed `--wide` and deterministic `--fanout` rosters, explicit `--file`
- attachments, and duplicate-safe `--resume` that retries only known-failed steps; roster manifests
- are validated and exclusively reserved before any upload. A durable pre-create marker prevents
- resume from duplicating a paid Manus task when task-ID persistence was interrupted. Manus requests nest empty connector, enabled-skill, and forced-skill lists under
- `message`, so the wrapper grants no connector or forced-skill IDs explicitly; the documented API
- still loads account-default enabled skills when `enable_skills` is empty, and this route therefore
- does not claim skill isolation.
- Devin creates
- a bounded remote task, including its creation request, without granting stored secrets or knowledge
- by default.
- Oh My Pi (`/omp` / `$elves omp`) runs headless `omp` over the shared isolation
- snapshot with a single provider-matched API key and never modifies the live checkout from the
- shortcut (use parked `omp-cli` full-run for implementation labor).
- #### Grok
- Grok uses
- headless mode at `high` reasoning by default, without approval bypass over a disposable tracked-source snapshot in
- Elves' required outer kernel sandbox, plus Grok's built-in inner `strict` profile, provider-documented
- isolated `dontAsk` settings, and bypass mode locked off. The shortcut requires an explicit
- `XAI_API_KEY`; a dedicated Grok tool shell removes both supported key names before any
- model-directed command runs, and the Linux boundary omits procfs to prevent parent-environment
- inspection. It does not expose a shared OAuth file because Grok applies the same sandbox to
- provider and tool reads.
- The runner builds argv from the flags the installed Grok Build CLI advertises: an absent safety
- flag (isolated `--cwd`, inner `--sandbox strict`, headless `--single`, `--output-format`,
- explicit reasoning effort) fails closed, while a quality flag the installed version dropped is
- simply not passed. Auto-update is disabled through the isolated `[cli] auto_update` config key
- rather than a removed flag. Reasoning effort defaults to `high`; `ELVES_GROK_EFFORT` selects
- `low`, `medium`, `high`, or `xhigh`, and `ELVES_GROK_MODEL` pins a model only when the
- authenticated live catalog lists it. The runner reports the CLI version, effort, model, the
- authentication route the CLI itself names, and any omitted flags.
- On a host that cannot nest sandboxes (macOS Seatbelt refuses a second profile inside Elves'
- required outer `sandbox-exec` boundary), the runner fails closed with
- `grok_inner_sandbox_unavailable` before it builds a snapshot, rather than launching with the
- inner profile silently missing. Elves does not drop the inner profile to make a launch succeed,
- and the outer boundary is not optional; use a Linux host with the bwrap backend or select
- another review route.
- **Review snapshot media policy (all harnesses and hosts).** Read-only review snapshots omit
- oversized binary media instead of failing the whole review. Video, audio, presentation, archive,
- image, font, and 3D binaries above the per-file limit are left out of the snapshot; the 16 MiB
- per-file limit is not raised. The context manifest records each omitted path, byte size, and
- reason, and every runner prints the same omission block. Source, prose instructions, executable
- agent configuration, and explicit `--include` paths still fail closed, with a remediation that asks
- for a derived text, image, or transcript artifact. Writable lanes keep fail-closed behavior.
- **Fugu is optional (review route fallback).** When a review route is unavailable because of quota,
- authentication, catalog, runner, timeout, or provider failure, probe the supported review routes
- and select another available independent reviewer instead of stopping. Preserve an explicit user
- route when it works; otherwise prefer a supported native reviewer when no optional provider works.
- Record requested route, actual route, and fallback reason. Do not claim a review ran when it did
- not, and do not let optional-provider failure block the run while a qualified review route exists.
- Host-neutral helper: `python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host
- <host> --requested <route> --unavailable <route>=<reason>`.
- ### Per-project install
- Clone into `.claude/skills/elves`, `.codex/skills/elves`, `.grok/skills/elves`, or
- `.omp/agent/skills/elves` inside your repo (remove the nested `.git`), or prefer
- `scripts/sync_installed_skills.py` over hand-maintaining a second tree.
- ### Validate the install
- ```bash
- # Claude Code:
- python3 ~/.claude/skills/elves/scripts/install_doctor.py --startup
- # Codex:
- python3 ~/.codex/skills/elves/scripts/install_doctor.py --startup
- # Grok Build:
- python3 ~/.grok/skills/elves/scripts/install_doctor.py --startup
- # Oh My Pi:
- python3 ~/.omp/agent/skills/elves/scripts/install_doctor.py --startup
- ```
- ### Update or uninstall
- ```bash
- # Update every host that already has Elves installed:
- python3 /path/to/elves/scripts/sync_installed_skills.py --apply --target all
- # Or update one host:
- python3 /path/to/elves/scripts/sync_installed_skills.py --apply --target grok
- # Uninstall: remove the skill root you installed (and Claude aliases only if you want them gone):
- rm -rf ~/.claude/skills/elves ~/.codex/skills/elves ~/.grok/skills/elves ~/.omp/agent/skills/elves
- ```
- ### No plan yet? Start with Discovery
- When you do not know what to work on, ask for a survey instead of a run:
- > Do a discovery pass on this repo and tell me what is worth doing.
- Discovery is read-only on source. It sweeps the repository against the nine categories in
- [`references/audit-playbook.md`](references/audit-playbook.md), returns findings ranked by impact
- over effort, and writes nothing outside `advisor-plans/`. Every finding cites `file:line` and a
- concrete effect, so "probably slow somewhere" never reaches you. "Not worth doing" is a recorded
- verdict, not a silent omission.
- Findings you pick become self-contained executor plans in `advisor-plans/`, one per finding, using
- [`references/finding-plan-template.md`](references/finding-plan-template.md). Those plans feed the
- normal run below. Findings you do not pick are filed with `gh issue create` rather than carried in
- anyone's memory.
- ### First run
- Write a plan (start from [`references/plan-template.md`](references/plan-template.md)), then say,
- from your project:
- > Implement docs/plans/my-feature.md as an elves run while I'm offline.
- The driver stages the run (run docs, branch, dedicated worktree when other agents may touch the
- repo, worker packet for delegable runs, preflight), launches the worker, reviews cumulatively,
- and stops at a **landable PR** (chat-to-work). Merging happens only when you say so — an explicit
- in-session authorization (chat-to-land) or the reviewed-landing command `\land-pr` / `/land-pr`.
- See [`references/e2e-chat-to-land.md`](references/e2e-chat-to-land.md) and
- [`references/kickoff-prompt-template.md`](references/kickoff-prompt-template.md).
- For a machine-checked cold handoff, the session may opt into explicit handoff v1: exact state,
- acceptance ownership, branch/HEAD, and a matching bounded Markdown or JSON packet capsule. The
- ordinary v2.8 path remains advisory when this schema is absent. The capsule is not prewalk continuity proof.
- See [`references/schema-and-acceptance.md`](references/schema-and-acceptance.md).
- Projects with deterministic repository-specific landing rituals may track
- `.elves/landing-profile.json`. Its declarative path co-change checks are evaluated at the exact
- HEAD/base/merge-base and bound to a host-owned digest; schema v1 rejects executable checks and
- never launches profile-directed processes. Missing profiles are neutral; profiles can block
- readiness but never grant merge, tag, release, protected-ref, secret, connector, or posting
- authority. Hosts may `observe` landings, `propose` candidates, explicitly `promote` into the tracked
- profile, and apply exact-HEAD `waive` entries — with no auto-promotion. See
- [`references/project-landing-profiles.md`](references/project-landing-profiles.md).
- ---
- ## Who implements
- **Default: a subscription-native worker** on the live host (Claude Code, Codex, Grok Build, or Oh My Pi) in a
- separate exact session — no external provider required. Optional work drivers when configured and
- permitted: trusted Grok Build full-run under Claude/Codex, Devin CLI, or other adapters. Missing
- optional provider access never blocks a native run. Repository `allow_grok=false` is an absolute
- veto. The host owns packets, protected refs, final gates, PR, and merge — always. Details:
- [`references/adaptive-worker-routing.md`](references/adaptive-worker-routing.md),
- [`references/prewalk.md`](references/prewalk.md),
- [`references/grok-open-source-worker.md`](references/grok-open-source-worker.md),
- [`references/grok-implementer-launch-prompt.md`](references/grok-implementer-launch-prompt.md),
- [`references/omp-worker.md`](references/omp-worker.md) (Oh My Pi main driver + optional `omp-cli` / `/omp` worker).
- Parallel implementation lanes are optional and never the default: serial stays the default, and
- `worker.parallel=auto` only recommends lanes when the deterministic width test passes; see
- [`references/parallelves.md`](references/parallelves.md).
- Trusted Grok implementation launches use `--always-approve` alone: Grok Build treats an explicit
- `--permission-mode auto` as an override, so the two flags must not be combined.
- Native delegation names both model and effort, and stays inside one model family. GPT-6 Astra
- `ultra`/`max`/`xhigh` hands off to the same GPT-6 Astra model at `medium`; GPT-5.6
- `xhigh`/extra-high/`ultra` hands off to the same GPT-5.6 model at `medium`; GPT-4.8 Max/UltraCode to
- the same GPT-4.8 model at `medium`; Fable 5.1 `max`/`ultra` to the same Fable 5.1 model at `low`; Opus 5.5
- `max`/`ultracode` to the same Opus 5.5 model at `high`. There is no Fable→Opus route. A Fable driver
- hands off to `claude-fable-5-1` at `low` rather than crossing families. The one cross-family worker is
- the opt-in Grok handoff, which prefers `grok-4.7` at explicit `high` when the live catalog returns
- it, then `grok-4.6`, then `grok-4.5`. Composer 2.5 (`grok-composer-2.5-fast`) is retired and is never selected.
- ### Optional exact-session prewalk
- Prewalk lets one worker orient on a guide model/effort, create a bounded TODO, make
- the first real edit, and then resume the **same session in the same worktree** on the execution
- route. The packet is sent once; the resume input is only `Continue.`. A new worker that receives a
- summary is a normal cold handoff, not prewalk, and cold fallback is forbidden after an edit.
- The safe preference is `worker.prewalk: "auto"`, while the launch CLI defaults to `off` for backward
- compatibility. `auto` makes no qualification model calls and reuses only matching cached proof.
- `required` automatically runs a 180-second, 1 MiB-bounded live canary when proof is absent. The
- task worker starts only after session, worktree, stream, route-change, retained-context, and
- packet-count checks pass; failure stops with a private evidence path. `experimental` explicitly
- accepts qualification uncertainty after static grammar inspection, reports that status, and keeps
- every real-run continuity and authority check. Claude Code, Codex, Grok Build, and Oh My Pi share
- these semantics. Grok single-phase native-worker launch remains registry-gated. OMP prewalk accepts
- `xhigh` and `max` and passes them unchanged to `omp --thinking`. See the
- [normative prewalk contract](references/prewalk.md) and
- [host parity matrix](references/host-parity.md).
- ## Safety model
- **The user owns whether Elves may merge.** The worker never merges; the driver merges only with
- an explicit opt-in recorded in Run Control, and only with a regular merge commit after final
- readiness — never a squash. Readiness (plan Acceptance with proof at the exact HEAD) and merge
- authority are independent; **Landable is plan Acceptance with proof**, not green CI plus
- `status: complete`.
- **Thin safety kernel** (never weakened): exact plan/session/packet acceptance identity;
- credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, and redaction checks; no
- worker merge/tag/protected-ref/PR/landing authority; test integrity; independent terminal review;
- final CI.
- The optional **continuity watchdog** stays outside the kernel's authority surfaces: an
- operator-owned OS timer that Elves never activates itself, detect-and-report by default, and
- every safety decision delegated to `full-run-prepare --resume` — it never resumes a terminal
- run and holds no landing, merge, or credential authority
- (`references/operations-guide.md`).
- **Forbidden commands.** Never: `git reset --hard`, `git checkout .`, `git clean -fd`, force push,
- rebase on shared branches, `rm -rf` outside scope, operating on another agent's checkout.
- **One run owns one branch and one checkout.** Prefer a dedicated worktree when other agents may
- touch the repo (`./scripts/preflight.sh --create-worktree <branch> --base origin/main`;
- `--dry-run` first). The helper prints the branch, worktree path, base ref, and collision tripwire,
- and does not reuse, delete, or repair existing worktrees. `START_TIP` is the collision tripwire:
- any unexplained tip move is a collision and a Hard Stop.
- **Worktree lifecycle.** Staging records the created worktree path in `.elves-session.json`;
- after merge, the run's worktree is reclaimed with the separate gc helper
- (`./scripts/preflight.sh --gc-worktrees`; report by default, `--apply` removes only clean, fully
- merged, fully pushed worktrees; unregistered sibling directories are listed and never deleted).
- Installed skill bundles ship `scripts/worktree_gc.py` with that helper (and
- `scripts/provider_supervisor.py` for full-run provider supervision). Historical `docs/plans/` and
- source-repo `docs/elves/` archives stay source-checkout only — never part of the installed skill.
- **Unattended by construction.** Gates and helper subprocesses run with closed stdin and explicit
- timeouts — a silent hang is a failure, not progress. Worker failures split into transient
- (backoff and resume; never consumes the re-drive budget) and substantive (budgeted re-drives,
- then split or host-native takeover). Workers keep an untracked progress ledger under
- `.elves/runtime/` so recovery starts oriented. See SKILL.md's Worker failure recovery and
- [`references/autonomy-guide.md`](references/autonomy-guide.md).
- ## What can go wrong
- Overnight agent runs fail in predictable ways. Knowing the failure modes makes them preventable.
- | Failure | What happens | Mitigation |
- |---|---|---|
- | **Machine sleeps** | Session stops silently. You wake up to 45 minutes of work instead of 8 hours. | `caffeinate` (macOS), `systemd-inhibit` (Linux), or run in cloud. Elves preflight warns you. |
- | **Agent runs destructive git commands** | `git reset --hard` wipes hours of uncommitted work. This has happened to real users. | Elves explicitly forbids `git reset --hard`, `git checkout .`, `git push --force`, and `git clean -fd`. The survival guide template includes these as non-negotiables. |
- | **Agent disables or weakens tests** | Agent comments out failing tests, weakens assertions, or shortens timeouts only to make the gate pass. You wake up to code that "passes" but is broken. | Elves forbids green-seeking test changes. Behavior-driven test updates are allowed when coverage is preserved or improved and the reason is recorded. |
- | **Context compaction loses instructions** | Long sessions hit memory limits. The agent's conversation gets summarized, and safety instructions disappear. | Elves stores layered run memory on disk. Host-native/legacy routes re-read after host commits/pushes; a trusted full-run host stays parked and re-reads/reconciles once at terminal/safety wake. The Stop Gate plus `continuation_guard` keep continuation explicit. |
- | **Interactive prompt stalls the session** | A tool asks for confirmation, a survey pops up, or `npm install` wants input. Nobody is there to click yes. | Elves surfaces the recommended non-interactive env vars during preflight, and the skill requires `--yes` flags plus tool-level survey suppression before unattended runs. Elves' own gates run with closed stdin and hard timeouts. |
- | **Flaky tests block progress** | A test passes locally but fails intermittently. The agent loops trying to fix a non-bug. | The agent logs flaky tests in the execution log and moves on after 3 failed attempts on the same non-deterministic failure. |
- | **Terminal closes (SSH disconnect)** | The SSH connection drops and the session dies. | Use `tmux` or `screen`. See the [operations guide](references/operations-guide.md). |
- | **Agent drifts from the plan** | After many batches, the agent starts making changes that weren't in the plan. | Host-native/legacy routes re-read after host pushes; trusted full-run carries one complete packet and the parked host reconciles at terminal/safety wake. Plan hashes, durable lessons, and a live (not append-only) survival guide anchor decisions. |
- | **Merge conflicts on push** | `git push` fails because the remote has diverged. The agent may rebase and lose work, or stall. | Elves instructs the agent to fetch and merge (never rebase on shared branches). If conflicts can't be resolved cleanly, the agent triggers a Hard Stop rather than risking data loss. |
- | **Two agents share a branch/checkout** | Claude and Codex (or two runs) write to the same branch in the same directory and clobber each other's files or move the branch mid-run. | One run owns one branch and one checkout. Use `./scripts/preflight.sh --create-worktree <branch> --base origin/main` when agents share a repo. Only the exact registered trusted full-run session may advance its assigned feature branch to a verified descendant; every other tripwire move stops as a collision. |
- Most of these are prevented by the preflight checks. Run preflight, fix the warnings, and most
- overnight failures never happen.
- ---
- ## Configuration
- ### Persistent preferences
- Copy [`config.json.example`](config.json.example) to `config.json` in your installed skill or
- project-local skill when you want defaults to persist across sessions. Put new Cobbler preferences
- under the top-level `cobbler` block. The legacy `council` block is for compatibility with older
- projects; if both blocks are present, `cobbler` wins. Math preferences belong under `math`.
- Shared safe worker convenience also lives at `${XDG_CONFIG_HOME:-~/.config}/elves/config.json`
- via `cobbler_agents.py preferences show|set|reset`.
- ### Tool configuration
- Tool-specific configuration lives in the survival guide under `## Tool Configuration` — the
- agent's instructions stay with the session. Minimal example:
- ```markdown
- ## Tool Configuration
- ### Validation Gates
- - lint: `npm run lint`
- - typecheck: `npm run typecheck`
- - build: `npm run build`
- - test: `npm test`
- ### Review
- - method: github-pr-comments
- ```
- If you don't configure validation gates, Elves auto-discovers them from your project files
- (`package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`). Full examples:
- [`references/tool-config-examples.md`](references/tool-config-examples.md).
- ### Batch sizing
- The default batch size is what a team of 4 developers would accomplish in a 2-week sprint. Each
- batch must be independently shippable: code, tests, docs, and passing review before moving on.
- Override in your plan or survival guide:
- ```markdown
- ## Batch Sizing
- - team-size: 2
- - sprint-length: 1 week
- ```
- ### Review methods
- | Tier | Method | Configuration |
- |---|---|---|
- | **Tier 1** | GitHub PR comments + built-in review | Default (zero config). |
- | **Tier 2** | Custom review API | Set `method: custom-api` and `review-api-url` in survival guide. |
- | **Tier 3** | Additional checks | Smoke tests, screenshot diffs, or any custom script returning 0/non-zero. |
- The agent uses the highest tier you have configured. Persistent false positives (3+ cycles) are
- dismissed with a written explanation in the execution log.
- Worker confidence now actively guides the primary review on both Claude Code and Codex. Trusted
- full-runs return a bounded machine-produced review block at terminal; native workers supply the
- same information through `Confidence:` commit trailers. The reviewer starts with that triage,
- deep-checks every reservation, low-confidence or conflicting area, and reports what it verified.
- Missing signals fall back to the full baseline review, and high confidence never reduces gates or
- review scope. See [`references/review-subagent.md`](references/review-subagent.md).
- ### Memory hygiene
- Long runs clean up as they go: keep live docs concise, archive old execution-log entries, promote
- durable lessons, stop idle resources, and write a reactivation handoff when a fresh thread would
- be faster. Elves does **not** delete local app state, chat databases, installed skills, plugins,
- or automations as part of a coding run. For explicit local maintenance, see the safe-maintenance
- pattern in [`references/autonomy-guide.md`](references/autonomy-guide.md).
- ---
- ## Repository reference index
- The compact canonical workflow is [`SKILL.md`](SKILL.md); [`AGENTS.md`](AGENTS.md) is the thin
- Codex adapter (invocation surface only — same workflow, same safety). Each contract lives in
- exactly one file below; other docs link instead of restating.
- **Elves (Grok Bot):** [`skills/elves-grok-bot/SKILL.md`](skills/elves-grok-bot/SKILL.md) is the
- unattended-run kernel for Grok Bot non-git work (HubSpot, Gmail, LinkedIn, CRM). Grok Bot is
- not Grok Build and not a fifth coding host. Technical name `elves-grok-bot`; invoked via
- natural "use elves", not `/goal`. Four files, Stop Gate, 1-minute watchdog, one fire at a
- time, terminal status, intent-before-send. Not for coding runs — root `SKILL.md` remains
- authoritative for Claude Code, Codex, Grok Build, and Oh My Pi code work.
- **Run lifecycle**
- - [`references/plan-template.md`](references/plan-template.md) — how to write a plan (stable
- `B#-A#` acceptance ids)
- - [`references/audit-playbook.md`](references/audit-playbook.md) — Discovery audit categories,
- the evidence rule, and the leverage rubric
- - [`references/finding-plan-template.md`](references/finding-plan-template.md) — per-finding
- executor handoff (distinct from `plan-template.md`, which shapes a batched run)
- - [`references/kickoff-prompt-template.md`](references/kickoff-prompt-template.md) — staging
- kickoff, including the worker packet and teardown expectations
- - [`references/survival-guide-template.md`](references/survival-guide-template.md) — Run Control,
- Stop Gate, compaction recovery, and the Out-of-scope findings ledger
- - [`references/execution-log-template.md`](references/execution-log-template.md),
- [`references/learnings-template.md`](references/learnings-template.md) — run memory
- - [`references/schema-and-acceptance.md`](references/schema-and-acceptance.md) — session schema,
- acceptance identity, worker packet at staging, work-driver spellings, landing/cleanup order
- - [`references/landing-authority.md`](references/landing-authority.md) — readiness vs merge
- authority
- - [`references/e2e-chat-to-land.md`](references/e2e-chat-to-land.md) — the end-to-end paths
- **Delegation and providers**
- - [`references/joyful-runs-contract.md`](references/joyful-runs-contract.md) — full-run operator
- contract (canonical code: `scripts/cobbler_runtime/canonical_contract.py`)
- - [`references/adaptive-worker-routing.md`](references/adaptive-worker-routing.md) — who
- implements and why
- - [`references/prewalk.md`](references/prewalk.md) — exact-session guide→execution trajectory,
- qualification, checkpoints, and recovery
- - [`references/parallelves.md`](references/parallelves.md) — Cobbler-coordinated parallel
- implementation lanes: serial default, recommend-only width test, trunk -> lanes -> integration
- - [`references/follow-mode.md`](references/follow-mode.md) — the parked driver's sanitized stream
- - [`references/grok-open-source-worker.md`](references/grok-open-source-worker.md) and
- [`references/grok-implementer-launch-prompt.md`](references/grok-implementer-launch-prompt.md)
- — external workers
- - [`references/model-onboarding.md`](references/model-onboarding.md),
- [`references/cobbler-setup-recipes.md`](references/cobbler-setup-recipes.md) — setup
- - [`references/provider-shortcuts.md`](references/provider-shortcuts.md) — focused Fugu,
- Manus, Grok Build, and Devin command routes
- - [`references/omp-worker.md`](references/omp-worker.md) — Oh My Pi main driver and optional `omp-cli` / `/omp` worker
- - [`references/host-parity.md`](references/host-parity.md) — Claude Code / Codex parity
- - [`references/project-landing-profiles.md`](references/project-landing-profiles.md) — tracked
- repository-specific exact-HEAD readiness checks
- **Quality and proof**
- - [`references/proof-and-review.md`](references/proof-and-review.md) — impact-selected proof,
- convergent review
- - [`references/verification-patterns.md`](references/verification-patterns.md),
- [`references/validation-guide.md`](references/validation-guide.md) — gates
- - [`references/review-subagent.md`](references/review-subagent.md) — independent review
- - [`references/autonomy-guide.md`](references/autonomy-guide.md) — staying unattended
- - [`references/operations-guide.md`](references/operations-guide.md) — sleep prevention, tmux,
- monitoring, notifications, SessionStart hook, daily briefing
- **Domain workflows**
- - [`references/math-workflow.md`](references/math-workflow.md) and the `references/math-*.md`
- family — the math research pack
- - [`references/open-ended-guide.md`](references/open-ended-guide.md) — open-ended runs
- - [`references/council-workflow.md`](references/council-workflow.md),
- [`references/council-prompts.md`](references/council-prompts.md),
- [`references/councilelves-launch-prompt.md`](references/councilelves-launch-prompt.md) — legacy
- Council surfaces (Council is a deprecated alias of Cobbler)
- **Templates and reports**
- - [`references/elves-report-template.html`](references/elves-report-template.html) — end-of-run
- report
- - [`references/runtime-helper-paths.md`](references/runtime-helper-paths.md) — installed vs
- source-checkout helper paths
- ## Maintainers' gates (this repository)
- ```bash
- # Elves source checkout:
- python3 scripts/verify_repo.py --ci
- # before operational-artifact cleanup, from a clean worktree:
- python3 scripts/verify_repo.py --final-readiness \
- --session .elves-session.json
- # after the narrow operational-artifact cleanup commit, on its clean current tip:
- python3 scripts/verify_repo.py --ci --base-ref origin/main
- test -z "$(git status --porcelain)"
- ```
- These are maintainers' gates for this source checkout; the repo-only helper is not shipped in a
- global skill install. Installed runs use their target project's gates plus the installed
- `elves_landing_check.py` (see
- [`references/runtime-helper-paths.md`](references/runtime-helper-paths.md)):
- ```bash
- python3 "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py" \
- --session <session-path> --repo-root .
- ```
- When the target tracks `.elves/landing-profile.json`, the landing check evaluates it automatically.
- The standalone installed command is:
- ```bash
- python3 "$ELVES_SKILL_ROOT/scripts/landing_profile.py" check \
- --repo-root . --base origin/main --json
- ```
- Learning commands (`observe`, `propose`, `candidates`, `promote`, `waive`, `clear-waiver`) use the
- same CLI. Only `promote` rewrites the tracked profile; runtime learning state stays under
- `.elves/runtime/landing-profile/`.
- Intentional source-checkout public-API breaks must be declared in the tracked
- `api-break-approvals.json` for the exact `--version`. Every entry names one surface, a non-empty
- reason, and a tracked in-repo plan. Strict verification rejects malformed, stale, untracked, or
- plan-less approvals.
- ## File structure
- ```text
- elves/
- ├── SKILL.md # canonical workflow (all hosts)
- ├── AGENTS.md # thin Codex adapter
- ├── README.md # this file
- ├── CHANGELOG.md # version history (the only home of "vX adds…")
- ├── config.json.example # persistent preferences
- ├── aliases/ # managed Claude Code alias skills
- ├── guide/ # published user guide (GitHub Pages)
- ├── references/ # one authoritative file per contract (see index)
- ├── scripts/ # helpers + cobbler_runtime package
- ├── tests/ # unittest suite (hermetic: fd-0 devnull guard)
- └── .ai-docs/ # durable architecture/conventions/gotchas
- ```
- ## Platform support
- | Platform | File | Subagents | Notes |
- |---|---|---|---|
- | Claude Code | SKILL.md | Yes | Full feature set |
- | Codex | SKILL.md | Varies | Use review subagents when available; otherwise do the review directly. `AGENTS.md` remains the repo-local Codex companion |
- | Claude.ai | SKILL.md (zip upload) | No | Upload as skill |
- | Any Agent Skills compatible | SKILL.md | Varies | Open standard |
- ## Philosophy
- Convert idle hours into shipped code: try, check, feed back, repeat. Memory lives in files, not
- chat. Root cause over band-aids; centralize over duplicate; extend over create; favor boring
- technology. The human owns what is worth building and whether it merges — the agent owns the
- middle.
- Agy reviews always use `/boost` in plan mode, including reviews of fixes.
- The reviewer uses a separate session from the code writers. Boost failure
- requires an authorized independent fallback or a block; a plain Agy response
- does not satisfy review. Pass the absolute admitted workspace to all Boost
- workers. Use a supervised terminal when headless transport is unqualified.
- Keep required isolation. Approve scoped review actions and wait for child
- completion plus a final report at the exact commit. Headless success alone
- does not prove a review. See [the review rules](references/review-subagent.md).
- A clean Agy review also needs context coverage. Read changed files, relevant
- callers, tests, instructions, and task docs. The host checks the coverage
- record against the diff and read evidence. Missing required context blocks
- a clean result.
- ## Contributing
- Issues and pull requests are welcome. If you find a bug, have a feature idea, or want to add
- support for a new platform or tool, open an issue to discuss it first.
- When submitting a PR:
- - Keep changes focused: one concern per PR.
- - Update the relevant template or reference file if your change affects agent behavior.
- - Test your change with at least one real overnight run if possible.
- - For cross-file skill/doc changes, run:
- ```bash
- python3 scripts/check_repo_consistency.py
- ```
- ## Disclaimer
- This software is provided "as is", without warranty of any kind, express or implied. Neither
- Aigora nor John Ennis are liable for any claims, damages, or other liability arising from using
- this software. That includes code changes, data loss, security incidents, infrastructure costs, or
- anything else that happens. The [MIT license](LICENSE) already says this, but we want to be clear
- about it here too.
- Elves expects you to grant your AI agent the permissions it needs to run autonomously. That might
- mean file system access, git push, GitHub CLI auth, shell command execution, or other tool
- approvals depending on your platform. If the agent has to pause and wait for permission during an
- unattended run, it'll stall. So the skill works best when you pre-approve what the agent will
- need. You're granting those permissions at your own risk. Know what you're allowing before you
- walk away.
- There's nothing uniquely dangerous about Elves. It uses standard tools (git, GitHub, your existing
- test suite) and it has safety measures (forbidden commands, test integrity rules, scoped rollback
- refs). But no software is foolproof, and an agent running for hours with broad permissions can
- make mistakes. Always review the PR before merging.
- ## License
- MIT, see [LICENSE](LICENSE).
- Copyright (c) 2026 Aigora.
- ## Teams on one task
- Ask for a driver with helpers, or ask several models to propose and compare
- solutions. Elves uses its existing model routes. It records contributor identities
- and keeps the landing reviewer independent. Optional Lantern reports arrive at
- driver checkpoints. Persistent writer lanes check dependencies, worktree identity,
- and actual changed files before driver integration.
- Read the [team guide](references/agent-teams.md) for setup, commands, and limits.
scripts/consistency_policy.py · Bundled script · 2,953 lines · 2 findings marked
- """Declarative repo-consistency policy inventory and phrase scenarios.
- Extracted from check_repo_consistency.py so the generic engine stays small.
- Semantic/mutation tests assert behavior, not preferred marketing phrases alone.
- """
- from __future__ import annotations
- from pathlib import Path
- REPO_ROOT = Path(__file__).resolve().parent.parent
- VERSION_FILES = {
- "SKILL.md": REPO_ROOT / "SKILL.md",
- "AGENTS.md": REPO_ROOT / "AGENTS.md",
- }
- # Surfaces that display the release version in prose rather than frontmatter.
- # VERSION_FILES only reads frontmatter, so these are invisible to it and can ship
- # stale behind a green check. `{version}` is substituted with the repo skill version.
- INLINE_VERSION_SURFACES = {
- "SKILL.md": ["User guide (v{version})"],
- "README.md": ["**Current release: v{version}**"],
- "guide/index.html": ["v{version} source and releases"],
- }
- CHANGELOG_PATH = REPO_ROOT / "CHANGELOG.md"
- RECOVERY_ORDER_FILES = {
- "SKILL.md": REPO_ROOT / "SKILL.md",
- "AGENTS.md": REPO_ROOT / "AGENTS.md",
- "references/kickoff-prompt-template.md": REPO_ROOT / "references" / "kickoff-prompt-template.md",
- "references/survival-guide-template.md": REPO_ROOT / "references" / "survival-guide-template.md",
- }
- RECOVERY_ORDER_TOKENS = [
- "survival guide",
- ".elves-session.json",
- "learnings",
- "plan",
- "execution log",
- ".ai-docs/manifest.md",
- ]
- PENDING_DOCS_FILES = {
- "SKILL.md": REPO_ROOT / "SKILL.md",
- "AGENTS.md": REPO_ROOT / "AGENTS.md",
- "references/review-subagent.md": REPO_ROOT / "references" / "review-subagent.md",
- }
- DURABLE_DOCS = [
- REPO_ROOT / "docs" / "elves" / "learnings.md",
- REPO_ROOT / ".ai-docs" / "manifest.md",
- REPO_ROOT / ".ai-docs" / "architecture.md",
- REPO_ROOT / ".ai-docs" / "conventions.md",
- REPO_ROOT / ".ai-docs" / "gotchas.md",
- REPO_ROOT / ".ai-docs" / "context-index.md",
- REPO_ROOT / "references" / "learnings-template.md",
- ]
- NONSTOP_GUARDRAIL_PHRASES = {
- "SKILL.md": [
- "Stop Gate",
- "continuation_guard",
- "After every host-owned commit and push, re-read the survival guide before doing anything else.",
- "Do not wait for user acknowledgment",
- ],
- "references/survival-guide-template.md": [
- "## Stop Gate",
- "## Forbidden Stop Reasons",
- "Stop allowed right now",
- "Every completed batch must end with a commit and push",
- "continue without waiting for user acknowledgment",
- ],
- "references/kickoff-prompt-template.md": [
- "Every completed batch must end with a commit and push before you start anything else.",
- "Immediately after every commit and push, re-read the survival guide before any other action.",
- "Do not send a final response unless the survival guide Stop Gate says stopping is allowed or a true blocker forces it.",
- ],
- "references/open-ended-guide.md": [
- "## Stop Gate Pattern",
- "## Forbidden Stop Reasons",
- "continuation_guard.stop_allowed: false",
- ],
- }
- # Discovery phase: the read-only survey that precedes Planning when no task is named.
- # Anchors only. The boundary (read-only on source, writes confined to advisor-plans/)
- # and the two contracts (evidence, leverage) must restate wherever Discovery appears.
- DISCOVERY_GUARDRAIL_PHRASES = {
- "SKILL.md": [
- "## Discovery",
- "**read-only on source**",
- "advisor-plans/",
- "references/audit-playbook.md",
- "references/finding-plan-template.md",
- "gh issue create",
- ],
- "references/audit-playbook.md": [
- "## Finding format",
- "## Prioritization rubric",
- ],
- "references/finding-plan-template.md": [
- "advisor-plans/NNN-short-slug.md",
- "zero context",
- ],
- "README.md": [
- "references/audit-playbook.md",
- ],
- }
- # Out-of-scope findings: work a run notices that the plan does not cover. The rule is
- # "file it, never fix it, never drop it", and it must reach the worker-facing surfaces,
- # not only SKILL.md. Anchors only.
- OUT_OF_SCOPE_GUARDRAIL_PHRASES = {
- "SKILL.md": [
- "## Out-of-Scope Findings",
- "gh issue create",
- "never file a duplicate",
- "deferred hygiene",
- "Scout Mode",
- ],
- "references/survival-guide-template.md": [
- "## Out-of-scope findings",
- "Filed this run:",
- "Could not file:",
- ],
- "references/kickoff-prompt-template.md": [
- "do not fix it and do not widen the batch",
- "gh issue create",
- ],
- }
- # Section/contract anchors only — do not pin motivational prose byte-for-byte.
- # Editorial rewording of effort guidance must not break CI.
- EFFORT_GUARDRAIL_PHRASES = {
- "SKILL.md": [
- "## Effort Standard",
- "Work as hard as you can",
- "plan acceptance and blockers",
- "deferred hygiene",
- ],
- "references/survival-guide-template.md": [
- "## Effort Standard",
- "Work as hard as you can",
- "## Deferred hygiene",
- "impact path mid-run",
- ],
- "references/kickoff-prompt-template.md": [
- "Work as hard as you can",
- "Do not coast after the first success",
- "deferred hygiene",
- "impact-path",
- ],
- "references/open-ended-guide.md": [
- "## Sustain Effort",
- "Work as hard as you can",
- "deferred hygiene",
- "impact path",
- ],
- }
- # Mid-run impact path vs terminal full suite + deferred hygiene (v2.20.0).
- # Without these pins, validation-guide can reintroduce "zero debt every batch" and
- # fight the proof budget again.
- MIDRUN_TERMINAL_HYGIENE_PHRASES = {
- "SKILL.md": [
- "deferred hygiene",
- "impact path",
- "full suite",
- "validate once, verify changes, attest final",
- ],
- "references/validation-guide.md": [
- "validate once, verify changes, attest final",
- "Deferred hygiene",
- "Mid-run vs terminal",
- "impact path",
- "weaken, skip, or delete tests",
- ],
- "references/proof-and-review.md": [
- "deferred hygiene",
- "full suite",
- "impact path",
- "per-batch driver reviews",
- ],
- "references/survival-guide-template.md": [
- "Deferred hygiene",
- "full suite at terminal",
- "impact-selected proof during work",
- ],
- "references/execution-log-template.md": [
- "Deferred hygiene",
- ],
- }
- FINAL_READINESS_REVIEW_PHRASES = {
- "SKILL.md": [
- "Final Readiness Review",
- "git diff <default-branch>...HEAD",
- "review subagent",
- ],
- "references/review-subagent.md": [
- "## Final Readiness Review",
- "git diff [DEFAULT_BRANCH]...HEAD",
- ],
- "references/kickoff-prompt-template.md": [
- "Require a final readiness review",
- "git diff <default-branch>...HEAD",
- ],
- }
- SINGLE_KICKOFF_PHRASES = {
- "SKILL.md": [
- "Default user path: one kickoff",
- "Trusted full-run delegation keeps that path",
- "chat-to-work",
- "chat-to-land",
- "Legacy two-call handoff",
- "full-run",
- "parked",
- ],
- "references/kickoff-prompt-template.md": [
- "Recommended: one kickoff",
- "trusted full-run / parked-monitor",
- "Chat-to-work (E2E, no merge)",
- "Chat-to-land (E2E through merge)",
- "Use separate calls only for the legacy path",
- ],
- "references/e2e-chat-to-land.md": [
- "recommended default user path",
- "Trusted Grok full-run delegation is the optional parked shape",
- "without waiting for a second human call",
- "Legacy / advanced",
- ],
- }
- FUTILE_REDRIVE_GUARD_PHRASES = {
- "SKILL.md": [
- "redrive_futile:workspace_unchanged",
- "manufacture futility",
- "do not repeat the previous approach",
- "redrive record-failure|evaluate|status",
- ],
- "references/e2e-chat-to-land.md": [
- "redrive_futile:workspace_unchanged",
- "manufacture futility",
- "do not repeat the previous approach",
- ],
- "references/glossary.md": [
- "redrive_futile:workspace_unchanged",
- "Futile re-drive",
- ],
- }
- LEARNINGS_LEDGER_PHRASES = {
- "SKILL.md": [
- "learnings validate|apply|rollback|digest|migrate",
- "learnings-history.jsonl",
- "never deletes",
- ],
- "references/learnings-template.md": [
- "learnings validate|apply|rollback|digest|migrate",
- "learnings-history.jsonl",
- "never automatic",
- ],
- "references/glossary.md": [
- "Learnings ledger",
- "learnings-history.jsonl",
- ],
- }
- USAGE_OBSERVED_PHRASES = {
- "references/survival-guide-template.md": [
- "Observed usage so far",
- "observed ≠ billed",
- "never a stop",
- ],
- "references/schema-and-acceptance.md": [
- "usage_observed",
- "usage_ceiling_checkpoint",
- "never a routing",
- "observed ≠ billed",
- ],
- }
- CURRENT_STATE_AUDIT_PHRASES = {
- "SKILL.md": [
- "the current state against every requirement",
- "memory of earlier work",
- ],
- "references/open-ended-guide.md": [
- "the current state against every requirement",
- "memory of earlier work",
- ],
- "references/kickoff-prompt-template.md": [
- "the current state against every requirement",
- "memory of earlier work",
- ],
- }
- CONTINUITY_WATCHDOG_PHRASES = {
- "references/operations-guide.md": [
- "never resumes a terminal run",
- "the OS owns the timer",
- "continuity install",
- ],
- "references/glossary.md": [
- "Continuity watchdog",
- "never resumes a terminal run",
- ],
- }
- SALVAGE_PREVIEW_PHRASES = {
- "SKILL.md": [
- "salvage tail --log",
- "never a completion report",
- ],
- "references/e2e-chat-to-land.md": [
- "salvage tail --log",
- "never a completion report",
- ],
- }
- SINGLE_KICKOFF_FORBIDDEN_PHRASES = {
- "README.md": [
- "Use the launch template from the same reference file in a fresh call",
- "**Two-step operator flow**",
- ],
- "AGENTS.md": [
- "do not launch in that same call",
- "Execution starts only from a fresh short launch prompt in the next call",
- ],
- "references/kickoff-prompt-template.md": [
- "**Stage and launch in separate calls**",
- "**If you only send one message, the agent should stage first**",
- "wait for your final launch command",
- ],
- }
- _SINGLE_KICKOFF_SURFACES = (
- "SKILL.md",
- "AGENTS.md",
- "README.md",
- "references/kickoff-prompt-template.md",
- "references/e2e-chat-to-land.md",
- "references/grok-implementer-launch-prompt.md",
- )
- SINGLE_KICKOFF_UNSCOPED_PATTERNS = {
- label: [
- r"\b(?:wait|stop)\b[^.\n]{0,160}\b(?:second|fresh|separate|another|final)\b[^.\n]{0,100}\b(?:launch|call|message|command)\b",
- r"\b(?:second|fresh|separate|another)\s+(?:human\s+)?(?:launch|call|message|command)\b",
- ]
- for label in _SINGLE_KICKOFF_SURFACES
- }
- EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS = {
- label: [r"full-run-\*"]
- for label in (
- "SKILL.md",
- "AGENTS.md",
- "README.md",
- "references/grok-implementer-launch-prompt.md",
- )
- }
- INSTALLED_HELPER_PATH_PHRASES = {
- "SKILL.md": [
- "source-checkout shorthand",
- "active Elves skill root",
- "~/.claude/skills/elves",
- "~/.codex/skills/elves",
- "~/.grok/skills/elves",
- "~/.omp/agent/skills/elves",
- "$ELVES_SKILL_ROOT/scripts/acceptance_contract.py",
- "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py",
- "installed Elves bundle never requires a repo-only helper",
- ],
- "references/runtime-helper-paths.md": [
- "## Source checkout shorthand",
- "## Installed Claude Code, Codex, Grok Build, or Oh My Pi skill",
- "## Shipped call-site runtime deps",
- "## Source-only archives",
- "target repository as the working directory",
- "$HOME/.claude/skills/elves",
- "$HOME/.codex/skills/elves",
- "$HOME/.grok/skills/elves",
- "$HOME/.omp/agent/skills/elves",
- "scripts/acceptance_contract.py",
- "scripts/elves_landing_check.py",
- "scripts/worktree_gc.py",
- "scripts/provider_supervisor.py",
- "docs/plans/",
- "Never make an ordinary installed Elves run",
- "depend on a repo-only helper",
- ],
- "references/grok-implementer-launch-prompt.md": [
- "runtime-helper-paths.md",
- "source-checkout shorthand",
- ],
- }
- _INSTALLED_FINAL_READINESS_SURFACES = (
- "SKILL.md",
- "AGENTS.md",
- "references/kickoff-prompt-template.md",
- "references/review-subagent.md",
- "references/survival-guide-template.md",
- )
- INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS = {
- label: [
- r"python3\s+(?:\./)?scripts/(?:verify_repo|release_checklist|check_repo_consistency|installed_bundle_smoke|pr_portfolio_report|sync_installed_skills)\.py\b"
- ]
- for label in _INSTALLED_FINAL_READINESS_SURFACES
- }
- REPO_CONSISTENCY_WORKFLOW_PHRASES = {
- ".github/workflows/repo-consistency.yml": [
- '"api-break-approvals.json"',
- '"config.json.example"',
- '".env*"',
- '"openapi.json"',
- '"openapi.yaml"',
- '"swagger.json"',
- '".github/ISSUE_TEMPLATE/**"',
- '".github/workflows/repo-consistency.yml"',
- '".github/workflows/pages.yml"',
- '"aliases/**"',
- '"guide/**"',
- '"PRODUCT.md"',
- '"docs/cobbler.md"',
- '"docs/openapi.json"',
- '"scripts/**"',
- "fetch-depth: 0",
- "Unreleased",
- "Development commits verify Unreleased",
- "scripts/release_checklist.py",
- "read_frontmatter_version",
- 'BASE_REF="$(git describe --tags --abbrev=0 --exclude="v${VERIFY_VERSION}" HEAD^)"',
- 'python3 scripts/verify_repo.py --ci --version "$VERIFY_VERSION"',
- "--base-ref",
- "actions/checkout@v6",
- "actions/setup-python@v6",
- ],
- }
- ACCEPTANCE_EVIDENCE_PHRASES = {
- "SKILL.md": [
- "plan Acceptance with proof",
- "acceptance",
- "elves_landing_check.py",
- "God-file",
- "one batch per close commit",
- ],
- "references/survival-guide-template.md": [
- "plan Acceptance with proof",
- "Evidence / SCRATCH Layout",
- "elves_landing_check.py",
- ],
- "references/execution-log-template.md": [
- "**Validate:**",
- "Plan Acceptance proof",
- ],
- "references/plan-template.md": [
- "characterization-only",
- "acceptance: [{criterion, met, evidence}]",
- ],
- }
- LANDING_CHECK_CONTRACT_PHRASES = {
- label: [
- "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py",
- "--session <session-path> --repo-root .",
- "plan_path",
- "equality assertion",
- ]
- for label in (
- "SKILL.md",
- "AGENTS.md",
- "references/survival-guide-template.md",
- )
- }
- LANDING_CHECK_BARE_FORBIDDEN_PATTERNS = {
- label: [r"python3\s+(?:\./)?scripts/elves_landing_check\.py\b"]
- for label in LANDING_CHECK_CONTRACT_PHRASES
- }
- CODEX_GOALS_SECTION_HEADINGS = {}
- CODEX_GOALS_SECTION_PHRASES = {
- }
- CODEX_GOALS_SECTION_FORBIDDEN_PHRASES = {
- "README.md": [
- "docs/elves/survival-guide.md",
- "docs/plans/my-plan.md",
- "docs/elves/execution-log.md",
- ],
- }
- REPO_CONSISTENCY_WORKFLOW_FORBIDDEN_PHRASES = {
- ".github/workflows/repo-consistency.yml": [
- "actions/checkout@v4",
- "actions/setup-python@v5",
- ],
- }
- REVIEWED_PR_LANDING_PHRASES = {
- "README.md": [
- "\\land-pr",
- "/land-pr",
- ],
- "SKILL.md": [
- "## Reviewed PR Landing Command",
- "\\land-pr",
- "/land-pr",
- "gh pr merge --merge",
- "default when bots are expected",
- "Fugu review of the current PR diff, when needed and authorized",
- "$elves fugu review",
- "Never invent a raw Fugu call",
- "A landing request alone does not authorize a paid Fugu call",
- "bump the version when the repository versions",
- "**Can it merge?**",
- "**Was it tested?**",
- "Local tests passed on <head SHA>",
- "never count as tested",
- "same-day back-merge PR",
- ],
- "references/review-subagent.md": [
- "### Reviewed PR Landing Command",
- "\\land-pr",
- "/land-pr",
- "gh pr merge --merge",
- "one-off merge opt-in",
- "Fugu review of the current PR diff, when needed and authorized",
- "$elves fugu review",
- "Hosts must not invent a raw Fugu call",
- "A landing request alone does not authorize Fugu",
- "bump the version when the repository versions",
- "Local tests passed on <head SHA>",
- "commits/${HEAD_SHA}/check-runs",
- ],
- "references/e2e-chat-to-land.md": [
- "\\land-pr",
- "/land-pr",
- "gh pr merge --merge",
- "Fugu review of the current PR diff, when needed and authorized",
- "$elves fugu review",
- "Hosts must not invent a raw Fugu call",
- "A landing request alone does not authorize Fugu",
- "bump the version when the repository versions",
- ],
- "references/survival-guide-template.md": [
- "reviewed-pr-landing-command",
- "\\land-pr",
- "/land-pr",
- "one-off explicit merge opt-in",
- ],
- "references/kickoff-prompt-template.md": [
- "reviewed-PR landing command",
- "\\land-pr",
- "/land-pr",
- "gh pr merge --merge",
- "Fugu review of the current PR diff only when needed and authorized",
- "$elves fugu review",
- "never invent a raw Fugu call",
- "bump the version when the repository versions",
- ],
- "references/plan-template.md": [
- "reviewed-PR landing command",
- "\\land-pr",
- "/land-pr",
- ],
- }
- REVIEWED_PR_LANDING_FORBIDDEN_PHRASES = {
- "SKILL.md": [
- "Only if the user has set a merge-on-green preference in Run Control do you merge yourself",
- "A merge is requested and the user has not set a merge-on-green preference.",
- ],
- "AGENTS.md": [
- "Only if the user has set a merge-on-green preference in Run Control do you merge yourself",
- "A merge is requested and the user has not set a merge-on-green preference.",
- "that gate stays with the user unless they set a merge-on-green preference.",
- ],
- "references/kickoff-prompt-template.md": [
- "merge policy (default: you never merge; opt-in: merge-commit-on-green)",
- "only if the user explicitly set a merge-on-green preference",
- ],
- "references/review-subagent.md": [
- 'gh api "repos/OWNER/REPO/commits/HEAD/check-runs"',
- ],
- }
- MEMORY_HYGIENE_PHRASES = {
- "SKILL.md": [
- "## Strategic Forgetting",
- "chats are for execution",
- "memory and resource hygiene",
- ],
- "references/survival-guide-template.md": [
- "## Strategic Forgetting",
- "## Memory and Resource Hygiene",
- ],
- "references/autonomy-guide.md": [
- "## Memory Pressure And Strategic Forgetting",
- "Local app maintenance",
- ],
- }
- ELVES_REPORT_PHRASES = {
- "SKILL.md": [
- "## Elves Report",
- "problems found",
- "lessons learned",
- "/tmp/elves-report-<repo-slug>-<yyyy-mm-dd>.html",
- "references/elves-report-template.html",
- "collapsible `<details>` sections",
- "committed examples and reusable templates non-identifying",
- "Elves Report path",
- ],
- "references/survival-guide-template.md": [
- "## Elves Report",
- "problems found",
- "lessons learned",
- "/tmp/elves-report-<repo-slug>-<yyyy-mm-dd>.html",
- "references/elves-report-template.html",
- ],
- "references/execution-log-template.md": [
- "**Elves Report:**",
- "**Problems found:**",
- "**Lessons learned:**",
- ],
- "references/elves-report-template.html": [
- "Elves Report",
- "Problems Found",
- "Lessons Learned",
- "Batch Ledger",
- "<details class=\"batch\"",
- ],
- "docs/elves-report-proof-of-concept.html": [
- "Elves Report",
- "assets/elves-banner.jpeg",
- "Problems found",
- "Lessons learned",
- "Batch Ledger",
- "<details class=\"batch\"",
- ],
- }
- WORKSPACE_ISOLATION_PHRASES = {
- "SKILL.md": [
- "One run owns one branch and one checkout",
- "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
- "--dry-run",
- "branch, worktree path, base ref, and collision tripwire",
- "does not reuse, delete, or repair existing worktrees",
- "collision tripwire",
- ],
- "README.md": [
- "One run owns one branch and one checkout",
- "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
- "--dry-run",
- "branch, worktree path, base ref, and collision tripwire",
- "does not reuse, delete, or repair existing worktrees",
- "collision tripwire",
- ],
- "references/survival-guide-template.md": [
- "One run owns one branch and one checkout",
- "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
- "--dry-run",
- "branch, worktree path, base ref, and collision tripwire",
- "does not reuse, delete, or repair existing worktrees",
- "collision tripwire",
- ],
- "references/kickoff-prompt-template.md": [
- "git worktree",
- "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
- "--dry-run",
- "branch, worktree path, base ref, and collision tripwire",
- "does not reuse, delete, or repair existing worktrees",
- ],
- "scripts/preflight.sh": [
- "Workspace Ownership",
- "preflight_worktree.py",
- "--create-worktree",
- "git worktree list --porcelain",
- "Current branch is checked out in one worktree",
- "(current checkout)",
- "Recommended dedicated worktree",
- "Use one owned branch and checkout per Elves run before launching",
- ],
- "scripts/preflight_worktree.py": [
- "DEFAULT_BASE_REF = \"origin/main\"",
- "--create-worktree",
- "--worktree-dir",
- "--base",
- "--dry-run",
- "git worktree add",
- "Default base origin/main does not resolve; pass --base <ref>.",
- "Requested --worktree-dir already exists",
- "Created dedicated worktree",
- "Recommended dedicated worktree",
- "collision tripwire:",
- ],
- }
- OPERATOR_DOC_PHRASES = {
- ".ai-docs/manifest.md": [
- "curated layer above the run-specific `docs/elves/*` memory surfaces",
- "`<plan_path>` from `.elves-session.json`",
- "`<survival_guide_path>` from `.elves-session.json`",
- "`<execution_log_path>` from `.elves-session.json`",
- "`<learnings_path>` from `.elves-session.json`",
- "Promotion flow: `execution log -> learnings -> .ai-docs`",
- ],
- ".ai-docs/architecture.md": [
- "## Memory layers",
- "live run control, checkpoint semantics, active compute, next exact batch",
- "Live operator state belongs in the survival guide and should be rewritten in place.",
- "changes almost always cross multiple surfaces",
- ],
- ".ai-docs/conventions.md": [
- "Run control is live metadata",
- "survival guide's `Run Control` block",
- "survival guide's `Stop Gate`",
- "Active Compute",
- "Every completed batch must end with `update docs -> commit -> push -> re-read survival guide`",
- "Repo-only maintenance helpers stay in the checkout.",
- "pin it with a `*_PHRASES` map",
- ],
- ".ai-docs/gotchas.md": [
- "Stop Gate",
- "continuation_guard",
- "same working tree on the same branch",
- "dedicated `git worktree` per run",
- "Paid pods, remote jobs, and long-lived local services",
- "Local project installs can quietly shadow global installs.",
- ],
- ".github/ISSUE_TEMPLATE/overnight_run_report.md": [
- "- **Run mode:**",
- "- **Checkpoint semantics:**",
- "- **Active compute:**",
- "Run-control behavior",
- "What you changed in your setup afterward",
- ],
- "references/kickoff-prompt-template.md": [
- "Set `## Run Control` explicitly",
- "checkpoint semantics",
- "may-continue-after-checkpoint",
- "actual stop conditions",
- "`Active Compute` if relevant",
- "collision tripwire",
- ],
- }
- MATH_MODULE_PHRASES = {
- "SKILL.md": [
- "## Math Research Workflows",
- "Cobbler-managed Elves domain workflow",
- "Discovery Sprint",
- "Native host subagents or direct analysis are the default",
- "useful optional math role preset",
- "Google Cloud AlphaEvolve",
- "math-alphaevolve.md",
- "Never treat model output",
- ],
- "references/survival-guide-template.md": [
- "### Math Configuration (optional)",
- "math-coordination: cobbler-managed-domain-workflow",
- "math-provider-policy: native-first-with-optional-external-routes",
- "math-required-env: []",
- "subfield_scout: native-subagent",
- "math-external-route-examples",
- "record the",
- "fallback in the model-call ledger",
- ],
- "references/tool-config-examples.md": [
- "## Math Research Workflow",
- "math-coordination: cobbler-managed-domain-workflow",
- "math-provider-policy: native-first-with-optional-external-routes",
- "math-required-env: []",
- "OPENROUTER_API_KEY",
- "math-ledger-dir: docs/math",
- ],
- "references/math-workflow.md": [
- "Cobbler-managed Elves domain workflow",
- "Cobbler Harness Mapping",
- "## The Discovery Sprint",
- "## Cross-Pollination",
- "## Claim Lifecycle",
- "math-artifact-ledgers.md",
- "math-alphaevolve.md",
- "Evolutionary example search",
- ],
- "references/math-plan-template.md": [
- "## Batch 1: Discovery Sprint",
- "algebraic/combinatorial analogs",
- "Every `quick_win` item has a plausible proof path",
- "evolutionary_search: alphaevolve",
- ],
- "references/math-provider-config.md": [
- "Cobbler-managed domain-workflow setting",
- "No provider key is required by this template",
- "## Role Slots",
- "native-first-with-optional-external-routes",
- "OPENROUTER_API_KEY",
- "record-before-switching-provider",
- "evolutionary_search",
- "math-alphaevolve.md",
- ],
- "references/math-alphaevolve.md": [
- "Google Cloud **AlphaEvolve**",
- "not a proof engine",
- "evolutionary_search",
- "independent-local-replay-only",
- "gcloud-impersonation",
- "deterministic local evaluator",
- ],
- "references/math-review-prompts.md": [
- "## Subfield Scout",
- "## Proof Critic",
- "## Source Auditor",
- "## Formalization Scout",
- "## Evolutionary Search (AlphaEvolve / similar)",
- ],
- "references/math-artifact-ledgers.md": [
- "domain evidence ledgers",
- "## Claim Ledger",
- "## Source Ledger",
- "## Model-Call Ledger",
- "## Human-Verification Ledger",
- "alphaevolve:<task-id>",
- ],
- "config.json.example": [
- '"math"',
- '"coordination": "cobbler-managed-domain-workflow"',
- '"provider_policy": "native-first-with-optional-external-routes"',
- '"required_env": []',
- '"subfield_scout"',
- '"evolutionary_search"',
- '"alphaevolve"',
- '"fallback_policy": "record-before-switching-provider"',
- ],
- }
- DOMAIN_WORKFLOW_PHRASES = {
- "SKILL.md": [
- "## Coordination Architecture",
- "**Elves** is the execution system",
- "**Cobbler** is the default coordinator",
- "**Domain workflows** are specialized Cobbler-managed packs",
- "**Math** is the first domain workflow",
- "**Providers** are optional role routes",
- "cobbler.default_for_session",
- ],
- "docs/cobbler.md": [
- "## The coordination hierarchy",
- "**Elves** handles execution",
- "**Cobbler** handles coordination",
- "**Domain workflows** handle specialized work under Cobbler",
- "Math is the first domain workflow",
- "cobbler.default_for_session",
- ],
- "references/council-workflow.md": [
- "Elves executes, Cobbler coordinates, domain workflows specialize, and providers",
- "route optional roles",
- "Math is the first Cobbler-managed domain workflow",
- "domain evidence artifacts",
- ],
- "references/kickoff-prompt-template.md": [
- "Cobbler Session State",
- "cobbler.default_for_session: true",
- "math as a Cobbler-managed domain workflow",
- ],
- "references/survival-guide-template.md": [
- "## Cobbler Session State",
- "Cobbler default",
- "cobbler.default_for_session: true",
- "Math is a Cobbler-managed domain workflow",
- ],
- "references/review-subagent.md": [
- "Cobbler Session State",
- "cobbler.default_for_session",
- "Math Domain Workflow Context",
- "math ledgers are treated as domain evidence artifacts",
- ],
- "references/execution-log-template.md": [
- "Math ledger status",
- ],
- "references/math-workflow.md": [
- "Cobbler-managed Elves domain workflow",
- "Cobbler is the coordinator",
- "Present/record",
- "Reclassify",
- ],
- "references/math-provider-config.md": [
- "Math provider routing is a Cobbler-managed domain-workflow setting",
- "No provider key is required by this template",
- "Missing optional provider access never blocks ordinary Cobbler use or a",
- "math Discovery Sprint",
- ],
- "references/math-plan-template.md": [
- "Math is a Cobbler-managed Elves",
- "math-coordination: cobbler-managed-domain-workflow",
- "math-required-env: []",
- ],
- "references/math-review-prompts.md": [
- "Cobbler role templates for the math domain workflow",
- "Every math role should receive the same context packet",
- "Configured",
- "external providers are optional role routes",
- ],
- "references/math-artifact-ledgers.md": [
- "domain evidence ledgers",
- "not a separate Cobbler, Council, or run-state ledger",
- "native-subagent",
- ],
- "references/tool-config-examples.md": [
- "Math is a Cobbler-managed domain workflow",
- "math-coordination: cobbler-managed-domain-workflow",
- "math-required-env: []",
- ],
- "references/council-provider-config.md": [
- "Math has its own Cobbler-managed domain workflow provider slots",
- "host-native or direct analysis is the fallback",
- "provider becomes required only when the project survival guide says",
- "so explicitly",
- ],
- "config.json.example": [
- '"coordination": "cobbler-managed-domain-workflow"',
- '"provider_policy": "native-first-with-optional-external-routes"',
- '"required_env": []',
- '"external_route_examples"',
- ],
- ".ai-docs/architecture.md": [
- "## Coordination hierarchy",
- "Elves executes",
- "Cobbler coordinates",
- "Domain workflows specialize",
- "Math is the first domain workflow",
- ],
- ".ai-docs/conventions.md": [
- "Cobbler is the default coordinator after an Elves invocation",
- "cobbler.default_for_session",
- "Math is a Cobbler-managed domain workflow",
- ],
- ".ai-docs/gotchas.md": [
- "Normal Cobbler and ordinary Elves must not require OpenRouter",
- "math-required-env: []",
- ],
- }
- DOMAIN_WORKFLOW_FORBIDDEN_PHRASES = {
- label: [
- "Elves can also run configurable mathematical research workflows",
- "OpenRouter is the baseline provider",
- "OpenRouter is the baseline model provider",
- "OpenRouter is the minimum useful setup",
- "Use OpenRouter first when no richer local setup exists",
- "math-provider-policy: openrouter-first",
- '"provider_policy": "openrouter-first"',
- "math-required-env:\n - OPENROUTER_API_KEY",
- '"required_env": ["OPENROUTER_API_KEY"]',
- ]
- for label in (
- "SKILL.md",
- "AGENTS.md",
- "README.md",
- "references/survival-guide-template.md",
- "references/tool-config-examples.md",
- "references/math-workflow.md",
- "references/math-provider-config.md",
- "references/math-plan-template.md",
- "references/math-review-prompts.md",
- "references/math-artifact-ledgers.md",
- "references/council-workflow.md",
- "references/council-provider-config.md",
- "config.json.example",
- )
- }
- DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS = {
- label: [
- r"\bmath\b[^.\n]*(?:peer|separate)\s+(?:coordinator|orchestrator|orchestration\s+layer)\b",
- r"\bmath\b[^.\n]*(?:requires|needs)\s+openrouter\b",
- r"\bopenrouter\b\s+is\s+required\s+for\s+math\b",
- r"\bopenrouter_api_key\b\s+(?:is\s+)?(?:required|must\s+be\s+set)\b",
- r"\bmath-required-env:\s*\n\s*-\s*OPENROUTER_API_KEY\b",
- ]
- for label in DOMAIN_WORKFLOW_FORBIDDEN_PHRASES
- }
- PUBLIC_API_SURFACE_SNAPSHOT_PHRASES = {
- ".gitignore": [
- ".elves/",
- ],
- "SKILL.md": [
- "Public API surface snapshots are optional regression evidence.",
- "Use existing structured sources before inventing scanners",
- "If no credible source exists, record `unavailable` with the reason instead of fabricating",
- "A missing snapshot source is not blocking unless `required: true` was explicitly set in the survival guide.",
- "`required: true` is valid only when explicitly set by the user or project survival guide.",
- "Do not infer required mode from project type, provider config, framework choice, or the presence of API files.",
- "Snapshot artifacts are run artifacts, not product docs",
- "Temporary snapshot artifacts should not remain in final product PR diffs unless the user explicitly",
- "Record shapes and field names, not secrets, bearer tokens, cookies, customer payloads, or production sample data.",
- "A snapshot proves public surface shape only; it is not a substitute for tests, E2E checks, review, or the human-owned constitution.",
- "public API surface delta when configured",
- ],
- "references/survival-guide-template.md": [
- "api-surface-snapshot:",
- "enabled: auto",
- "required: false",
- "Public API surface snapshots are optional regression evidence",
- "A missing snapshot source is not blocking unless required: true was explicitly set",
- "Snapshot artifacts are run artifacts, not product docs",
- ],
- "references/execution-log-template.md": [
- "Public API surface snapshot:",
- "N/A / unavailable reason / no delta / additive / planned breaking / unexpected breaking",
- ],
- "references/review-subagent.md": [
- "API surface snapshot artifacts when configured",
- "Public API surface snapshots",
- "optional regression evidence",
- "A missing snapshot source is not blocking unless `required: true` was explicitly set",
- "A snapshot proves public surface shape only; it is not a substitute",
- ],
- "references/kickoff-prompt-template.md": [
- "Configure optional public API surface snapshot behavior",
- "api-surface-snapshot.enabled: auto",
- "required: false",
- ".elves/api-surface/",
- ],
- "references/tool-config-examples.md": [
- "## Public API Surface Snapshot",
- "enabled: auto",
- "required: false",
- "Use existing structured sources before inventing scanners",
- "If no credible source exists, record `unavailable` with the reason instead of fabricating a snapshot",
- "A snapshot proves public surface shape only; it is not a substitute",
- ],
- "config.json.example": [
- '"api_surface_snapshot"',
- '"enabled": "auto"',
- '"required": false',
- '".elves/api-surface/baseline.json"',
- '"unexpected_breaking_change": "blocking"',
- "snapshots are regression evidence, not authority",
- ],
- "TODO.md": [
- "public API surfaces",
- "implemented `cobbler_runtime.public_api_snapshot` compatibility gate",
- ],
- }
- PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS = {
- label: [
- r"\bapi\s+snapshots?\s+(?:are|is)\s+required\b",
- r"\bmust\s+generate\s+an?\s+api\s+snapshot\b",
- r"\brequired:\s*true\s+by\s+default\b",
- r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\binfer\s+required\s+mode\b",
- r"\bsnapshots?\s+replace\s+(?:tests|the constitution|review)\b",
- r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\bcommit\s+snapshot\s+artifacts\b",
- r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\brecord\s+(?:raw\s+)?(?:secrets|bearer tokens|cookies|customer payloads|production sample data)\b",
- r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\bcapture\s+(?:raw\s+)?(?:secrets|bearer tokens|cookies|customer payloads|production sample data)\b",
- r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\binclude\s+(?:raw\s+)?(?:secrets|bearer tokens|cookies|customer payloads|production sample data)\b",
- ]
- for label in (
- "SKILL.md",
- "AGENTS.md",
- "README.md",
- "references/survival-guide-template.md",
- "references/execution-log-template.md",
- "references/review-subagent.md",
- "references/kickoff-prompt-template.md",
- "references/tool-config-examples.md",
- "config.json.example",
- )
- }
- COUNCIL_MODULE_PHRASES = {
- "README.md": [
- "/cobbler",
- "/setup-cobbler",
- "$elves cobbler: <task>",
- "Ask the Cobbler",
- "Codex users should not need or expect a top-level `/cobbler` command",
- "Council is a deprecated alias of Cobbler",
- ],
- "SKILL.md": [
- "## Cobbler",
- "Cobbler",
- "/cobbler",
- "$elves cobbler: <task>",
- "/council",
- "/ec",
- "/elves-council",
- "$elves council: <task>",
- "Host honesty matters",
- "do not assume Codex has a top-level `/cobbler` command",
- "Codex Goals are optional continuation plumbing",
- "not required for a Quick Cobbler answer",
- "default orchestration model",
- "Cobbler-first coordination is the default for Elves runs",
- "worker agents may edit the repo",
- "Quick Cobbler is the default one-off answer mode",
- "read-only",
- "stateless",
- "Codex subagents",
- "Claude Code subagents",
- "read-only lens analysis directly",
- "Optional model routing is role-scoped",
- "provider model such as `openrouter:<model-id>`",
- "resolve dissent by",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Risks",
- "Next move",
- "Confidence",
- "run state",
- "Provider-backed council is optional",
- "must not require",
- "vendor identity",
- ],
- "references/council-workflow.md": [
- "# Cobbler Workflow",
- "Cobbler is the default coordination layer",
- "Council is the compatibility path",
- "Claude Code primary: `/cobbler <task>`",
- "Codex primary: `$elves cobbler: <task>`",
- "Codex compatibility: `$elves council: <task>`",
- "Do not document Codex as having a top-level `/cobbler`",
- "Run Cobbler is the default coordination pattern inside an Elves run",
- "Worker agents may edit",
- "Quick Cobbler is the default one-off answer mode",
- "Quick Cobbler is the default one-off answer mode. It is always read-only and stateless",
- "Role agents do not see each other's reports before synthesis",
- "Run Cobbler reuses existing Elves memory surfaces",
- "Provider-backed council is not a third Cobbler mode",
- "use must not require OpenRouter",
- "Optional model routing is role-scoped",
- "fall back to native subagents",
- "model prestige",
- "Do not make Quick Cobbler require OpenRouter",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Risks",
- "Next move",
- "Confidence",
- "Do not create a separate PR, branch, survival guide, execution log, or ledger",
- ],
- "references/council-prompts.md": [
- "# Cobbler Prompt Templates",
- "Cobbler roles are lenses with obligations, not theatrical personas",
- "Do not read or rely on other role reports",
- "Work scope",
- "worker edit with assigned files",
- "Run Cobbler is the default coordination",
- "Return one fitted answer",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Next move",
- "why_this_fits",
- "strongest_dissent",
- "next_move",
- ],
- "references/council-provider-config.md": [
- "# Cobbler Provider-Backed Council Configuration",
- "Cobbler-first coordination is the default for Elves runs",
- "Normal Cobbler",
- "$elves cobbler: <task>",
- "use must work without",
- "Cobbler-first Elves runs and Quick Cobbler one-off answers need no provider configuration",
- "cobbler-coordination-default: cobbler-first",
- "cobbler-model-routing-policy: native-first",
- "provider:model-id",
- "fall back to native",
- "cobbler-provider-backed-required-env: []",
- "Do not make ordinary Cobbler or Council-compatible use",
- "Do not create a separate Council ledger",
- ],
- "references/codex-goals.md": [
- "Goals keeps Codex moving; Cobbler coordinates the Elves loop",
- "Codex Goals are not required for Quick Cobbler",
- "$elves cobbler: <task>",
- "Ask the Cobbler",
- "$elves council: <task>",
- "You only need a Quick Cobbler answer",
- "`survival_guide_path`",
- "`learnings_path`",
- "`plan_path`",
- "`execution_log_path`",
- "do not substitute generic filenames",
- ],
- "references/tool-config-examples.md": [
- "## Cobbler",
- "Default Cobbler coordination block for Elves runs",
- "Cobbler-first is the default orchestration",
- "Quick Cobbler requires no external provider",
- "cobbler-coordination-default: cobbler-first",
- "cobbler-default-backend: native-subagents",
- "cobbler-model-routing-policy: native-first",
- "cobbler-provider-backed-fallback: native-subagent-and-note",
- "openrouter:<model-id>",
- "low, medium, high, or xhigh",
- "cobbler-run-logging: existing-elves-memory",
- "cobbler-provider-backed-required-env: []",
- "Legacy `council-*` config keys remain compatibility aliases",
- ],
- "references/survival-guide-template.md": [
- "Coordination mode",
- "### Cobbler Coordination Defaults",
- "Cobbler-first coordination is the default for Elves runs",
- "Provider-backed council is optional",
- "cobbler-coordination-default: cobbler-first",
- "cobbler-default-backend: native-subagents",
- "cobbler-model-routing-policy: native-first",
- "cobbler-provider-backed-fallback: native-subagent-and-note",
- "openrouter:<model-id>",
- "low, medium, high, or xhigh",
- "cobbler-run-logging: existing-elves-memory",
- "cobbler-provider-backed-required-env: []",
- "Legacy `council-*` config keys remain compatibility aliases",
- ],
- "config.json.example": [
- '"cobbler"',
- '"council"',
- '"coordination_default": "cobbler-first"',
- '"default_for_elves_runs": true',
- '"primary_invocations"',
- '"default_answer_shape"',
- '"provider_backed_council"',
- '"compatibility_for": "cobbler"',
- '"precedence": "cobbler"',
- '"default_backend": "native-subagents"',
- '"quick_read_only": true',
- '"quick_stateless": true',
- '"run_logging": "existing-elves-memory"',
- '"model_routing_policy": "native-first"',
- '"fallback": "native-subagent-and-note"',
- '"external_route_example": "openrouter:<model-id>"',
- '"required_env": []',
- '"provider_policy": "optional-external-providers"',
- ],
- }
- COUNCIL_SECTION_HEADINGS = {
- "SKILL.md": "## Cobbler",
- "AGENTS.md": "## Cobbler",
- }
- CLAUDE_ALIAS_MARKER = "<!-- elves-managed-alias: claude-skill-alias v1 -->"
- CLAUDE_ALIAS_SKILL_PHRASES = {
- "aliases/claude/cobbler/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: cobbler",
- "/cobbler",
- "default orchestration model",
- "Use the installed `elves` skill",
- "For one-off Quick Cobbler answers, stay read-only and stateless",
- "worker agents may edit scoped files",
- "Claude Code subagents",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Next move",
- "must not require OpenRouter",
- ],
- "aliases/claude/cobbler-mode/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: cobbler-mode",
- "/cobbler-mode",
- "Cobbler Mode",
- "default orchestration model",
- "current-thread",
- "Cobbler Mode: on",
- "Cobbler Mode: off",
- "not durable run state",
- "For one-off Quick Cobbler answers, stay read-only and stateless",
- "worker agents may edit scoped files",
- "Claude Code subagents",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Next move",
- "must not require OpenRouter",
- ],
- "aliases/claude/setup-cobbler/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: setup-cobbler",
- "/setup-cobbler",
- "onboard plan|show|apply|probe",
- "Never stage",
- ".elves/models.toml",
- "must not require OpenRouter",
- ],
- "aliases/claude/setup-council/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: setup-council",
- "/setup-council",
- "onboard plan|show|apply|probe",
- "compatibility",
- "must not require OpenRouter",
- "Never stage",
- ],
- "aliases/claude/council/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: council",
- "/council",
- "compatibility alias",
- "default orchestration model",
- "installed `elves`",
- "For one-off Quick Cobbler answers, stay read-only and stateless",
- "worker agents may edit scoped files",
- "Claude Code subagents",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Next move",
- "must not require OpenRouter",
- ],
- "aliases/claude/ec/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: ec",
- "/ec",
- "compatibility alias",
- "default orchestration model",
- "installed `elves`",
- "For one-off Quick Cobbler answers, stay read-only and stateless",
- "worker agents may edit scoped files",
- "Claude Code subagents",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Next move",
- "must not require OpenRouter",
- ],
- "aliases/claude/elves-council/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: elves-council",
- "/elves-council",
- "compatibility alias",
- "default orchestration model",
- "installed `elves`",
- "For one-off Quick Cobbler answers, stay read-only and stateless",
- "worker agents may edit scoped files",
- "Claude Code subagents",
- "Recommendation",
- "Why this fits",
- "Strongest dissent",
- "Next move",
- "must not require OpenRouter",
- ],
- "aliases/claude/fugu/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: fugu",
- "/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>",
- "/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>",
- "Provider shortcut protocols",
- "run_fugu.sh",
- "codex-fugu",
- "fugu/high",
- "fugu-ultra-v1.1",
- "read-only",
- "non-ignored",
- "runner rejects `--write`",
- ],
- "aliases/claude/manus/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: manus",
- "/manus <topic>",
- "--wide",
- "--fanout",
- "--resume",
- "Cobbler",
- "Provider shortcut protocols",
- "run_manus.sh",
- "MANUS_API_KEY",
- "bounded wait",
- ],
- "aliases/claude/grok/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: grok",
- "/grok <instructions>",
- "Provider shortcut protocols",
- "run_grok.sh",
- "non-bypass permission posture",
- ],
- "aliases/claude/devin/SKILL.md": [
- CLAUDE_ALIAS_MARKER,
- "name: devin",
- "/devin <instructions>",
- "Provider shortcut protocols",
- "run_devin.sh",
- "DEVIN_API_KEY",
- "bounded wait",
- ],
- }
- CODEX_INSTALL_COBBLER_PHRASES = {
- "README.md": [
- "--target codex",
- "Do not invent top-level /cobbler",
- "Codex installs the main skill bundle only",
- "$elves cobbler: <task>",
- ],
- }
- COBBLER_CONFIG_PREFERENCE_PHRASES = {
- "README.md": [
- "Put new Cobbler preferences",
- "under the top-level `cobbler` block",
- "is for compatibility with older",
- "if both blocks are present, `cobbler` wins",
- ],
- "SKILL.md": [
- "Cobbler preferences belong under the top-level `cobbler` block",
- "if both blocks are present",
- "`cobbler` wins",
- ],
- "config.json.example": [
- '"precedence": "cobbler"',
- "If both blocks are present, cobbler wins",
- ],
- }
- COUNCIL_FORBIDDEN_PHRASES = {
- "README.md": [
- "ordinary `/council` requires OpenRouter",
- "normal `/council` requires OpenRouter",
- "ordinary Cobbler requires OpenRouter",
- "normal Cobbler requires OpenRouter",
- "Cobbler requires `OPENROUTER_API_KEY`",
- "Council requires `OPENROUTER_API_KEY`",
- "Cobbler is optional for Elves runs",
- "Cobbler only runs when invoked",
- "Run Cobbler is just Quick Cobbler inside a run",
- "Run Cobbler is Quick Cobbler inside an existing Elves run",
- "Use `/cobbler` in Codex",
- "Use `/council` in Codex",
- "Quick Cobbler requires Codex Goals",
- "Cobbler requires `/goal`",
- ],
- "SKILL.md": [
- "ordinary `/council` requires OpenRouter",
- "normal `/council` requires OpenRouter",
- "ordinary Cobbler requires OpenRouter",
- "normal Cobbler requires OpenRouter",
- "Cobbler requires `OPENROUTER_API_KEY`",
- "Council requires `OPENROUTER_API_KEY`",
- "Elves can also run Cobbler",
- "Cobbler is optional for Elves runs",
- "Cobbler only runs when invoked",
- "Run Cobbler is just Quick Cobbler inside a run",
- "Run Cobbler is Quick Cobbler inside an existing Elves run",
- "Use `/cobbler` in Codex",
- "Use `/council` in Codex",
- "Quick Cobbler requires Codex Goals",
- "Cobbler requires `/goal`",
- ],
- "AGENTS.md": [
- "ordinary `/council` requires OpenRouter",
- "normal `/council` requires OpenRouter",
- "ordinary Cobbler requires OpenRouter",
- "normal Cobbler requires OpenRouter",
- "Cobbler requires `OPENROUTER_API_KEY`",
- "Council requires `OPENROUTER_API_KEY`",
- "Elves can also run Cobbler",
- "Cobbler is optional for Elves runs",
- "Cobbler only runs when invoked",
- "Run Cobbler is just Quick Cobbler inside a run",
- "Run Cobbler is Quick Cobbler inside an existing Elves run",
- "Use `/cobbler` in Codex",
- "Use `/council` in Codex",
- "Quick Cobbler requires Codex Goals",
- "Cobbler requires `/goal`",
- ],
- "references/codex-goals.md": [
- "Quick Cobbler requires Codex Goals",
- "Cobbler requires `/goal`",
- "Use `/cobbler` in Codex",
- "Use `/council` in Codex",
- "docs/elves/survival-guide.md",
- "docs/plans/my-plan.md",
- "docs/elves/execution-log.md",
- ],
- "references/council-workflow.md": [
- "ordinary `/council` requires OpenRouter",
- "normal `/council` requires OpenRouter",
- "Council requires `OPENROUTER_API_KEY`",
- "Council can edit files",
- "Council can create branches",
- "Council can open PRs",
- "# Elves Council Workflow",
- "Quick Council is the default",
- "Run Council reuses existing Elves memory surfaces",
- "Deep Council is optional",
- "Do not make Quick Council require OpenRouter",
- "Quick Cobbler is read-only and stateless unless",
- "Quick Cobbler is the default one-off answer mode. It is read-only and stateless unless",
- "### Provider-Backed Council",
- ],
- "references/council-provider-config.md": [
- "ordinary `/council` requires OpenRouter",
- "normal `/council` requires OpenRouter",
- "Council requires `OPENROUTER_API_KEY`",
- "# Council Provider Configuration",
- "Quick Council needs no provider configuration",
- "Deep Council is opt-in",
- "council-deep-required-env",
- ],
- "references/council-prompts.md": [
- "# Elves Council Prompts",
- "Council roles are lenses with obligations",
- "You are synthesizing independent Elves Council reports",
- "Mode: [Quick Cobbler / Run Cobbler / Provider-backed council]",
- ],
- "references/tool-config-examples.md": [
- "## Elves Council",
- "Quick Council requires no external provider key",
- "Optional Deep Council provider diversity",
- "council-deep-required-env",
- ],
- "references/survival-guide-template.md": [
- "### Elves Council Configuration (optional)",
- "External providers are optional Deep Council",
- "Optional Deep Council provider diversity",
- "council-deep-required-env",
- ],
- }
- COBBLER_FORBIDDEN_PATTERNS = {
- label: [
- r"\bquick\s+cobbler\s+(?:needs|requires)\s+openrouter\b",
- r"\bnormal\s+cobbler\s+requires\s+(?:an\s+)?external\s+provider\s+key\b",
- r"\bcobbler\s+requires\s+openrouter\b",
- r"\bcouncil-compatible\s+use\s+requires\s+openrouter\b",
- r"\bopenrouter_api_key\b\s+is\s+required\s+for\s+cobbler\b",
- r"\bcobbler\s+is\s+optional\s+for\s+elves\s+runs\b",
- r"\bcobbler\s+only\s+runs\s+when\s+invoked\b",
- r"\brun\s+cobbler\s+is\s+(?:just\s+)?quick\s+cobbler\s+inside\s+(?:an?\s+)?(?:active\s+)?(?:elves\s+)?run\b",
- r"\bquick\s+cobbler\b[^.\n]*(?:unless|except)\b[^.\n]*(?:active\s+elves\s+run|implementation|edit|mutate)\b",
- r"\bcobbler\s+mode\s+persists\s+across\s+threads\b",
- r"\bcobbler\s+mode\s+starts\s+an?\s+elves\s+run\b",
- r"\bcobbler\s+mode\s+requires\s+codex\s+goals\b",
- r"\bcobbler\s+mode\s+can\s+edit\s+files\s+by\s+default\b",
- r"\buse\s+`?/cobbler-mode`?\s+in\s+codex\b",
- ]
- for label in (
- "SKILL.md",
- "AGENTS.md",
- "README.md",
- "references/council-workflow.md",
- "references/council-provider-config.md",
- "references/tool-config-examples.md",
- "references/survival-guide-template.md",
- "config.json.example",
- "aliases/claude/cobbler/SKILL.md",
- "aliases/claude/cobbler-mode/SKILL.md",
- "aliases/claude/council/SKILL.md",
- "aliases/claude/ec/SKILL.md",
- "aliases/claude/elves-council/SKILL.md",
- )
- }
- COBBLER_MODE_PHRASES = {
- "SKILL.md": [
- "Cobbler Mode is the lowest-friction way",
- "/cobbler-mode",
- "$elves cobbler-mode",
- "Cobbler Mode: on",
- "Cobbler Mode: off",
- "current-thread conversation state",
- "not durable run state",
- "daemon",
- "Codex slash command",
- ],
- "references/council-workflow.md": [
- "### Cobbler Mode",
- "not a third Cobbler behavior mode",
- "/cobbler-mode",
- "$elves cobbler-mode",
- "Cobbler Mode: on",
- "Cobbler Mode: off",
- "current-thread conversation state",
- "not durable run state",
- "branch, PR, survival guide, execution log, Codex Goal",
- ],
- "aliases/claude/cobbler-mode/SKILL.md": [
- "name: cobbler-mode",
- "/cobbler-mode",
- "Cobbler Mode",
- "default orchestration model",
- "current-thread",
- "Cobbler Mode: on",
- "Cobbler Mode: off",
- "not durable run state",
- "daemon",
- ],
- }
- COBBLER_HARNESS_LOOP_PHRASES = {
- "SKILL.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "present/record",
- "reclassify",
- ],
- "docs/cobbler.md": [
- "capability scan",
- "Route and medium selection",
- "Context packet",
- "Execute agents/tools/skills",
- "Collect evidence",
- "Fit answer",
- "Present/record",
- "Reclassify",
- "does not copy Fable's model identity",
- ],
- "references/council-workflow.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "Present/record",
- "Reclassify",
- ],
- "references/council-prompts.md": [
- "Capability scan",
- "Route and medium",
- "Context packet",
- "Evidence",
- "Present/record",
- "Reclassify",
- ],
- "references/tool-config-examples.md": [
- "cobbler-harness-loop",
- "capability-scan",
- "route-and-medium-selection",
- "context-packet",
- "execute-agents-tools-skills",
- "collect-evidence",
- "fit-answer",
- "present-record",
- "reclassify",
- ],
- "references/survival-guide-template.md": [
- "cobbler-harness-loop",
- "capability-scan",
- "route-and-medium-selection",
- "context-packet",
- "execute-agents-tools-skills",
- "collect-evidence",
- "fit-answer",
- "present-record",
- "reclassify",
- ],
- "config.json.example": [
- '"harness_loop"',
- '"capability_scan"',
- '"route_and_medium_selection"',
- '"context_packet"',
- '"execute_agents_tools_skills"',
- '"collect_evidence"',
- '"fit_answer"',
- '"present_record"',
- '"reclassify"',
- ],
- "aliases/claude/cobbler/SKILL.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "present/record",
- "reclassify",
- ],
- "aliases/claude/cobbler-mode/SKILL.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "present/record",
- "reclassify",
- ],
- "aliases/claude/council/SKILL.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "present/record",
- "reclassify",
- ],
- "aliases/claude/ec/SKILL.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "present/record",
- "reclassify",
- ],
- "aliases/claude/elves-council/SKILL.md": [
- "capability scan",
- "route and medium selection",
- "context packet",
- "execute agents/tools/skills",
- "collect evidence",
- "fit answer",
- "present/record",
- "reclassify",
- ],
- }
- COBBLER_HARNESS_DRIFT_PATTERNS = {
- label: [
- r"\bquick\s+cobbler\b[^.\n]*(?:edits|mutates|commits|pushes|opens\s+prs)\b",
- r"\bcontext\s+packet\b[^.\n]*(?:includes|contains)\s+(?:secrets|tokens|credentials|cookies)\b",
- r"\bprovider-backed\s+council\b[^.\n]*(?:required|default)\b",
- r"\breclassify\b[^.\n]*(?:by\s+changing\s+run\s+state|by\s+creating\s+a\s+new\s+run)\b",
- ]
- for label in COBBLER_HARNESS_LOOP_PHRASES
- }
- FULL_RUN_MODEL_ROUTING_PHRASES = {
- "SKILL.md": [
- "Full-run model routing is a separate optional staging preference",
- "`model-routing` phase preferences",
- "native-first by default",
- "requested route, actual route, and material fallback reason",
- "`requested_route`, `actual_route`, and `fallback_reason`",
- "Missing optional provider access",
- "`required: true`",
- ],
- "references/survival-guide-template.md": [
- "### Full-Run Model Routing (optional)",
- "policy: native-first",
- "fallback: host-native",
- "implement-model: strongest-host-native",
- "JSON keys: requested_route, actual_route, fallback_reason",
- ],
- "references/execution-log-template.md": [
- "**Phase routing (optional):**",
- "Requested route",
- "Actual route",
- "Fallback reason",
- ],
- "references/review-subagent.md": [
- "## Phase Route Context",
- "requested route, actual route, and fallback reason",
- "required: true",
- "Missing optional provider access is not a",
- ],
- "references/tool-config-examples.md": [
- "## Full-Run Model Routing",
- "model-routing:",
- "native-subagent, host-default",
- "openrouter:<model-id>",
- "Do not treat bare aliases as provider model IDs",
- ],
- "references/council-workflow.md": [
- "Run Cobbler is not the same thing as full-run model routing",
- "requested route, actual route, and material fallback reason",
- "separate council ledger",
- ],
- "references/council-prompts.md": [
- "Full-run model routing belongs to Elves run control",
- "not the Quick Cobbler role selector",
- ],
- "references/council-provider-config.md": [
- "## Full-Run Phase Routes",
- "Provider-backed council slots may satisfy read-only full-run model-routing phases",
- "Do not make implementation provider-backed by default",
- "route, actual route, and fallback reason",
- ],
- "config.json.example": [
- '"model_routing"',
- '"policy": "native-first"',
- '"fallback": "host-native"',
- '"required": false',
- '"provider_backed_allowed": false',
- '"log_material_fallbacks": true',
- ],
- }
- FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES = {
- label: [
- "ordinary Elves requires OpenRouter",
- "normal Elves requires OpenRouter",
- "model-routing requires OpenRouter",
- "full-run model routing requires OpenRouter",
- "required: true is the default",
- "route mismatch is always blocking",
- "implementation routes to external providers by default",
- "Quick Cobbler uses model-routing",
- ]
- for label in (
- "SKILL.md",
- "AGENTS.md",
- "README.md",
- "references/survival-guide-template.md",
- "references/execution-log-template.md",
- "references/review-subagent.md",
- "references/tool-config-examples.md",
- "references/council-workflow.md",
- "references/council-prompts.md",
- "references/council-provider-config.md",
- "config.json.example",
- )
- }
- FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS = {
- label: [
- r"\bfull-run\s+model\s+routing\s+requires\s+(?:an\s+)?external\s+provider\s+key\b",
- r"\bmodel-routing\s+requires\s+openrouter\b",
- r"\brequired:\s*true\s+is\s+(?:the\s+)?default\b",
- r"(?<!do not )\bmake\s+implementation\s+provider-backed\s+by\s+default\b",
- ]
- for label in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES
- }
- # Who implements: host-native default + optional external implementer / host-import writer.
- IMPLEMENTATION_LANES_PHRASES = {
- "SKILL.md": [
- "### Who implements (native default, optional extras)",
- "Default: host-native only",
- "Vanilla Cobbler uses whatever host is running the skill",
- "same pattern as the math module",
- "implementation_lane: fast | untrusted",
- "cobbler_agents.py implement prepare|launch|gate|resume-batch|status",
- "references/grok-implementer-launch-prompt.md",
- "the default overnight path",
- "cobbler_agents.py worker",
- "Do not invent top-level Codex slash commands",
- ],
- "CHANGELOG.md": [
- "### Optional external batch implementer",
- "implementation_lane: fast | untrusted",
- "cobbler_agents.py implement prepare|launch|gate|resume-batch|status",
- "references/grok-implementer-launch-prompt.md",
- "not the default overnight path",
- "### Docs: native-first implement framing",
- "vanilla Cobbler is host-native",
- ],
- "references/grok-implementer-launch-prompt.md": [
- "This is not the Elves default",
- "implementation_lane: fast | untrusted",
- "cobbler_agents.py implement prepare",
- "not** use that lease path as the default",
- "Omit `implementation_lane` entirely for host-native runs",
- ],
- "references/councilelves-launch-prompt.md": [
- "Vanilla path",
- "Claude Code or Codex out of the box",
- "implementation_lane: fast | untrusted",
- "cobbler_agents.py implement prepare|launch|gate|resume-batch|status",
- "not** use the untrusted lease path as the default overnight",
- "cobbler_agents.py worker",
- ],
- }
- # External-agent setup (v1.20.0 Batch 5).
- SETUP_COBBLER_PHRASES = {
- "SKILL.md": [
- "### External-agent setup and model onboarding",
- "Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp)",
- "bounded live qualification canary",
- "/setup-cobbler",
- "/setup-council",
- "$elves setup-cobbler",
- "$elves setup-council",
- "not a top-level",
- "cobbler_agents.py onboard",
- "cobbler_agents.py setup",
- ".elves/models.toml",
- "references/model-onboarding.md",
- "references/cobbler-setup-recipes.md",
- ],
- "docs/cobbler.md": [
- "/setup-cobbler",
- "/setup-council",
- "$elves setup-cobbler",
- "$elves setup-council",
- "model onboarding",
- "cobbler-setup-recipes.md",
- "model-onboarding.md",
- "Never stage",
- ],
- "references/cobbler-setup-recipes.md": [
- "/setup-cobbler",
- "/setup-council",
- "$elves setup-cobbler",
- "onboard plan",
- "verified",
- "experimental",
- "custom",
- "OPENROUTER_API_KEY",
- "native-only",
- "remaining_quota",
- "Never stage",
- ],
- "references/model-onboarding.md": [
- "Model Onboarding",
- "Claude Code, Codex, Grok Build, and Oh My Pi",
- "Supported hosts (main drivers)",
- "not been our focus",
- "many have not been heavily",
- "Antigravity CLI",
- "Prefer a PR",
- "onboard plan",
- "onboard apply",
- "onboard probe",
- "Never stage",
- "host-native",
- ],
- "aliases/claude/setup-cobbler/SKILL.md": [
- "model onboarding",
- "onboard plan|show|apply|probe",
- "Never stage",
- ".elves/models.toml",
- "must not require OpenRouter",
- ],
- }
- # Coordinator-to-implementer handoff + git-history-as-operator-UI standards (v1.20.0 Batch 1).
- IMPLEMENTER_HANDOFF_PHRASES = {
- "SKILL.md": [
- "## Coordinator-to-Implementer Handoff Standard",
- "intent / why",
- "Build On targets",
- "owned surfaces",
- "forbidden surfaces",
- "acceptance evidence",
- "failure modes / pitfalls",
- "HEAD / run-doc paths / route-session identity / output format",
- "blocking coordinator defect",
- ],
- "references/plan-template.md": [
- "Coordinator-to-implementer handoff",
- "Build On targets",
- "Owned surfaces",
- "Forbidden surfaces",
- "acceptance evidence",
- "Failure modes / pitfalls",
- "HEAD / run-doc paths / route-session identity / output format",
- ],
- "references/survival-guide-template.md": [
- "Coordinator-to-implementer handoff",
- "Build On targets",
- "owned surfaces",
- "forbidden surfaces",
- "acceptance evidence",
- ],
- "references/execution-log-template.md": [
- "Handoff standard",
- "Build On targets",
- "owned surfaces",
- "forbidden surfaces",
- "acceptance evidence",
- ],
- "references/review-subagent.md": [
- "Coordinator-to-implementer handoff obligations",
- "blocking coordinator defect",
- "Build On targets",
- "owned surfaces",
- "forbidden surfaces",
- "acceptance evidence",
- ],
- }
- RISK_TIER_PHRASES = {
- "SKILL.md": [
- "Thin safety kernel",
- "validate once, verify changes, attest final",
- "low | standard | high",
- "trusted | untrusted",
- "touched surfaces",
- "risk checkpoints",
- "terminal readiness",
- "exact HEAD",
- "impact-selected",
- ],
- "references/joyful-runs-contract.md": [
- "low",
- "standard",
- "high",
- "trusted",
- "untrusted",
- "ready=true never grants merge permission",
- ],
- "references/proof-and-review.md": [
- "validate once, verify changes, attest final",
- "impact path",
- "delta re-review",
- ],
- }
- PROGRESS_COMMIT_PHRASES = {
- "SKILL.md": [
- "## Git History as Operator UI",
- "[<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>",
- "Forbid vague subjects",
- "audited detached handoff commits",
- "never own refs, remotes, push, PRs, or canonical run memory",
- "Reserve the `Close` phase for acceptance-backed batch completion",
- "Protected refs, PR operations, and merge never dispatch model inference",
- ],
- "references/plan-template.md": [
- "Contract|Implement|Validate|Review|Close",
- "Forbid vague subjects",
- "audited detached handoff commits",
- "never own refs/remotes/push/PR/run-memory",
- "Close` requires",
- ],
- "references/survival-guide-template.md": [
- "Contract|Implement|Validate|Review|Close",
- "Forbid vague subjects",
- "audited detached handoff commits",
- "Close` requires acceptance",
- "Git/PR ops never dispatch model inference",
- ],
- "references/execution-log-template.md": [
- "Contract|Implement|Validate|Review|Close",
- "forbid vague subjects",
- "audited detached handoff commits",
- "never own refs/remotes/push/PR/run-memory",
- ],
- "references/review-subagent.md": [
- "Git history as operator UI",
- "Contract|Implement|Validate|Review|Close",
- "audited detached handoff commits",
- "Close` appears only with acceptance evidence",
- "did not dispatch model inference",
- ],
- }
- # Vague subjects must remain present as anti-pattern examples on skill mirrors.
- PROGRESS_COMMIT_ANTIPATTERN_EXAMPLES = {
- "SKILL.md": [
- "[feat/payments · Batch 3/12] Updates",
- "[feat/payments · Batch 3/12 · Implement] progress",
- "[feat/payments · Batch 3/12 · Implement] WIP",
- "[feat/payments · Batch 3/12 · Implement] fixes",
- ],
- }
- PUBLIC_WORDING_FILES = [
- REPO_ROOT / "SKILL.md",
- REPO_ROOT / "AGENTS.md",
- REPO_ROOT / "README.md",
- REPO_ROOT / "CHANGELOG.md",
- REPO_ROOT / "config.json.example",
- ]
- PUBLIC_WORDING_FORBIDDEN_PHRASES = [
- # Exact model names are valid in the route-identity contract. Keep
- # prohibiting branding/persona claims that describe Cobbler as Fable-like.
- "Fable-like",
- "Fable-style",
- "inspired by Fable",
- "Fable-powered",
- "cobbled together",
- "cobbled-together",
- ]
- # Persona claims that describe Cobbler as *being* Fable (or other host models as
- # product personas), matched case-insensitively. Bare model identifiers
- # (`Fable 5`, `claude-fable-5`, route tables) remain legitimate and must not match.
- PUBLIC_WORDING_FORBIDDEN_PATTERNS = [
- r"powered\s+by\s+fable",
- r"built\s+on\s+fable",
- r"backed\s+by\s+fable",
- r"driven\s+by\s+fable",
- r"runs\s+on\s+fable",
- r"fable\s+under\s+the\s+hood",
- r"fable\s+persona",
- # "is Fable" / "is a Fable …" product-persona claims (not "Fable 5 model").
- r"\bis\s+(?:a\s+)?fable(?:\s+model|\s+persona|\s+agent)?\b(?!\s*[0-9])",
- # Claude/Anthropic persona claims for Cobbler/Elves product identity.
- r"powered\s+by\s+claude",
- r"powered\s+by\s+anthropic",
- r"claude\s+persona",
- r"anthropic\s+persona",
- ]
- # --- Elves 2.3: thin AGENTS adapter + compact SKILL pins ---
- _AGENTS_THIN_POINTER = [
- 'thin Codex adapter',
- 'canonical workflow is',
- 'SKILL.md',
- 'Codex Goals',
- 'Grok Build goal mode',
- 'chat-to-work',
- 'chat-to-land',
- 'plan Acceptance with proof',
- 'Stop Gate',
- 'continuation_guard',
- '\\land-pr',
- '/land-pr',
- 'source-checkout shorthand',
- 'active Elves skill root',
- '$ELVES_SKILL_ROOT/scripts/elves_landing_check.py',
- '--session <session-path> --repo-root .',
- 'Build On',
- 'owned surfaces',
- 'forbidden surfaces',
- 'acceptance evidence',
- 'blocking coordinator defect',
- 'Contract|Implement|Validate|Review|Close',
- 'Forbid vague subjects',
- '[feat/auth · Batch 3/12] Updates',
- '[feat/auth · Batch 3/12 · Implement] progress',
- 'One run owns one branch and one checkout',
- 'optional regression evidence',
- ]
- # One whole-file thin-adapter check replaces the per-corpus AGENTS.md shims:
- # AGENTS.md is a pointer file, so it carries each contract's NAME exactly once
- # and the corpora that own the contracts no longer pin AGENTS.md separately.
- AGENTS_POINTER_PHRASES = {"AGENTS.md": list(_AGENTS_THIN_POINTER)}
- if isinstance(COUNCIL_MODULE_PHRASES, dict):
- COUNCIL_MODULE_PHRASES = dict(COUNCIL_MODULE_PHRASES)
- COUNCIL_MODULE_PHRASES["AGENTS.md"] = [
- "$elves cobbler: <task>",
- "$elves council: <task>",
- "Ask the Cobbler",
- "Codex Goals",
- "Grok Build goal mode",
- "capability-proven enhancement",
- "one-packet fallback",
- "authenticated live catalog",
- ]
- if isinstance(COBBLER_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in COBBLER_FORBIDDEN_PATTERNS:
- COBBLER_FORBIDDEN_PATTERNS = {k: v for k, v in COBBLER_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(COBBLER_HARNESS_DRIFT_PATTERNS, dict) and 'AGENTS.md' in COBBLER_HARNESS_DRIFT_PATTERNS:
- COBBLER_HARNESS_DRIFT_PATTERNS = {k: v for k, v in COBBLER_HARNESS_DRIFT_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS:
- DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS = {k: v for k, v in DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS:
- EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS = {k: v for k, v in EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS:
- FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS = {k: v for k, v in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS:
- INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS = {k: v for k, v in INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(LANDING_CHECK_BARE_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in LANDING_CHECK_BARE_FORBIDDEN_PATTERNS:
- LANDING_CHECK_BARE_FORBIDDEN_PATTERNS = {k: v for k, v in LANDING_CHECK_BARE_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS:
- PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS = {k: v for k, v in PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(SINGLE_KICKOFF_UNSCOPED_PATTERNS, dict) and 'AGENTS.md' in SINGLE_KICKOFF_UNSCOPED_PATTERNS:
- SINGLE_KICKOFF_UNSCOPED_PATTERNS = {k: v for k, v in SINGLE_KICKOFF_UNSCOPED_PATTERNS.items() if k != 'AGENTS.md'}
- if isinstance(COUNCIL_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in COUNCIL_FORBIDDEN_PHRASES:
- COUNCIL_FORBIDDEN_PHRASES = {k: v for k, v in COUNCIL_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
- if isinstance(DOMAIN_WORKFLOW_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in DOMAIN_WORKFLOW_FORBIDDEN_PHRASES:
- DOMAIN_WORKFLOW_FORBIDDEN_PHRASES = {k: v for k, v in DOMAIN_WORKFLOW_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
- if isinstance(FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES:
- FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES = {k: v for k, v in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
- if isinstance(REVIEWED_PR_LANDING_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in REVIEWED_PR_LANDING_FORBIDDEN_PHRASES:
- REVIEWED_PR_LANDING_FORBIDDEN_PHRASES = {k: v for k, v in REVIEWED_PR_LANDING_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
- if isinstance(SINGLE_KICKOFF_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in SINGLE_KICKOFF_FORBIDDEN_PHRASES:
- SINGLE_KICKOFF_FORBIDDEN_PHRASES = {k: v for k, v in SINGLE_KICKOFF_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
- if isinstance(ACCEPTANCE_EVIDENCE_PHRASES, dict) and 'SKILL.md' in ACCEPTANCE_EVIDENCE_PHRASES:
- ACCEPTANCE_EVIDENCE_PHRASES = dict(ACCEPTANCE_EVIDENCE_PHRASES)
- ACCEPTANCE_EVIDENCE_PHRASES['SKILL.md'] = ['plan Acceptance with proof', 'acceptance', 'elves_landing_check.py', 'God-file', 'one batch per close commit']
- if isinstance(COBBLER_CONFIG_PREFERENCE_PHRASES, dict) and 'SKILL.md' in COBBLER_CONFIG_PREFERENCE_PHRASES:
- COBBLER_CONFIG_PREFERENCE_PHRASES = dict(COBBLER_CONFIG_PREFERENCE_PHRASES)
- COBBLER_CONFIG_PREFERENCE_PHRASES['SKILL.md'] = ['config.json', 'cobbler', 'council']
- if isinstance(COBBLER_HARNESS_LOOP_PHRASES, dict) and 'SKILL.md' in COBBLER_HARNESS_LOOP_PHRASES:
- COBBLER_HARNESS_LOOP_PHRASES = dict(COBBLER_HARNESS_LOOP_PHRASES)
- COBBLER_HARNESS_LOOP_PHRASES['SKILL.md'] = ['capability scan', 'context packet', 'Cobbler-first', 'fit answer']
- if isinstance(COBBLER_MODE_PHRASES, dict) and 'SKILL.md' in COBBLER_MODE_PHRASES:
- COBBLER_MODE_PHRASES = dict(COBBLER_MODE_PHRASES)
- COBBLER_MODE_PHRASES['SKILL.md'] = ['Cobbler Mode', 'cobbler-mode', 'not durable run state']
- if isinstance(COUNCIL_MODULE_PHRASES, dict) and 'SKILL.md' in COUNCIL_MODULE_PHRASES:
- COUNCIL_MODULE_PHRASES = dict(COUNCIL_MODULE_PHRASES)
- COUNCIL_MODULE_PHRASES['SKILL.md'] = ['## Cobbler', '/cobbler', '$elves cobbler', 'Quick Cobbler', 'native-subagent-first', 'Cobbler-first coordination is the default for Elves runs', '$elves council: <task>', 'Host honesty matters', 'do not assume Codex has a top-level `/cobbler` command', 'Codex Goals are optional continuation plumbing', 'not required for a Quick Cobbler answer', 'default orchestration model', 'worker agents may edit the repo', 'Quick Cobbler is the default one-off answer mode', '/council', '/ec', '/elves-council']
- if isinstance(DOMAIN_WORKFLOW_PHRASES, dict) and 'SKILL.md' in DOMAIN_WORKFLOW_PHRASES:
- DOMAIN_WORKFLOW_PHRASES = dict(DOMAIN_WORKFLOW_PHRASES)
- DOMAIN_WORKFLOW_PHRASES['SKILL.md'] = ['**Elves** is the execution system', '**Cobbler** is the default coordinator', '**Domain workflows** are specialized Cobbler-managed packs', '**Math** is the first domain workflow', '**Providers** are optional role routes', 'cobbler.default_for_session']
- if isinstance(EFFORT_GUARDRAIL_PHRASES, dict) and 'SKILL.md' in EFFORT_GUARDRAIL_PHRASES:
- EFFORT_GUARDRAIL_PHRASES = dict(EFFORT_GUARDRAIL_PHRASES)
- EFFORT_GUARDRAIL_PHRASES['SKILL.md'] = [
- '## Effort Standard',
- 'Work as hard as you can',
- 'plan acceptance and blockers',
- 'deferred hygiene',
- ]
- if isinstance(ELVES_REPORT_PHRASES, dict) and 'SKILL.md' in ELVES_REPORT_PHRASES:
- ELVES_REPORT_PHRASES = dict(ELVES_REPORT_PHRASES)
- ELVES_REPORT_PHRASES['SKILL.md'] = ['## Elves Report', 'problems found', 'lessons learned', '/tmp/elves-report-<repo-slug>-<yyyy-mm-dd>.html', 'references/elves-report-template.html', 'collapsible `<details>` sections', 'committed examples and reusable templates non-identifying', 'Elves Report path']
- if isinstance(FINAL_READINESS_REVIEW_PHRASES, dict) and 'SKILL.md' in FINAL_READINESS_REVIEW_PHRASES:
- FINAL_READINESS_REVIEW_PHRASES = dict(FINAL_READINESS_REVIEW_PHRASES)
- FINAL_READINESS_REVIEW_PHRASES['SKILL.md'] = ['Final Readiness Review', 'git diff <default-branch>...HEAD', 'review subagent']
- if isinstance(FULL_RUN_MODEL_ROUTING_PHRASES, dict) and 'SKILL.md' in FULL_RUN_MODEL_ROUTING_PHRASES:
- FULL_RUN_MODEL_ROUTING_PHRASES = dict(FULL_RUN_MODEL_ROUTING_PHRASES)
- FULL_RUN_MODEL_ROUTING_PHRASES['SKILL.md'] = ['model routing', 'native-first', 'fallback', 'Missing optional provider access']
- if isinstance(IMPLEMENTATION_LANES_PHRASES, dict) and 'SKILL.md' in IMPLEMENTATION_LANES_PHRASES:
- IMPLEMENTATION_LANES_PHRASES = dict(IMPLEMENTATION_LANES_PHRASES)
- IMPLEMENTATION_LANES_PHRASES['SKILL.md'] = ['trusted Grok', 'full-run', 'parked', 'untrusted', 'Do not invent top-level Codex slash commands', 'implementation_lane: fast | untrusted']
- if isinstance(IMPLEMENTER_HANDOFF_PHRASES, dict) and 'SKILL.md' in IMPLEMENTER_HANDOFF_PHRASES:
- IMPLEMENTER_HANDOFF_PHRASES = dict(IMPLEMENTER_HANDOFF_PHRASES)
- IMPLEMENTER_HANDOFF_PHRASES['SKILL.md'] = ['Build On', 'owned surfaces', 'forbidden surfaces', 'acceptance evidence', 'blocking coordinator defect', 'HEAD / run-doc paths / route-session identity / output format']
- if isinstance(INSTALLED_HELPER_PATH_PHRASES, dict) and 'SKILL.md' in INSTALLED_HELPER_PATH_PHRASES:
- INSTALLED_HELPER_PATH_PHRASES = dict(INSTALLED_HELPER_PATH_PHRASES)
- INSTALLED_HELPER_PATH_PHRASES['SKILL.md'] = ['source-checkout shorthand', 'active Elves skill root', '~/.claude/skills/elves', '~/.codex/skills/elves', '~/.grok/skills/elves', '~/.omp/agent/skills/elves', '$ELVES_SKILL_ROOT/scripts/acceptance_contract.py', '$ELVES_SKILL_ROOT/scripts/elves_landing_check.py', 'installed Elves bundle never requires a repo-only helper']
- if isinstance(LANDING_CHECK_CONTRACT_PHRASES, dict) and 'SKILL.md' in LANDING_CHECK_CONTRACT_PHRASES:
- LANDING_CHECK_CONTRACT_PHRASES = dict(LANDING_CHECK_CONTRACT_PHRASES)
- LANDING_CHECK_CONTRACT_PHRASES['SKILL.md'] = ['$ELVES_SKILL_ROOT/scripts/elves_landing_check.py', '--session <session-path> --repo-root .', 'plan_path', 'equality assertion']
- if isinstance(MATH_MODULE_PHRASES, dict) and 'SKILL.md' in MATH_MODULE_PHRASES:
- MATH_MODULE_PHRASES = dict(MATH_MODULE_PHRASES)
- MATH_MODULE_PHRASES['SKILL.md'] = ['Cobbler-managed Elves domain workflow', 'Discovery Sprint', 'Native host subagents or direct analysis are the default', 'useful optional math role preset', 'Google Cloud AlphaEvolve', 'math-alphaevolve.md', 'Never treat model output']
- if isinstance(MEMORY_HYGIENE_PHRASES, dict) and 'SKILL.md' in MEMORY_HYGIENE_PHRASES:
- MEMORY_HYGIENE_PHRASES = dict(MEMORY_HYGIENE_PHRASES)
- MEMORY_HYGIENE_PHRASES['SKILL.md'] = ['## Strategic Forgetting', 'chats are for execution', 'memory and resource hygiene']
- if isinstance(NONSTOP_GUARDRAIL_PHRASES, dict) and 'SKILL.md' in NONSTOP_GUARDRAIL_PHRASES:
- NONSTOP_GUARDRAIL_PHRASES = dict(NONSTOP_GUARDRAIL_PHRASES)
- NONSTOP_GUARDRAIL_PHRASES['SKILL.md'] = ['Stop Gate', 'continuation_guard', 'After every host-owned commit and push, re-read the survival guide before doing anything else.', 'Do not wait for user acknowledgment']
- if isinstance(PROGRESS_COMMIT_PHRASES, dict) and 'SKILL.md' in PROGRESS_COMMIT_PHRASES:
- PROGRESS_COMMIT_PHRASES = dict(PROGRESS_COMMIT_PHRASES)
- PROGRESS_COMMIT_PHRASES['SKILL.md'] = ['## Git History as Operator UI', '[<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>', 'Forbid vague subjects', 'audited detached handoff commits', 'never own refs, remotes, push, PRs, or canonical run memory', 'Protected refs, PR operations, and merge never dispatch model inference']
- if isinstance(PUBLIC_API_SURFACE_SNAPSHOT_PHRASES, dict) and 'SKILL.md' in PUBLIC_API_SURFACE_SNAPSHOT_PHRASES:
- PUBLIC_API_SURFACE_SNAPSHOT_PHRASES = dict(PUBLIC_API_SURFACE_SNAPSHOT_PHRASES)
- PUBLIC_API_SURFACE_SNAPSHOT_PHRASES['SKILL.md'] = ['Public API surface snapshots are optional regression evidence.', 'Use existing structured sources before inventing scanners', 'If no credible source exists, record `unavailable` with the reason instead of fabricating', 'A missing snapshot source is not blocking unless `required: true` was explicitly set in the survival guide.', '`required: true` is valid only when explicitly set by the user or project survival guide.', 'Do not infer required mode from project type, provider config, framework choice, or the presence of API files.', 'Snapshot artifacts are run artifacts, not product docs', 'Temporary snapshot artifacts should not remain in final product PR diffs unless the user explicitly', 'Record shapes and field names, not secrets, bearer tokens, cookies, customer payloads, or production sample data.', 'A snapshot proves public surface shape only; it is not a substitute for tests, E2E checks, review, or the human-owned constitution.', 'public API surface delta when configured']
- if isinstance(REVIEWED_PR_LANDING_PHRASES, dict) and 'SKILL.md' in REVIEWED_PR_LANDING_PHRASES:
- REVIEWED_PR_LANDING_PHRASES = dict(REVIEWED_PR_LANDING_PHRASES)
- REVIEWED_PR_LANDING_PHRASES['SKILL.md'] = ['## Reviewed PR Landing Command', 'gh pr merge --merge', '\\land-pr', '/land-pr', 'default when bots are expected', 'Fugu review of the current PR diff, when needed and authorized', '$elves fugu review', 'Never invent a raw Fugu call', 'A landing request alone does not authorize a paid Fugu call', 'bump the version when the repository versions', '**Can it merge?**', '**Was it tested?**', 'Local tests passed on <head SHA>', 'never count as tested', 'same-day back-merge PR']
- if isinstance(RISK_TIER_PHRASES, dict) and 'SKILL.md' in RISK_TIER_PHRASES:
- RISK_TIER_PHRASES = dict(RISK_TIER_PHRASES)
- RISK_TIER_PHRASES['SKILL.md'] = ['Thin safety kernel', 'validate once, verify changes, attest final', 'low | standard | high', 'trusted | untrusted', 'touched surfaces', 'risk checkpoints', 'terminal readiness', 'exact HEAD', 'impact-selected']
- if isinstance(SETUP_COBBLER_PHRASES, dict) and 'SKILL.md' in SETUP_COBBLER_PHRASES:
- SETUP_COBBLER_PHRASES = dict(SETUP_COBBLER_PHRASES)
- SETUP_COBBLER_PHRASES['SKILL.md'] = ['setup-cobbler', 'setup-council', 'model-onboarding.md', 'not a top-level', 'cobbler_agents.py setup', 'references/cobbler-setup-recipes.md', 'Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp)', 'bounded live qualification canary', '$elves setup-council']
- if isinstance(SINGLE_KICKOFF_PHRASES, dict) and 'SKILL.md' in SINGLE_KICKOFF_PHRASES:
- SINGLE_KICKOFF_PHRASES = dict(SINGLE_KICKOFF_PHRASES)
- SINGLE_KICKOFF_PHRASES['SKILL.md'] = ['Default user path: one kickoff', 'Trusted full-run delegation keeps that path', 'chat-to-work', 'chat-to-land', 'Legacy two-call', 'full-run', 'parked']
- if isinstance(WORKSPACE_ISOLATION_PHRASES, dict) and 'SKILL.md' in WORKSPACE_ISOLATION_PHRASES:
- WORKSPACE_ISOLATION_PHRASES = dict(WORKSPACE_ISOLATION_PHRASES)
- WORKSPACE_ISOLATION_PHRASES['SKILL.md'] = ['One run owns one branch and one checkout', './scripts/preflight.sh --create-worktree <branch> --base origin/main', '--dry-run', 'branch, worktree path, base ref, and collision tripwire', 'does not reuse, delete, or repair existing worktrees']
- ADAPTIVE_WORKER_ROUTING_PHRASES = {
- "SKILL.md": [
- "subscription-native worker",
- "authenticated live",
- "same GPT-6 Astra model at `medium`",
- "same GPT-5.6 model at `medium`",
- "same Fable 5.1 model at `low`",
- "same Opus 5.5 model at `high`",
- "Native delegation stays inside one model family",
- "prefer `grok-4.7` at explicit `high`",
- "Composer 2.5 is retired",
- "${XDG_CONFIG_HOME:-~/.config}/elves/config.json",
- "approval-bypass authority",
- ],
- "AGENTS.md": [
- "exact same-model/lower-effort route map",
- "references/adaptive-worker-routing.md",
- ],
- "README.md": [
- "Native delegation names both model and effort",
- "same GPT-6 Astra model at `medium`",
- "same GPT-5.6 model at `medium`",
- "same Fable 5.1 model at `low`",
- "same Opus 5.5 model at `high`",
- "There is no Fable→Opus route",
- "`grok-4.7` at explicit `high`",
- "Composer 2.5",
- ],
- "references/adaptive-worker-routing.md": [
- "repository safety veto > explicit run intent > repository defaults > global convenience",
- "authenticated live",
- "exact observed model identity",
- "same observed `gpt-6-astra` model ID at `medium`",
- "same observed GPT-5.6 model ID at `medium`",
- "same observed `claude-fable-5-1` model ID at `low`",
- "same observed `claude-opus-5-5` model ID at `high`",
- "Native delegation stays inside one model family",
- "Elves no longer defines a",
- "`grok-4.7` at `high` when present in the live catalog",
- "Composer 2.5 is retired",
- "codex exec resume <thread-id>",
- "a session ID is not such an object",
- ],
- "guide/index.html": [
- "Same model, lower effort",
- "GPT-6 Astra <code>medium</code>",
- "GPT-5.6 <code>medium</code>",
- "Fable 5.1 <code>low</code>",
- "Opus 5.5 <code>high</code>",
- "stays inside one model family",
- "<code>grok-4.7</code> at <code>high</code>",
- "Composer 2.5 is retired",
- ],
- "CHANGELOG.md": [
- "Explicit delegation route identity and Grok highest-effort default",
- "same GPT-5.6 identity at `medium`",
- "Remove the Fable→Opus cross-model route",
- "same observed `claude-opus-5` model at `high`",
- "authenticated live-catalog default at explicit",
- "Prefer **`grok-4.5` at `high`**",
- "Adaptive subscription-native workers",
- "authenticated live-catalog models",
- "prompt/KV cache",
- ],
- }
- # The Fugu shortcut's model/effort profiles are restated on six surfaces, and the
- # only Fugu coverage used to be the Claude alias phrase group. A model rename could
- # therefore land everywhere except one page and still pass: that is exactly how
- # `guide/index.html` kept saying `fugu-ultra/high` after every other surface moved
- # to `fugu-ultra-v1.1/high`. Pin all five profiles per surface, in that surface's
- # own markup, so the next rename has to be complete.
- FUGU_SHORTCUT_PROFILE_PHRASES = {
- "SKILL.md": [
- "`fugu/high`",
- "`fugu/xhigh`",
- "`fugu-cyber/xhigh`",
- "`fugu-ultra-v2.0/high`",
- "`fugu-ultra-v1.1/max`",
- ],
- "AGENTS.md": [
- "`fugu/high`",
- "`fugu/xhigh`",
- "`fugu-cyber/xhigh`",
- "`fugu-ultra-v2.0/high`",
- "`fugu-ultra-v1.1/max`",
- ],
- "README.md": [
- "`fugu/high`",
- "`fugu/xhigh`",
- "`fugu-cyber/xhigh`",
- "`fugu-ultra-v2.0/high`",
- "`fugu-ultra-v1.1/max`",
- ],
- "guide/index.html": [
- "<code>fugu/high</code>",
- "<code>fugu/xhigh</code>",
- "<code>fugu-cyber/xhigh</code>",
- "<code>fugu-ultra-v2.0/high</code>",
- "<code>fugu-ultra-v1.1/max</code>",
- ],
- "references/provider-shortcuts.md": [
- "`fugu` / `high`",
- "`fugu` / `xhigh`",
- "`fugu-cyber` / `xhigh`",
- "`fugu-ultra-v2.0` / `high`",
- "`fugu-ultra-v1.1` / `max`",
- ],
- "aliases/claude/fugu/SKILL.md": [
- "`fugu/high`",
- "`fugu/xhigh`",
- "`fugu-cyber/xhigh`",
- "`fugu-ultra-v2.0/high`",
- "`fugu-ultra-v1.1/max`",
- ],
- }
- # The complete /fugu invocation grammar on every restating surface. The v2.17.1
- # release fixed `--max` missing from these grammars after v2.17.0 shipped it on
- # one surface only; this group pins the full task and review forms so a flag
- # added to the runner cannot land on five surfaces and miss the sixth again.
- # (The alias surface's grammar is pinned with the alias phrase group.)
- FUGU_INVOCATION_GRAMMAR_PHRASES = {
- "SKILL.md": [
- "`/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
- "`/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
- ],
- "AGENTS.md": [
- "`$elves fugu [--deep\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
- "`$elves fugu [--deep\\|--cyber\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
- ],
- "README.md": [
- "`/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
- "`/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
- ],
- "guide/index.html": [
- "<code>/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task></code>",
- "<code>/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope></code>",
- ],
- "references/provider-shortcuts.md": [
- "`/fugu [--deep\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
- "`/fugu [--deep\\|--cyber\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
- ],
- }
- # Host-side Fugu routing when the user omits a profile flag. Without these pins,
- # a surface can keep saying "default is regular fugu/high" while the host-routing
- # contract (choose lane before launch; isolation snapshot always on; profile locks
- # model) drifts on the others. Keep the shared decision anchors short so ordinary
- # editorial rewording of surrounding prose does not fail CI.
- FUGU_HOST_ROUTING_PHRASES = {
- "SKILL.md": [
- "Host Fugu routing",
- "Fugu route:",
- 'Host routing when the user says "use Fugu"',
- "isolation snapshot is always on",
- "explicit user flags always win",
- "Use plain regular Fugu by default",
- "successful Cyber call in the current session",
- "must explicitly select `--ultra` or `--max`",
- ],
- "AGENTS.md": [
- "Host Fugu routing",
- "Fugu route:",
- 'Host routing when the user says "use Fugu"',
- "isolation snapshot is always on",
- "explicit user flags always win",
- "Plain regular Fugu is the default",
- "successful Cyber call in the current",
- "must explicitly select `--ultra`",
- ],
- "README.md": [
- "Host Fugu routing",
- "Fugu route:",
- 'Host routing when the user says "use Fugu"',
- "isolation snapshot is always on",
- "explicit flags always win",
- "Plain regular Fugu is the default",
- "successful Cyber call in the current session",
- "must explicitly select Ultra or Max",
- ],
- "guide/index.html": [
- "Fugu route:",
- 'Host routing when the user says "use Fugu"',
- "isolation snapshot is always on",
- "flags always win",
- "Plain regular Fugu is the default",
- "successful Cyber call in the current session",
- "must explicitly select Ultra or Max",
- ],
- "references/provider-shortcuts.md": [
- 'Host routing when the user says "use Fugu"',
- "does not score complexity",
- "isolation snapshot is not optional",
- "plain `fugu/high` by default",
- "successful Cyber call in the current session",
- "must explicitly select `--ultra` or `--max`",
- "Explicit user flags",
- "always win",
- "runner flag",
- "select `--cyber` only",
- ],
- "aliases/claude/fugu/SKILL.md": [
- "Host Fugu routing",
- "Fugu route:",
- 'Host routing when the user says "use Fugu"',
- "isolation snapshot is always on",
- "Explicit user flags always win",
- "bare `fugu/high` by default",
- "successful Cyber call in the current session",
- "must explicitly select `--ultra` or `--max`",
- ],
- }
- PREWALK_PHRASES = {
- "SKILL.md": [
- "Exact-session prewalk",
- "A fresh session",
- "with a copied packet or summary is not prewalk",
- "post-edit cold fallback is forbidden",
- "Static help proves",
- "bounded live qualification canary",
- "experimental",
- "references/prewalk.md",
- ],
- "AGENTS.md": [
- "Prewalk:",
- "cold packet handoff is not prewalk",
- "references/prewalk.md",
- ],
- "README.md": [
- "Optional exact-session prewalk",
- "same session in the same worktree",
- "180-second",
- "experimental",
- "references/prewalk.md",
- ],
- "references/prewalk.md": [
- "Elves **prewalk** is a trajectory property",
- "separately qualified worker session",
- "execution route with only",
- "retained_safe",
- "post-edit cold fallback",
- "`required` automatically runs one bounded live qualification canary",
- "`experimental` is an explicit operator acceptance",
- "grok_prewalk_qualification_canary",
- "single-phase native-worker launch",
- "It never stores model output",
- ],
- "references/host-parity.md": [
- "Exact-session prewalk parity",
- "one redacted logical follow stream",
- "no post-edit cold fallback",
- "prewalk.md",
- "automatic required-mode qualification",
- "exact_session_experimental",
- "single-phase native-worker launch",
- ],
- "references/adaptive-worker-routing.md": [
- "Optional exact-session prewalk route",
- "requested/actual prewalk mode",
- "help probes always report false",
- "actual mode `off`",
- "qualification_required",
- "exact_session_experimental",
- "single-phase native-worker launch",
- ],
- "guide/index.html": [
- "Use exact-session prewalk",
- "same session in the same",
- "180-second",
- "exact_session_experimental",
- "references/prewalk.md",
- ],
- "CHANGELOG.md": [
- "Automatic prewalk qualification",
- "180-second",
- "exact_session_experimental",
- "private `.attempt.json`",
- "Grok single-phase native-worker",
- ],
- }
- EXPLICIT_HANDOFF_V1_PHRASES = {
- "SKILL.md": [
- "strict explicit",
- "handoff v1",
- "advisory, never",
- "does not turn a cold handoff into exact-session prewalk",
- ],
- "AGENTS.md": [
- "explicitly declared handoff-v1",
- "strict",
- "host-neutral",
- ],
- "README.md": [
- "machine-checked cold handoff",
- "ordinary v2.8 path remains advisory",
- "not prewalk continuity proof",
- ],
- "references/schema-and-acceptance.md": [
- "Optional explicit handoff v1",
- "Presence is the opt-in",
- "Both formats are bounded",
- "It is not trajectory continuity",
- ],
- "references/survival-guide-template.md": [
- "Handoff validation:",
- "explicit-v1",
- "never proof of exact-session prewalk continuity",
- ],
- "CHANGELOG.md": [
- "Explicit handoff v1 staging contract",
- "advisory-only",
- "never proves exact-session prewalk continuity",
- ],
- }
- GROK_OPEN_SOURCE_WORKER_PHRASES = {
- "SKILL.md": [
- "authenticated live",
- "behaviorally proven headless goal mode",
- "one-packet fallback",
- "Native Claude Code and Codex",
- ],
- "CHANGELOG.md": [
- "authenticated live-catalog models",
- "behaviorally proven headless `/goal`",
- "one-packet fallback",
- "Native Codex and Claude Code routes",
- ],
- "docs/elves/learnings.md": [
- "authenticated live catalog's parsed default",
- "another exact catalog member",
- "`/goal status` command resolution",
- "did not reach terminal state",
- "one-packet prompt fallback",
- "mode-safe terminal-canary JSON artifact",
- "digest ID",
- "full-run-await",
- ],
- "references/adaptive-worker-routing.md": [
- "authenticated live",
- "behaviorally verified headless `/goal`",
- "one-packet prompt fallback",
- "--grok-goal-behavioral-evidence <artifact.json>",
- "exact installed version/build",
- "--host claude",
- ],
- "references/cobbler-setup-recipes.md": [
- "authenticated live catalog",
- "one-packet fallback",
- "full-run-await --json",
- "grok-open-source-worker.md",
- ],
- "references/grok-implementer-launch-prompt.md": [
- "authenticated live-catalog parsed default",
- "one-packet prompt path",
- "full-run-await",
- "Claude Code and Codex remain complete without Grok",
- ],
- "references/grok-open-source-worker.md": [
- "https://github.com/xai-org/grok-build",
- "curl -fsSL https://x.ai/cli/install.sh | bash",
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 2,623 on GitHub
- "--allow-grok --probe-grok",
- "ELVES_HOST=claude",
- "--host \"$ELVES_HOST\"",
- "grok_goal_terminal_canary",
- "prompt_sha256",
- "64 KiB",
- "32 KiB",
- "digest-derived evidence ID",
- "narrow auth projection",
- "command resolution",
- "terminal state",
- "one-packet fallback",
- "full-run-launch --json",
- "full-run-await --json",
- "full-run-reconcile --json",
- "--host-tests-pass",
- "--resume --grant-grok-auth",
- "/goal resume",
- "## Qualified prewalk lane (distinct from trusted full-run)",
- "--permission-mode auto",
- "grok_prewalk_qualification_canary",
- "Required mode automatically runs the bounded live canary",
- "single-phase Grok native-worker launch gated",
- "commit `98c3b24`",
- "source commit `7cfcb20`",
- ],
- "guide/index.html": [
- "https://github.com/xai-org/grok-build",
- "curl -fsSL https://x.ai/cli/install.sh | bash",
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 2,652 on GitHub
- "--provider grok --allow-grok --probe-grok",
- "ELVES_HOST=claude",
- "--host \"$ELVES_HOST\"",
- "mode-safe JSON canary artifact",
- "prompt digest",
- "narrow OAuth projection",
- "command resolution",
- "terminal",
- "one-packet fallback",
- "implement full-run-await --session-id",
- "implement full-run-launch --session-id",
- "implement full-run-reconcile --json",
- "--host-tests-pass",
- "--grant-grok-auth --grant-github-push",
- ],
- "references/host-parity.md": [
- "narrow auth projection",
- "command resolution",
- "catalog lookup and model inference",
- "validated terminal objective-canary artifact",
- "exact installed version/build",
- "prompt digest",
- "one-packet fallback",
- "catalog qualify",
- "--host claude",
- "--host codex",
- "live driver's transport",
- ],
- }
- _GROK_UPSTREAM_PIN_RE = None # lazily compiled in grok_upstream_commit_pin_errors
- def grok_upstream_commit_pin_errors(semantic_commit: str | None = None) -> list[str]:
- """Cross-check the doc-pinned Grok upstream short SHA against runtime.
- The reference doc pin ("source commit `<short>`" over
- references/grok-open-source-worker.md) and
- worker_routing.GROK_UPSTREAM_SEMANTIC_COMMIT describe the same upstream
- commit; a one-sided bump of either must fail consistency. Tests may inject
- a semantic_commit to exercise the disagreeing state.
- """
- import re
- import sys
- global _GROK_UPSTREAM_PIN_RE
- if _GROK_UPSTREAM_PIN_RE is None:
- _GROK_UPSTREAM_PIN_RE = re.compile(r"source commit `([0-9a-f]{7,40})`")
- if semantic_commit is None:
- scripts_dir = str(REPO_ROOT / "scripts")
- if scripts_dir not in sys.path:
- sys.path.insert(0, scripts_dir)
- from cobbler_runtime.worker_routing import ( # noqa: PLC0415
- GROK_UPSTREAM_SEMANTIC_COMMIT,
- )
- semantic_commit = GROK_UPSTREAM_SEMANTIC_COMMIT
- pins = [
- match
- for phrase in GROK_OPEN_SOURCE_WORKER_PHRASES.get(
- "references/grok-open-source-worker.md", []
- )
- for match in _GROK_UPSTREAM_PIN_RE.findall(phrase)
- ]
- errors: list[str] = []
- if not pins:
- errors.append(
- "consistency policy no longer pins the Grok upstream `source commit` "
- "phrase over references/grok-open-source-worker.md"
- )
- for pin in pins:
- if not str(semantic_commit or "").startswith(pin):
- errors.append(
- f"doc-pinned Grok upstream source commit `{pin}` is not a prefix "
- "of worker_routing.GROK_UPSTREAM_SEMANTIC_COMMIT "
- f"`{semantic_commit}`; bump both sides together"
- )
- return errors
- GROK_OPEN_SOURCE_WORKER_FORBIDDEN_PHRASES = {
- "docs/elves/learnings.md": [
- "use permitted Grok Composer 2.5 Fast for regular clear work",
- "resume, `/goal`, streaming JSON",
- ],
- }
- WORKER_CONFIDENCE_SIGNAL_PHRASES = {
- "SKILL.md": [
- "**Confidence trailer**",
- "`Confidence: <level>` alone when `unsure_about` is empty",
- "never a lazy default",
- "flagged `unsure_about` areas get a deeper pass",
- "it does not skip gates or waive review in either direction",
- "`review_context.review_prompt_block`",
- "**Confidence-Guided Review**",
- "Claude Code and Codex use this identical contract",
- ],
- "references/review-subagent.md": [
- "## Worker confidence triage (read before the diff):",
- "An empty `unsure_about` list is a valid, complete answer",
- "The signal is triage only, never authority",
- "calibration observation to note in the report, not a violation",
- "The coordinator **must attach that",
- "block verbatim** to the primary Final Readiness prompt",
- "### Confidence-Guided Review",
- "Claude Code and Codex follow the same rule and prompt shape",
- ],
- "references/host-parity.md": [
- "`elves-worker-confidence-review-v1`",
- "attach its `review_prompt_block` verbatim",
- "confidence to reduce review or gates",
- ],
- "README.md": [
- "Worker confidence now actively guides the primary review on both Claude Code and Codex",
- "Missing signals fall back to the full baseline review",
- "high confidence never reduces gates or",
- "review scope",
- ],
- "guide/index.html": [
- "Worker confidence actively guides that review on both Claude Code and Codex",
- "Missing signals",
- "high confidence never removes a gate or review step",
- ],
- "scripts/cobbler_agents.py": [
- 'review_context.get("review_prompt_block")',
- 'print(review_context["review_prompt_block"])',
- ],
- "scripts/cobbler_runtime/full_run.py": [
- '"schema": "elves-worker-confidence-review-v1"',
- '"confidence_can_reduce_scope": False',
- '"flagged_areas_require_deeper_pass": True',
- '"missing_signal_falls_back_to_full_review": True',
- ],
- "references/grok-implementer-launch-prompt.md": [
- "**worker confidence signal**",
- "an empty list means \"I verified everything I touched and have no reservations,\"",
- "review triage only, never authority",
- "include your confidence (high | medium | low) and any areas you were unsure about, if any",
- ],
- "references/survival-guide-template.md": [
- "The packet also carries the confidence-reporting requirement:",
- "empty list is a valid, complete answer; triage signal only, never authority.",
- ],
- "CHANGELOG.md": [
- "Worker confidence signal (audit B5)",
- "never a lazy default",
- "review triage only, never authority",
- ],
- }
- PARALLELVES_CONTRACT_PHRASES = {
- "references/parallelves.md": [
- "not a runtime scheduler, and not an authority change",
- "exactly one coordination hierarchy: Cobbler routes lanes the way it already routes",
- "Cobbler lenses are read-only responders; Parallelves lanes",
- "is shared; the authority model is not. Lanes never gain merge, PR, or protected-ref authority.",
- "Serial remains the default everywhere.",
- "`auto` may only recommend lanes when every",
- "Nothing auto-launches.",
- "no sentence in this contract claims a runtime lane orchestrator, and none exists",
- "`parallel_declined:<gate>:<detail>` reason, recorded as provenance.",
- "`parallel_declined:worker_dominance:no_recorded_timings`",
- "in a driver-owned order, and produces one PR for the whole run.",
- "composes existing per-session worker runs (native or trusted full-run), one\nper lane, per each host's documented grammar",
- "The cross-lane entropy review is mandatory before the integration PR is review-ready.",
- "Per-lane confidence signals order the",
- "Going parallel is a reversible bet.",
- "most one lane's result lands.",
- "`off` (default) | `auto`. `auto` is recommend-only and",
- "2-3 lanes maximum in v1",
- "Automatic required-mode",
- "Runtime lane supervision is explicitly future work and ships in no v1 batch.",
- ],
- "references/glossary.md": [
- "default, recommend-only `auto`, no runtime orchestrator, no authority change",
- "feature branch on pairwise-disjoint owned surfaces, under the existing worker authority model.",
- "a serial batch that builds shared foundations before lanes fork",
- "per-lane review structurally cannot see.",
- "budget, risk posture) that must pass before `auto` may recommend lanes",
- "judges, and at most one lane's result lands.",
- "the width test records for every declined gate; parallelism is never silently withheld.",
- ],
- "AGENTS.md": [
- "**Parallel lanes (Parallelves):** serial default; `worker.parallel=auto` is recommend-only and\n nothing auto-launches",
- ],
- "guide/index.html": [
- "Serial stays the default.",
- "<code>auto</code> only recommends lanes when a deterministic width test passes. Nothing\n launches lanes automatically",
- ],
- "README.md": [
- "serial default, recommend-only width test, trunk -> lanes -> integration",
- "serial stays the default, and\n`worker.parallel=auto` only recommends lanes when the deterministic width test passes",
- ],
- "SKILL.md": [
- "parallel lanes are an earned\nrouting outcome, never a mode switch",
- "`worker.parallel=auto` may only recommend lanes, every decline records a\nconcrete `parallel_declined:<gate>:<detail>` reason, and nothing auto-launches",
- "mandatory cross-lane entropy review",
- ],
- "references/review-subagent.md": [
- "this cross-lane pass is mandatory\nbefore the integration PR is review-ready",
- "the cumulative integration diff, every\nlane's per-lane review record, and every lane's confidence signals",
- "cross-lane question classes that per-lane review structurally cannot see",
- "**Duplicated helpers across lanes**",
- "**Convention divergence**",
- "**Conflicting approaches to shared concerns**",
- "low-confidence lanes and\nflagged `unsure_about` areas are reviewed first",
- "calibration observation to note in the report, not a violation; the signal remains\ntriage only, never authority",
- ],
- "references/host-parity.md": [
- "identical semantics on Claude Code and\nCodex: serial default, recommend-only `auto`",
- "The lanes tooling is\ndeterministic and host-neutral; both hosts invoke it the same way",
- "Per-lane worker launches introduce no new invocation grammar",
- "same subscription-native default and optional-provider rules as any worker",
- "nothing in\nthis section launches lanes at runtime",
- ],
- "references/schema-and-acceptance.md": [
- "advisory in v1, exactly like the pre-handoff-v1",
- "records lane state for recovery and does not validate it",
- "plus the runtime fields `branch`, `worktree`, `session_id`, and `status`",
- "A session without\n`lanes` is serial (the default).",
- "Declaring `lanes` launches nothing and grants nothing",
- ],
- "CHANGELOG.md": [
- "Serial remains the default everywhere; there is no runtime lane\n orchestrator in v1 and no sentence claims one.",
- "The test is recommend-only; every declined gate records a concrete\n `parallel_declined:<gate>:<detail>` reason, and nothing auto-launches.",
- ],
- "references/plan-template.md": [
- "Omitting this section means serial (the default).",
- "`owned_surfaces`, and `batches`, plus a `trunk:` batch list built serially before lanes fork.",
- "Declaring lanes never launches anything: `worker.parallel=auto` may only recommend them when",
- "the width test passes, and every decline records a concrete reason.",
- ],
- }
- # Read-only review snapshots omit oversized binary media; every other category still
- # fails closed. Restating surfaces must not drift into "raise the limit" or
- # "skip the review" wording.
- REVIEW_SNAPSHOT_MEDIA_PHRASES = {
- label: [
- "omit oversized binary media",
- "16 MiB per-file limit is not raised",
- "derived text, image, or transcript artifact",
- ]
- for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'references/provider-shortcuts.md', 'references/fugu-calling-guide.md', 'references/review-subagent.md', 'aliases/claude/fugu/SKILL.md', 'aliases/claude/grok/SKILL.md', 'aliases/claude/omp/SKILL.md']
- }
- REVIEW_SNAPSHOT_MEDIA_FORBIDDEN_PHRASES = {
- label: [
- "raise the 16 MiB",
- "raises the per-file limit",
- ]
- for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'references/provider-shortcuts.md', 'references/fugu-calling-guide.md', 'references/review-subagent.md', 'aliases/claude/fugu/SKILL.md', 'aliases/claude/grok/SKILL.md', 'aliases/claude/omp/SKILL.md']
- }
- # Fugu is one optional review route. Restating surfaces must keep the reroute,
- # the recorded route triple, and the no-false-claim rule together.
- REVIEW_ROUTE_FALLBACK_PHRASES = {
- label: [
- "quota, authentication, catalog, runner, timeout, or provider failure",
- "requested route, actual route, and fallback reason",
- "review-route",
- ]
- for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'references/provider-shortcuts.md', 'references/fugu-calling-guide.md', 'references/review-subagent.md', 'aliases/claude/fugu/SKILL.md']
- }
- REVIEW_ROUTE_FALLBACK_FORBIDDEN_PHRASES = {
- label: [
- "Fugu is required",
- "blocks the run when Fugu",
- ]
- for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'references/provider-shortcuts.md', 'references/fugu-calling-guide.md', 'references/review-subagent.md', 'aliases/claude/fugu/SKILL.md']
- }
- # The Grok runner follows the installed CLI's advertised flags. Restating
- # surfaces must keep the fail-closed safety set, the config-key auto-update
- # replacement, and the catalog-bound model rule together, and must not claim a
- # flag the runner no longer hardcodes.
- GROK_LAUNCH_SURFACE_PHRASES = {
- label: [
- "flags the installed Grok Build CLI advertises"
- if label != "guide/index.html"
- else "flags the installed CLI advertises",
- "fails closed",
- "auto_update",
- "authenticated live catalog lists it",
- "cannot nest sandboxes",
- "outer boundary is not optional",
- ]
- for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'guide/index.html', 'references/provider-shortcuts.md', 'aliases/claude/grok/SKILL.md']
- }
- GROK_LAUNCH_SURFACE_FORBIDDEN_PHRASES = {
- label: [
- "self-checking",
- "always passes --check",
- ]
- for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'guide/index.html', 'references/provider-shortcuts.md', 'aliases/claude/grok/SKILL.md']
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.