Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aigorahub--elves/badge.svg)](/listings/aigorahub--elves)

HTML

<a href="/listings/aigorahub--elves"><img src="/api/listings/aigorahub--elves/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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)

  1. ---
  2. name: elves
  3. 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`.
  4. license: MIT
  5. 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.
  6. metadata:
  7. author: John Ennis
  8. version: "2.40.0"
  9. argument-hint: Path to plan file, or plan text directly.
  10. ---
  11. # Elves
  12. You are the night shift for **efficient, intelligent agentic workflows** — development and research
  13. runs that stay productive without locking the user into one model ecosystem. Plan clearly, delegate
  14. confidently, review intelligently, and ship.
  15. ## Supported main drivers (host check)
  16. **Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp).** They load this skill, stage the
  17. run, own canonical memory, protected refs, PR actions, final gates, terminal review, and merge.
  18. **Grok Build may drive Elves.** When the current session is Grok Build acting as the orchestrator
  19. (not as a worker already launched by Claude Code or Codex), stage and run the normal workflow.
  20. All four supported hosts may use exact-session prewalk when their installed transport proves the
  21. same continuity contract.
  22. **Oh My Pi may drive Elves.** When the current session is `omp` acting as the orchestrator (not as
  23. an `omp-cli` worker already launched by Claude/Codex/Grok), stage and run the normal workflow.
  24. Install with `sync_installed_skills.py --apply --target omp` into `~/.omp/agent/skills/elves`. `worker.prewalk=required` automatically runs one bounded live
  25. qualification canary when matching evidence bound to the installed version and the exact
  26. execution route is absent. It proceeds only
  27. when exact session continuity, route change, registered worktree binding, one logical stream,
  28. retained guide context, and one packet all pass. Failure stops before the task worker launches and
  29. preserves private evidence. `worker.prewalk=experimental` is an explicit operator acceptance of
  30. remaining qualification uncertainty; it still requires advertised exact resume and route override,
  31. and the real run still enforces every session, worktree, stream, packet, transition, and authority
  32. check. OMP prewalk accepts `xhigh` and `max` and passes them unchanged to `omp --thinking`. `auto`
  33. never spends on qualification, but it reuses successful cached proof.
  34. Grok Build also remains an **optional worker** under Claude Code or Codex when permitted
  35. (`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
  36. automatic qualification and runtime invariants (`references/prewalk.md`).
  37. Managed install targets are `~/.claude/skills/elves`, `~/.codex/skills/elves`,
  38. `~/.grok/skills/elves`, and `~/.omp/agent/skills/elves`
  39. (`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
  40. session is an exotic non-supported host (not Claude, Codex, Grok, or omp), refuse to stage and redirect
  41. to a supported driver.
  42. **The user owns whether Elves may merge.** You never merge by default — the user merges when they
  43. return. Exceptions: explicit merge-on-green in Run Control, chat-to-land, or the Reviewed PR Landing
  44. Command (`/land-pr` / `\land-pr`). Land only with a regular merge commit after final readiness,
  45. never a squash.
  46. **Default user path: one kickoff.** Ask naturally; the capable live driver plans and reviews,
  47. a separate subscription-native worker normally keeps the exact observed model identity and lowers
  48. only its effort. The named delegation defaults are: GPT-6 Astra at `ultra`/`max`/`xhigh` → the
  49. same GPT-6 Astra model at `medium`; GPT-5.6 at `xhigh`/extra-high/`ultra` → the
  50. same GPT-5.6 model at `medium`; GPT-4.8 Max/UltraCode → the same GPT-4.8 model at `medium`; Claude
  51. Fable 5.1 at `max`/`ultra` → the same Fable 5.1 model at `low`; Claude Opus 5.5 at `max`/`ultracode` →
  52. the same Opus 5.5 model at `high`. Native delegation stays inside one model family and lowers effort
  53. only; there is no Fable→Opus route. Exact-session prewalk is the one place two models share a run,
  54. and an operator pins both phase routes there (v2.30+): a strong guide orients and writes the bounded
  55. TODO, then the same session resumes on a cheaper or differently tuned execution route. Elves stores
  56. no model names of its own. Every route is checked against the host's own live catalog: a model is
  57. usable at a reasoning level when the installed host publishes that level for that model, so new
  58. models and new reasoning levels need no Elves edit. The catalog widens the host's offline
  59. vocabulary and never narrows below it, so an unreadable catalog authorises nothing new. Grok Build is
  60. the one cross-family worker, and it is opt-in rather than a default:
  61. 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.
  62. Composer 2.5 is retired and is never selected. Unlisted native routes use plan-matched effort, and
  63. explicit user route choices still win for any catalog-listed, non-retired model.
  64. Optional permitted Grok is capability-probed and recommended explicitly. The user makes at most one
  65. useful preference choice, receives a proven native view or exact follow command, and returns to
  66. cumulative driver review. Trusted full-run delegation keeps that path
  67. fast and calm: one risk-aware plan, one autonomous worker goal, meaningful worker commits/pushes, a
  68. parked driver, a capability-bound non-model follow surface, one cumulative terminal review, consolidated fixes,
  69. delta-only re-review, impact-selected proof, and a host-owned **landable PR** or authorized merge.
  70. Prefer **chat-to-work** or **chat-to-land** (`references/e2e-chat-to-land.md`). **Legacy two-call**
  71. handoff remains valid for huge/unstable plans.
  72. **Canonical contract (code):** `scripts/cobbler_runtime/canonical_contract.py`. Operator detail:
  73. `references/joyful-runs-contract.md`, `landing-authority.md`, `follow-mode.md`,
  74. `proof-and-review.md`, `host-parity.md`, `schema-and-acceptance.md`, `prewalk.md`.
  75. **User guide (v2.40.0):** `https://aigorahub.github.io/elves/` is the short task-first path for
  76. installation, kickoff, worker choice, live progress, review, and landing. The references above
  77. remain the detailed workflow contracts.
  78. **Runtime helper paths:** every `python3 scripts/...` example is **source-checkout shorthand**.
  79. In an installed Claude Code, Codex, Grok Build, or Oh My Pi skill, resolve helpers from the **active Elves skill root**
  80. (`~/.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**.
  81. See `references/runtime-helper-paths.md`.
  82. ## Reviewed PR Landing Command
  83. When the user asks to review the diff from main, read all PR comments, address findings, run tests,
  84. and merge once green — or types `\land-pr` / `/land-pr` — treat that as a one-off explicit merge
  85. opt-in for the current PR.
  86. 1. Resolve branch, PR, base, draft state, checks.
  87. 2. Read every review surface.
  88. 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 —
  89. `/fugu review <scope>` in Claude Code, `$elves fugu review <scope>` in Codex, Grok Build, or Oh
  90. My Pi — and state the one-line `Fugu route: …` first. The shortcut resolves `scripts/run_fugu.sh`
  91. from the active Elves skill root and runs it with its sandbox, context policy, and wall-clock
  92. bound intact; that runner **is** the routed call.
  93. **Never invent a raw Fugu call:** no direct `codex-fugu` or `claude-fugu` invocation, no
  94. improvised API request, and no variant that strips the runner's isolation or timeout controls.
  95. Scope the review to this PR's diff against the default branch.
  96. Otherwise, record the skipped Fugu review and its reason. Fugu findings are evidence for the host review, never landing
  97. authority.
  98. 4. Host review: independent review of `git diff <default-branch>...HEAD`.
  99. Every Agy review and re-review requires `/boost` in plan mode. No plain
  100. Agy fallback. Use the supervised Agy procedure in
  101. `references/review-subagent.md` when headless transport is unqualified.
  102. Keep child permissions, Boost completion, and final review evidence separate.
  103. 5. Fix blockers from the review surfaces, the Fugu review, and the host review; push.
  104. 6. Update the docs the change touches, and **bump the version when the repository versions**
  105. (Elves itself versions: `SKILL.md` metadata, `AGENTS.md`, the `CHANGELOG.md` release heading, and
  106. the pinned version narration). Repositories that carry no version stay unversioned — do not
  107. invent a version scheme for them.
  108. 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.
  109. 8. Merge only when not draft, worktree clean, no requested changes, final readiness is clean, and
  110. both landing questions pass on the exact head. **Can it merge?** Every required check passed or
  111. was skipped, and GitHub does not report the PR as `BLOCKED`. **Was it tested?** An ordinary PR
  112. (base is the default branch) has a `Local tests passed on <head SHA>` PR comment for that head;
  113. a Dependabot PR has its full-suite jobs passed instead (Elves checks those against the repo's
  114. `.github/ci-suite.json`; without that file a person lands Dependabot PRs).
  115. A release or hotfix PR (base is `main` while `main` is not the default branch) carries the
  116. `release` label, has `release-gate` and `full-tests` concluded `success` on that head, has `main`
  117. up to date, and needs the user's explicit release authority. Socket, Vercel, and skipped checks
  118. never count as tested. The strict landing check computes both answers from GitHub. Then
  119. `gh pr merge --merge --match-head-commit <sha>` (never squash). On a release PR, review the diff
  120. against the PR base (`main`), and after it lands open the same-day back-merge PR from `main` into
  121. the default branch.
  122. 9. Post-merge teardown: reclaim the run's own recorded worktree (`worktree_path` in
  123. `.elves-session.json`) with `./scripts/preflight.sh --gc-worktrees --path <worktree_path>` —
  124. report first, add `--apply` to remove. The gc helper is separate from the create helper and
  125. removes only clean, fully merged, fully pushed worktrees.
  126. Active-run land-pr **grants driver authorization** without bypassing or restarting readiness.
  127. See `references/landing-authority.md`.
  128. ## Architecture (v2.3)
  129. ```text
  130. staging -> executing -> reconciling -> reviewing <-> revising -> ready -> terminal
  131. ```
  132. Worker state, readiness evidence, and landing authority are **independent**:
  133. - `ready=true` never grants merge permission
  134. - `driver_authorized=true` never proves readiness
  135. - Merge requires both at the same **exact HEAD**
  136. - Worker evidence cannot grant merge or change landing outcome
  137. **Risk** is `low | standard | high`. **Trust mode** is independently `trusted | untrusted`.
  138. (Legacy 2.2 four-tier labels map onto these axes; see `references/proof-and-review.md`.)
  139. **Thin safety kernel** (must not weaken):
  140. 1. Exact plan/session/packet acceptance identity (B0/B1, bare/bracketed IDs)
  141. 2. Credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, redaction
  142. 3. No worker merge/tag/protected-ref/PR/landing authority
  143. 4. Test integrity, constitution, exact-HEAD readiness, independent terminal review, final CI
  144. 5. Strict detached/import evidence for untrusted writers
  145. 6. Native Claude Code and Codex without Grok or optional providers
  146. Proof budget: **validate once, verify changes, attest final**. Prefer **touched surfaces** by
  147. default; broad proof at risk checkpoints and terminal readiness. Mid-run: impact path and blockers
  148. only; bank advisory nits as **deferred hygiene**. Terminal: full suite (or project full gate), one
  149. cumulative review, drain deferred hygiene. See `references/validation-guide.md` and
  150. `references/proof-and-review.md`.
  151. ## Why This Exists
  152. Convert idle hours into shipped code. Ralph Loop: try, check, feed back, repeat. Memory lives in
  153. files (survival guide, plan, execution log, learnings) — not chat. Read them. Trust them. Update them.
  154. ## Documentation Surfaces
  155. - **Plan** — scope and acceptance
  156. - **Survival Guide** — run control, next action, Stop Gate
  157. - **Learnings** — durable reusable lessons
  158. - **Execution Log** — chronological proof
  159. - **Elves Report** — temporary HTML morning report under `/tmp`
  160. - **`.ai-docs/*`** — curated durable architecture/conventions/gotchas
  161. Promotion: `execution log -> learnings -> .ai-docs`
  162. ## Coordination Architecture
  163. - **Elves** is the execution system: plans, branches, PRs, validation, review, memory, landing
  164. - **Cobbler** is the default coordinator: classify, route, preserve dissent, fit one answer
  165. - **Domain workflows** are specialized Cobbler-managed packs
  166. - **Math** is the first domain workflow (Math is first)
  167. - **Providers** are optional role routes; never the orchestration layer
  168. Once Elves starts a staged or active run, operate Cobbler-first unless the survival guide turns it
  169. off. Persist `cobbler.default_for_session` in `.elves-session.json` and the survival guide.
  170. ## Math Research Workflows
  171. Math research is a **Cobbler-managed Elves domain workflow**: Discovery Sprint, scouts, proof
  172. 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`.
  173. ## Cobbler
  174. 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.**
  175. Invocation:
  176. - Claude Code: `/cobbler <task>`, `/cobbler-mode`, `/setup-cobbler` (aliases `/council`, `/ec`, `/elves-council`, `/setup-council` remain)
  177. - 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**
  178. - Grok Build: natural language for Cobbler intents (no Claude-style slash aliases)
  179. - Oh My Pi: natural language for Cobbler intents (no Claude-style slash aliases)
  180. **Cobbler Mode** is current-thread chat state (**not durable run state**). Exit with "Cobbler Mode: off".
  181. **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.
  182. ### Who implements (native default, optional extras)
  183. **Default: subscription-native worker** on the live host (Claude Code, Codex, Grok Build, or Oh My Pi). It
  184. receives one packet in a separate exact session, inherits the live driver's model unless explicitly
  185. routed otherwise, and uses the named same-model/lower-effort delegation defaults above (plan-matched
  186. effort for unlisted routes) without changing the live driver. No optional external implement CLI is
  187. required for the native path. Host-native in-session execution remains the safe fallback when the
  188. separate native worker lifecycle is unavailable.
  189. Optional Grok Build is selected only when available **and permitted**. An explicit current-run or
  190. global `provider=grok` is remembered consent; repository `allow_grok=true` is not. Repository
  191. `allow_grok=false` remains an absolute veto. Model selection comes from the authenticated live
  192. 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
  193. it. Composer 2.5 (`grok-composer-2.5-fast`) is retired and is never selected. Installed-binary
  194. capability evidence is launch authority. Provider qualification is independent from `/goal`:
  195. behaviorally proven headless goal mode is an enhancement, while an unavailable goal capability uses
  196. the recorded one-packet fallback. Missing core/auth/catalog capability or repository prohibition
  197. falls back honestly to native. See `references/adaptive-worker-routing.md` and
  198. `references/grok-open-source-worker.md`.
  199. **Optional work drivers:** trusted Grok Build full-run
  200. (`implement full-run-prepare|full-run-launch|full-run-monitor|full-run-await|full-run-reconcile|full-run-logs`;
  201. `full-run-stop` for cancellation only); **Oh My Pi (`omp-cli`)** parked full-run with the same
  202. lifecycle and host-owned authority; Devin CLI, OpenCode, and other adapters when configured; or
  203. legacy bounded batches. Host owns packets, protected refs, final gates, PR, and merge. Trusted
  204. full-run worker owns internal batches and feature-branch progress while the host stays **parked**.
  205. Untrusted lease writers remain detached with host import only. Oh My Pi as a **main driver** (`omp`
  206. host) is separate from optional **`omp-cli` / `/omp` worker** routes under other hosts; neither is
  207. required for Claude/Codex/Grok native runs (`references/omp-worker.md`).
  208. Launch recipe: `references/grok-implementer-launch-prompt.md`. Credential grants are explicit;
  209. workers never inherit host HOME/SSH/git identity ambiently.
  210. ### External-agent setup and model onboarding
  211. `/setup-cobbler` or `$elves setup-cobbler` (and natural language). Codex: **not a top-level** slash
  212. command. CLI: `python3 scripts/cobbler_agents.py onboard plan|show|apply|probe` and
  213. `cobbler_agents.py setup`. Write only ignored local `.elves/models.toml`. See
  214. `references/model-onboarding.md` and `references/cobbler-setup-recipes.md`.
  215. ### Provider shortcut protocols
  216. When an explicit request matches one of these provider tags, resolve the runner from the **active
  217. Elves skill root**, keep the target repository as the working directory, validate its arguments and
  218. required capability, then execute it without an extra confirmation prompt:
  219. - `/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>` or “use Fugu …” →
  220. `scripts/run_fugu.sh [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] <planning-task>` for a bounded planning or analysis task.
  221. `/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`, `$elves fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review
  222. <scope>`, or “do a Fugu review …” selects the explicit read-only review contract.
  223. **Host Fugu routing:** when the user says “use Fugu” (or plain `/fugu` / `$elves fugu`) without
  224. an explicit profile flag, the host agent must choose the lane before launch: general vs
  225. `review <scope>`, plain / `--deep` / `--cyber` / `--ultra` / `--max` (profile locks model + effort; never
  226. invent a free model slug), and optional exact `--include`
  227. paths. State one short `Fugu route: …` line, then invoke the runner. Prefer the cheapest lane
  228. 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.
  229. Prefer `--max-wait` over automatic `--deep`. **If any `--include`, run `--preflight` first**
  230. (never gitignored paths). Redirect Fugu to a log (never `| tail`); chat cancel does not stop the
  231. provider; wait up to the wall or kill the process group. On timeout/crash, harvest any
  232. `Fugu partial salvage` markers from the log before relaunching. Put goal, paths, done-when, and
  233. out of scope in the task string. The isolation snapshot is always on for every launch (not a host skip
  234. option); the host only selects extra admitted context via `--include`, not a parallel “minimal
  235. snapshot” product. Full decision table, templates, wait contract:
  236. `references/provider-shortcuts.md` (**Host routing when the user says "use Fugu"**);
  237. field notes: `references/fugu-calling-guide.md`.
  238. Both use a Git-enumerated snapshot containing policy-admitted tracked and non-ignored untracked
  239. files; `--include <path>` must admit and copy exact host-selected context or fail, while immutable
  240. safety policy rejects ignored, both `.env.*` and `*.env` credential-name families,
  241. operational/internal-namespace,
  242. executable-agent, symlink, hard-link, special, unsafe-mode, and out-of-repository paths with
  243. bounded diagnostics. Fugu is limited to planning and read-only review. `--write` is rejected.
  244. The required outer filesystem sandbox remains the read/write authority, and the Linux boundary
  245. omits procfs so model-directed commands cannot inspect the credential-bearing parent environment;
  246. it exposes only a synthetic `/proc/self/exe` link to the qualified real Codex binary.
  247. Codex uses its documented externally-sandboxed mode so macOS does not attempt a forbidden nested
  248. sandbox. Live writable-state limits tolerate benign disappearing temporary subtrees and fail
  249. closed on other traversal errors. macOS read-only cleanup is best-effort and non-authoritative;
  250. polling is never claimed as recursive containment. The default runner profile is regular
  251. `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
  252. `--ultra` selects `fugu-ultra-v2.0/high` when that slug is listed, then `fugu-ultra/high`, then
  253. `fugu-ultra-v1.1/high`. `fugu-ultra-v1.0` is never substituted. `--max` selects effort `max` on
  254. the first of those slugs that lists it, which remains `fugu-ultra-v1.1/max` until a newer catalog
  255. row lists `max`, with a 60-minute default wall budget for one narrow high-stakes gate. `--max` is
  256. not the Fugu Max model (`fugu-max`). Profiles are mutually exclusive.
  257. Regular and deep are ephemeral one-shot sessions. Ultra reserves part of the
  258. total wall budget for synthesis and, if needed, resumes the exact captured session id with further
  259. tools forbidden. It never guesses a “last” session; raw events are parsed incrementally under a
  260. bounded host pipe, final output stays pinned to a no-follow descriptor, and raw
  261. events/resumable state remain only inside the disposable lane. Every settled phase receives a
  262. final descriptor-safe writable-state audit before output is accepted.
  263. **Review snapshot media policy (all harnesses and hosts).** Read-only review snapshots omit
  264. oversized binary media instead of failing the whole review. Video, audio, presentation, archive,
  265. image, font, and 3D binaries above the per-file limit are left out of the snapshot; the 16 MiB
  266. per-file limit is not raised. The context manifest records each omitted path, byte size, and
  267. reason, and every runner prints the same omission block. Source, prose instructions, executable
  268. agent configuration, and explicit `--include` paths still fail closed, with a remediation that asks
  269. for a derived text, image, or transcript artifact. Writable lanes keep fail-closed behavior.
  270. **Fugu is optional (review route fallback).** When a review route is unavailable because of quota,
  271. authentication, catalog, runner, timeout, or provider failure, probe the supported review routes
  272. and select another available independent reviewer instead of stopping. Preserve an explicit user
  273. route when it works; otherwise prefer a supported native reviewer when no optional provider works.
  274. Record requested route, actual route, and fallback reason. Do not claim a review ran when it did
  275. not, and do not let optional-provider failure block the run while a qualified review route exists.
  276. Host-neutral helper: `python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host
  277. <host> --requested <route> --unavailable <route>=<reason>`.
  278. - `/manus <topic>` → `scripts/run_manus.sh <topic>` for one private, bounded Manus deep-web task.
  279. For reference-by-reference research, Cobbler uses
  280. `--wide --items-file <roster.json> [--file <source>] <goal>`: request native Wide Research,
  281. verify exact roster coverage, repair missing or duplicated items with deterministic one-task-per-
  282. item fan-out, and synthesize only after coverage is complete. `--fanout` skips the native attempt;
  283. `--resume <manifest>` continues the ignored `.elves/runtime/manus/` record without duplicating
  284. successful or live tasks, while archiving and retrying only known-failed steps. Cobbler remains
  285. the outer orchestrator; Manus is a bounded provider subsystem. New manifests are confined to
  286. that runtime tree, are exclusively reserved before uploads, and never overwrite an existing
  287. file. Requests nest empty connector, enabled-skill, and forced-skill lists under `message`; no
  288. connector or forced-skill IDs are explicitly granted, but Manus documents that an empty
  289. `enable_skills` list loads the account's enabled defaults, so this route does not promise skill
  290. isolation. A durable create-intent guard makes a crash between paid creation and task-ID storage
  291. fail closed for resume until an operator reconciles the provider task list.
  292. - `/grok <instructions>` or `grok build <instructions>` → `scripts/run_grok.sh <instructions>` for
  293. a headless Grok task at `high` reasoning by default, with non-bypass permissions over a disposable tracked-source
  294. snapshot in Elves' required outer kernel sandbox, plus Grok's built-in inner `strict` profile,
  295. provider-documented isolated `dontAsk` settings, and bypass locked off. It requires an explicit
  296. `XAI_API_KEY` (or the legacy named key); its dedicated tool shell removes both key names before
  297. model-directed commands run, and its Linux boundary omits procfs to prevent parent-environment
  298. inspection. Shared-file OAuth fails closed because Grok applies its sandbox to both provider and
  299. model-tool reads.
  300. The runner builds argv from the flags the installed Grok Build CLI advertises: an absent safety
  301. flag (isolated `--cwd`, inner `--sandbox strict`, headless `--single`, `--output-format`,
  302. explicit reasoning effort) fails closed, while a quality flag the installed version dropped is
  303. simply not passed. Auto-update is disabled through the isolated `[cli] auto_update` config key
  304. rather than a removed flag. Reasoning effort defaults to `high`; `ELVES_GROK_EFFORT` selects
  305. `low`, `medium`, `high`, or `xhigh`, and `ELVES_GROK_MODEL` pins a model only when the
  306. authenticated live catalog lists it. The runner reports the CLI version, effort, model, the
  307. authentication route the CLI itself names, and any omitted flags.
  308. On a host that cannot nest sandboxes (macOS Seatbelt refuses a second profile inside Elves'
  309. required outer `sandbox-exec` boundary), the runner fails closed with
  310. `grok_inner_sandbox_unavailable` before it builds a snapshot, rather than launching with the
  311. inner profile silently missing. Elves does not drop the inner profile to make a launch succeed,
  312. and the outer boundary is not optional; use a Linux host with the bwrap backend or select
  313. another review route.
  314. - `/devin <instructions>` → `scripts/run_devin.sh <instructions>` for a bounded remote Devin
  315. development session with no stored secret or knowledge grants unless a future explicit
  316. allowlist surface authorizes them. Its creation and poll requests use bounded response bodies and
  317. share a hard wall-clock wait budget; zero wait retains create-and-return behavior.
  318. - `/omp <instructions>` → `scripts/run_omp.sh <instructions>` for a bounded headless Oh My Pi
  319. worker/shortcut under Claude/Codex/Grok (not the interactive main-driver path), run-scoped
  320. `--profile` and private HOME/XDG isolation, never spell the CLI `opm`, never pass omp product
  321. `--prewalk` as Elves prewalk. Prefer explicit model pin via `ELVES_OMP_MODEL`. See
  322. `references/omp-worker.md`. Its Linux boundary omits procfs and has no `/proc` view.
  323. Exact-session OMP create and resume use one stable worktree-derived profile. Isolated profiles
  324. do not inherit host OAuth. Auth preflight reads a loopback broker from the environment or
  325. persistent `auth.broker` settings and stops before any model call when provider auth is missing.
  326. The slash spellings are Claude Code managed aliases. Codex uses `$elves fugu|manus|grok|devin|omp …`
  327. or natural language; **never invent top-level Codex slash commands**. These are optional paid
  328. provider routes, not the native default, and never grant merge, protected-ref, secret, or
  329. approval-bypass authority. Full transport, timeout, auth-name, and follow-link contracts:
  330. `references/provider-shortcuts.md`.
  331. ## Strategic Forgetting
  332. 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.
  333. ## Code Quality Philosophy
  334. 1. Root cause over band-aids
  335. 2. Centralize over duplicate
  336. 3. Extend over create
  337. 4. Architecture first
  338. 5. Proactive pattern detection
  339. 6. Progressive repo conditioning
  340. 7. No unjustified hardcoded constants
  341. 8. Runaway detection (5+ fruitless edits → stop and reframe)
  342. 9. Favor boring technology
  343. 10. **Anti-accretion:** no new repo meta-tooling, coined terms, or config keys without an explicit
  344. plan acceptance criterion that names the user-visible overnight-run value. Prefer deleting or
  345. quarantining unused surface over adding process around it.
  346. Reviewers: the current codebase is source of truth, not training data. Pass today's date to review
  347. subagents.
  348. ## Coordinator-to-Implementer Handoff Standard
  349. Before every worker turn (one packet for a trusted full-run), write a stand-alone packet:
  350. 1. intent / why
  351. 2. non-obvious rationale
  352. 3. Build On targets
  353. 4. owned surfaces
  354. 5. forbidden surfaces
  355. 6. acceptance evidence
  356. 7. failure modes / pitfalls
  357. 8. HEAD / run-doc paths / route-session identity / output format
  358. Incomplete handoffs are blocking coordinator defects. Canonical run docs stay host-owned.
  359. **Commit cadence and phase roles.** An implementing worker pushes at least one non-`Close`
  360. progress slice before `Close`, with the first slice due as soon as a failing test or first surface
  361. change exists; a single monolithic `Close` commit is a reconcile-visible defect the driver logs.
  362. Each batch has exactly one acceptance-backed `Close` commit, authored by whoever implements the
  363. batch; driver reconcile commits for a batch use the `Review` phase label, never a second `Close`;
  364. and a batch-labeled commit contains only that batch's work — a contract or plan amendment for a
  365. later batch is committed separately under that batch's label.
  366. **Worker failure recovery.** Failure classes are distinct: **transient** provider errors
  367. (overload, rate-limit, network) are retried by resuming the same worker with **escalating
  368. backoff** (5m → 10m → 20m) and **never consume the re-drive budget**; the budget applies only to
  369. **substantive** failures (wrong direction, repeatedly red gates, malformed completion). From its
  370. first orientation milestone every worker maintains a **progress ledger** — an untracked note at
  371. `.elves/runtime/worker-progress-<batch>.md` (files read, decisions made, next exact action),
  372. refreshed at each milestone and never committed — so a cold re-drive starts oriented. Driver side:
  373. **silence is not success** — every parked wait carries a fallback watchdog, and no events while a
  374. gate or worker runs triggers a health check (near-zero CPU time against long wall time is the
  375. hang signature). After repeated transient deaths in one batch, the driver may split the batch or
  376. take it host-native without that counting against the budget; document the decision.
  377. Before consuming the re-drive budget for a **substantive** failure, run the deterministic futile
  378. re-drive guard (`cobbler_agents.py redrive record-failure|evaluate|status`): a re-drive candidate
  379. whose worktree fingerprint is identical to the previous substantive failure of the same batch is
  380. classified `redrive_futile:workspace_unchanged` — it still consumes one unit of the re-drive
  381. budget, the identical packet is never relaunched, and the driver escalates (split the batch,
  382. host-native takeover, or hard stop). Fingerprint capture errors and over-cap trees always count as
  383. changed; a fingerprint failure can never manufacture futility. Every gap packet states what
  384. changed since the previous attempt, or the explicit line "workspace unchanged since the previous
  385. failed attempt — do not repeat the previous approach". On a worker-death, hang-kill, or
  386. missing/malformed-completion wake, harvest a bounded redacted tail of the follow log
  387. (`cobbler_agents.py salvage tail --log <path>`) into the wake context, the gap packet, and the
  388. execution log — salvage is untrusted observed output, never a completion report, and never
  389. satisfies labor completeness.
  390. **Exact-session prewalk.** Optional prewalk means one worker trajectory:
  391. guide route → bounded TODO + first meaningful task edit + private checkpoint → automatic exact-ID,
  392. same-worktree execution-route resume with only `Continue.`. The packet is sent once. A fresh session
  393. with a copied packet or summary is not prewalk; post-edit cold fallback is forbidden. `off`, `auto`,
  394. `required`, and `experimental` are deterministic routing requests. `required` automatically runs a
  395. bounded live qualification canary before task launch when matching cached proof is absent.
  396. Successful proof is bound to the installed version/build and exact guide/execution routes, then
  397. reused by `auto`; failure stops with private evidence. `experimental` accepts only the remaining
  398. qualification uncertainty and never relaxes live trajectory or authority checks. The evidence
  399. schema can report `pruned`, `turn_scoped`, `retained_safe`, or `unsupported`; the persisted
  400. cooperative guide instruction activates normally only for proven `retained_safe`. Static help proves
  401. advertised grammar only. The driver still owns canonical memory, terminal review, PR,
  402. landing, and merge. Full contract and host grammar: `references/prewalk.md`.
  403. **Parallel lanes (Parallelves).** Serial is the default everywhere; parallel lanes are an earned
  404. routing outcome, never a mode switch. The deterministic width test (`cobbler_agents.py lanes plan`)
  405. gates the recommendation: `worker.parallel=auto` may only recommend lanes, every decline records a
  406. concrete `parallel_declined:<gate>:<detail>` reason, and nothing auto-launches. The topology is
  407. trunk -> lanes -> integration: trunk batches build shared foundations serially, lanes run as
  408. ordinary workers on pairwise-disjoint owned surfaces in dedicated checkouts (a native-worker lane
  409. needs its own clone with its own origin), and the driver merges
  410. them behind a mandatory cross-lane entropy review. Full contract: `references/parallelves.md`.
  411. ## Git History as Operator UI
  412. Preferred subject schema:
  413. ```text
  414. [<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>
  415. ```
  416. **Forbid vague subjects.** Anti-pattern examples:
  417. `[feat/payments · Batch 3/12] Updates`,
  418. `[feat/payments · Batch 3/12 · Implement] progress`,
  419. `[feat/payments · Batch 3/12 · Implement] WIP`,
  420. `[feat/payments · Batch 3/12 · Implement] fixes`.
  421. Trusted `branch_progress` workers may commit/push only the assigned feature branch. Untrusted lease
  422. 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.
  423. **Protected refs, PR operations, and merge never dispatch model inference.**
  424. Batch `Close` commits (and the driver mirroring worker batches) carry a **Confidence trailer**:
  425. `Confidence: <level>` alone when `unsure_about` is empty, or
  426. `Confidence: <level> — unsure: <semicolon-joined items>` when not. An empty unsure list is a valid,
  427. complete answer — a positive assertion, never a lazy default; the trailer is review triage only,
  428. never authority. Example:
  429. `Confidence: medium — unsure: retry backoff bounds in queue.py; whether the legacy CSV importer still hits the new validator`.
  430. ## Effort Standard
  431. Do not be lazy. Work as hard as you can for the full run on **plan acceptance and blockers**. Same
  432. drive on the last product batch as the first. Prefer deeper progress on the planned path over the
  433. minimum acceptable change.
  434. Hard work does **not** mean mid-run nit perfection, nested full reviews, or re-running a large full
  435. suite between ordinary batches. Correctness on the impact path is non-negotiable; polish and
  436. full-suite attestation belong at terminal readiness (deferred hygiene).
  437. ## Out-of-Scope Findings
  438. A run notices things the plan does not cover. There are three destinations, and only one is right
  439. for work outside the plan:
  440. | What was noticed | Destination | Settled |
  441. | --- | --- | --- |
  442. | In-scope nit, polish, full-suite attestation | deferred hygiene | terminal readiness, this run |
  443. | Adjacent bug, test or doc, time remaining | Scout Mode | this run, as a commit |
  444. | Worth doing, outside the plan | **GitHub issue** | a later run |
  445. Out of scope means the plan does not cover it and widening a batch to include it would change what
  446. the user accepted. Do not fix it, do not widen the batch, and do not drop it. **File it**:
  447. ```bash
  448. gh issue list --search "<keywords>" --state all --limit 5 # never file a duplicate
  449. gh issue create --title "<imperative and specific>" --body "<body>" --label enhancement
  450. ```
  451. The body carries what and where (`file:line`), why it matters, why it was out of scope for this
  452. run, and the branch or PR that found it. Never a secret value: cite the location and the credential
  453. type, and recommend rotation.
  454. Record every issue URL in the execution log and list them in the terminal report, so the run names
  455. what it deferred instead of leaving it in a transcript nobody re-reads. Without `gh` or without a
  456. repository, write the same entries to the run notes and say so in the report.
  457. A run that files more than a handful is describing a different project than the one it was asked to
  458. build. Say that in the report rather than filing thirty issues.
  459. ## Run Mode
  460. Persist under `## Run Control`. **Finite** (default) ends at completion. **Open-ended** continues
  461. until explicit stop or true blocker — checkpoints are not completion.
  462. ### Open-ended rules
  463. After every checkpoint, continue. Final Completion is disabled unless the user stops you. A final
  464. response is forbidden while Stop Gate says `Stop allowed right now: no` or
  465. `continuation_guard.stop_allowed: false`.
  466. ### Pre-Final Guard
  467. Before any final response: Did the user ask to stop? What does Run Control say? Does the Stop Gate
  468. allow stopping? Is work remaining? Audit the current state against every requirement at the
  469. current HEAD — do not rely on intent, partial progress, or memory of earlier work. If not
  470. justified, continue.
  471. ## Discovery
  472. Use this phase when the goal is open-ended and no task has been named yet: "what should we work on
  473. next", a structural-debt survey, a UX or security sweep, bug hunting, or backlog generation. When
  474. the user already named the work, skip straight to Planning.
  475. Discovery is **read-only on source**. It may run the repository's own read-only checks (type-check,
  476. lint in check mode, dependency audit, a cheap side-effect-free test run) but writes nothing outside
  477. `advisor-plans/`. It runs before `staging` and is not a worker state: there is no readiness
  478. evidence, no landing authority, and nothing to merge. Implementation happens later, through the
  479. normal batch loop, once the user picks what to build.
  480. The read-only boundary **overrides open-ended escalation**. Discovery shares its use cases with
  481. `references/open-ended-guide.md`, and that guide sends a saturated run into Scout Mode, which
  482. commits code. That escalation does not apply here. When findings saturate during Discovery,
  483. broaden the survey or file issues; do not enter Scout Mode, fix adjacent bugs, or modify source
  484. until the user selects work.
  485. Method lives in `references/audit-playbook.md`: nine categories with what to look for in each, and
  486. a depth rule that scales the pass to repository size. Two contracts from that reference are
  487. binding:
  488. - **Evidence.** A finding cites `file:line` and a concrete effect. "Probably has N+1 queries
  489. somewhere" is not a finding; `orders/api.ts:142 issues one query per order item inside a loop`
  490. is. Never reproduce a secret value; cite the location and credential type, and recommend rotation.
  491. - **Leverage.** Rank by impact divided by effort, discounted by confidence and by how risky the fix
  492. is. "Not worth doing" is a valid verdict and is recorded with one line of reasoning, so the
  493. maintainer knows it was considered.
  494. Selected findings become self-contained executor plans in `advisor-plans/`, one per finding, using
  495. `references/finding-plan-template.md`. Each plan assumes an executor with zero context: it has not
  496. seen this session, the survey, or the other plans. A plan that says "the pattern discussed above"
  497. is broken. That template is per-finding and is distinct from `references/plan-template.md`, which
  498. shapes a batched run.
  499. Findings the user does not select are filed with `gh issue create` rather than carried in memory or
  500. fixed opportunistically, in the shape and with the guards described under **Out-of-Scope
  501. Findings**. Discovery differs only in volume: a survey is expected to produce several issues, where
  502. an ordinary run should produce few.
  503. ## Planning
  504. Interactive by default; autonomous expansion of brief prompts is allowed with user approval before
  505. execution. Required: plan, survival guide, learnings, execution log, active branch.
  506. Plans express **intent, acceptance, risk, caution, affected surfaces, constitution impacts, focused
  507. tests, review focus, dependencies**, and optional checkpoints — **without implementation
  508. choreography**. See `references/plan-template.md`.
  509. ## Driver and helper teams
  510. Use one driver with bounded helpers for a shared task, independent proposals then
  511. critique for brainstorming, and separate writer lanes for implementation. Canonical
  512. commands and gates: `references/agent-teams.md`. The `team` and `team-lanes` CLI
  513. commands work on every supported host. Saved role choices use existing preferences.
  514. Stage exact driver and helper identities. Record all substantive contributors.
  515. The independent landing reviewer must be outside that set. A fresh same family
  516. reviewer is valid. Use the qualified Agy plan mode and Boost harness when selected.
  517. Review routing and final readiness enforce contributor exclusion and exact commit
  518. evidence. Worker reports cannot rewrite the driver ledger or callback configuration.
  519. Lantern callbacks are optional. Pull reports at named driver checkpoints. Never
  520. prompt a working or parked seat. Keep the one packet prewalk transition. Persist
  521. report results before acknowledgement and reconcile ambiguous effects before retry.
  522. Only the driver integrates lane results or performs authorized landing.
  523. ## Staging
  524. Launch only when: plan cleaned, run docs current, branch/PR recorded (or the supported pending
  525. draft checkpoint below is recorded), preflight green, acceptance
  526. contract reconciled, run mode/non-negotiables recorded, no unresolved planning blockers. In single-
  527. kickoff E2E, continue immediately once launch-ready.
  528. For an authorized implementation run, the driver opens or reuses the draft
  529. implementation PR at the first useful pushed commit, preferably a staging
  530. commit, before bulk execution. Do not wait for implementation to finish.
  531. The driver owns PR creation and bot requests; workers keep their existing
  532. feature-branch commit and push authority. Read-only audits and issue harvests
  533. do not create PRs. Check the configured bot trigger and draft support. Use a
  534. documented review request only when permitted. If draft review is unavailable,
  535. record that limit and keep the incomplete PR in draft. Never mark it ready
  536. only to start a bot. See `references/review-subagent.md` for early review rules.
  537. If staging has no useful diff, record PR creation as pending and arrange a
  538. safe worker checkpoint at its first useful push only when the installed route
  539. supports it and all staging gates permit it. Otherwise prepare a useful staging
  540. diff and open the draft before launch. The driver creates a pending draft
  541. there before bulk work resumes. Do not wait for the whole worker run or send
  542. prompts into a working or parked seat. Confirm a bot review, bot-owned check,
  543. or queued bot job; unrelated CI is not proof that bot review started.
  544. Record the PR URL/number, base branch, and exact current head. After resume,
  545. look up the existing PR by repository and branch before creating another.
  546. The checkpoint uses the original worker packet. It must not change the exact
  547. prewalk session transition or add a second packet; the transition remains `Continue.`.
  548. If Run Control `Work driver` ≠ host-native (or the run may be delegated), the standalone
  549. coordinator→implementer packet is written and its path recorded in Run Control and as
  550. `worker_packet_path` in `.elves-session.json` — staging is not launch-ready without it. The
  551. per-batch handoff block in the plan and the consolidated staging packet are not substitutes; see
  552. `references/schema-and-acceptance.md`. `acceptance_contract.py validate` warns (advisory, never
  553. blocking) when a delegable session lacks the recorded path. A session may opt into strict explicit
  554. handoff v1 by declaring top-level `handoff` state and the matching leading Markdown or JSON packet
  555. capsule; once declared, state/ownership/repository drift is blocking.
  556. The capsule does not turn a cold handoff into exact-session prewalk.
  557. ### Preflight
  558. ```bash
  559. git remote get-url origin
  560. git push --dry-run 2>&1 | head -3
  561. gh auth status 2>&1 | head -3
  562. python3 "$ELVES_SKILL_ROOT/scripts/acceptance_contract.py" validate \
  563. --repo-root . --session .elves-session.json
  564. ```
  565. **One run owns one branch and one checkout.** Prefer a dedicated worktree when other agents may
  566. touch the repo (`./scripts/preflight.sh --create-worktree <branch> --base origin/main`; `--dry-run`
  567. 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.
  568. 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.
  569. ## Trusted full-run path (normal happy path)
  570. 1. Stage once.
  571. 2. One packet; launch trusted worker (`branch_progress`).
  572. 3. **Park.** Follow sanitized stream by default (`full-run-await`; `--quiet` opt-out). No model
  573. inference; no timed chat updates. See `references/follow-mode.md`.
  574. 4. Worker commits/pushes meaningful progress slices with concrete subjects.
  575. 5. Native Grok goal mode only when capability-proven; otherwise record honest one-packet fallback.
  576. 6. Wake on death, hangs, malformed completion, safety, blockers, material scope/assumption change,
  577. checkpoint, user input, or exit. Pushed progress survives recovery from the verified tip.
  578. 7. Reconcile once. One cumulative terminal review. Consolidate blockers. Revise. Delta re-review.
  579. 8. Attest readiness at exact HEAD. Terminal: landable PR, or merge only if authorized at that HEAD.
  580. Host-native and legacy bounded routes still run the full per-batch loop below. Healthy trusted
  581. full-runs do **not** do per-batch driver review.
  582. ## Core Loop (host-native / legacy bounded / worker-internal quality)
  583. ### 1. Orient
  584. Survival guide → `.elves-session.json` → learnings → plan → execution log → `.ai-docs/manifest.md`
  585. → constitution → TODO.
  586. ### 2. Verify Green
  587. Run gates; capture test baseline. Fix breaks before new work.
  588. ### 3. Rollback Ref
  589. Host-owned `refs/elves/rollback/<run-id>/<session-id>/bN-…` (or single `b0` for trusted full-run).
  590. ### 4. Contract
  591. Behaviors, Build on, acceptance criteria, blast radius. Stable IDs `B#-A#` / `[B#-A#]`.
  592. ### 5. Implement
  593. Pre-implementation survey. Extend existing utilities. Write tests. Commit with progress subjects.
  594. ### 6. Validate
  595. Impact path: changed surface → affected consumer → selected test. Touched-surface proof by default;
  596. broad at high-risk checkpoints and **terminal** (full suite or project full gate). Do not re-run a
  597. large full suite between ordinary batches when the impact path is green. Bug-fix protocol for
  598. blockers: category → category test → fix all. Queue pure advisories under **Deferred hygiene**
  599. (survival guide + execution-log digest); drain at terminal. Details:
  600. `references/validation-guide.md`.
  601. ### 7. Review
  602. Mid-run: contract walk for this batch; no nested full product re-review of settled work. Terminal:
  603. one cumulative review only.
  604. Reviewers read worker confidence trailers/report fields **first** and allocate attention
  605. accordingly: flagged `unsure_about` areas get a deeper pass. The signal is triage, never
  606. authority — it does not skip gates or waive review in either direction. A successful trusted
  607. full-run terminal monitor/await returns `review_context.review_prompt_block`; the coordinator
  608. attaches that machine-produced block verbatim to Final Readiness. For native Claude Code and Codex
  609. workers, build the same triage table from every `Confidence:` trailer in the cumulative commit
  610. history. The reviewer must return a **Confidence-Guided Review** section that names the deeper
  611. passes performed, or explicitly records that signals were partial/absent and baseline review was
  612. used. Claude Code and Codex use this identical contract.
  613. Independent feedback. Walk contract. Enforce code quality. Medium/high blast radius: regression
  614. pass. Fix blocking; advisory does not delay readiness (bank mid-run advisories as deferred hygiene).
  615. 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.
  616. ### 8. Legality Check
  617. If a constitution exists: PASS / WARN / FAIL / UNCHANGED per intention. FAIL blocks.
  618. ### 9–12. Document, survival guide, commit/push, re-read
  619. After every host-owned commit and push, re-read the survival guide before doing anything else.
  620. Do not wait for user acknowledgment.
  621. ### 13. PR Loop
  622. Outside parked full-run: nonblocking new/unresolved poll after host pushes. Terminal readiness waits
  623. for required checks/reviewers. Trusted parked worker pushes defer host PR polling until wake.
  624. Open the draft before parking for bulk execution. Bot feedback enters driver review at the next
  625. safe checkpoint, wake, or terminal reconciliation. Routine comments do not
  626. interrupt a healthy worker. Early bot review never replaces final independent
  627. review of the cumulative diff at the exact head.
  628. ### 14–15. Drift check when evidence warrants; continue or stop
  629. ## Scout Mode
  630. After planned batches, with time remaining: adjacent bugs, tests, docs. Commit format:
  631. `[<branch> · Scout] <verb> <what changed>`.
  632. ## Forbidden Commands
  633. Never: `git reset --hard`, `git checkout .`, `git clean -fd`, force push, rebase on shared branches,
  634. `rm -rf` outside scope, operating on another agent's checkout. Stop on unexpected tip moves
  635. (collision) outside the exact registered trusted full-run exception.
  636. ## Merge Conflicts
  637. Rule out collision first. Otherwise fetch and merge (no rebase). Complex conflicts → Hard Stop.
  638. ## Test Integrity
  639. Never weaken, delete, or skip a test merely to obtain green. Legitimate behavior-driven updates
  640. with preserved/improved coverage and evidence are allowed.
  641. ## Compaction Recovery
  642. 1. Survival guide (Stop Gate + Run Control first)
  643. 2. `.elves-session.json` / `continuation_guard`
  644. 3. Learnings → plan → execution log → `.ai-docs` → constitution
  645. 4. Resume the single next required action immediately
  646. ## Completion Contract
  647. Landable is **plan Acceptance with proof** — not green CI + `status: complete`.
  648. Before batch `status: complete`: **impact** gates green for this batch (not necessarily full-suite
  649. mid-run), regression attestation on the impact path, non-empty
  650. `acceptance: [{id, criterion, met, evidence}]`, PR feedback triaged for blockers, legality clean for
  651. FAIL, docs current for owned surfaces, deferred hygiene updated, session JSON updated, commit
  652. pushed. **God-file rule:** structure locks alone do not complete a split batch unless plan
  653. Acceptance allows characterization-only. Prefer **one batch per close commit**. Terminal readiness
  654. still requires full suite (or project full gate) and drained deferred hygiene.
  655. Landing check (installed):
  656. ```bash
  657. python3 "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py" \
  658. --session <session-path> --repo-root .
  659. ```
  660. Session `plan_path` is authoritative; explicit `--plan` is only an equality assertion. An installed
  661. Elves bundle never requires a repo-only helper.
  662. A repository may track `.elves/landing-profile.json` for bounded declarative project-specific
  663. checks. Schema v1 accepts path co-change checks and post-merge declarations but rejects executable
  664. checks. A missing profile is neutral; a present invalid or blocking-failed profile blocks
  665. readiness. The host recomputes live results and binds exact profile bytes, HEAD, resolved base and
  666. merge base, and normalized outcomes to a host-owned digest; worker reports cannot override them.
  667. Profiles never grant merge, tag, release, protected-ref, connector, secret, or posting authority.
  668. Hosts may record observations, synthesize candidates, and explicitly promote checks, or waive one
  669. blocking check at the exact HEAD; learning state is gitignored runtime data and never auto-promotes.
  670. See `references/project-landing-profiles.md`.
  671. ## Constitution and the Legality Check
  672. Correctness (gates) ≠ plan compliance (review) ≠ legality (judge). The human owns constitutional
  673. intentions. Agent drafts; human owns.
  674. ## Proof and convergent review (v2.3)
  675. See `references/proof-and-review.md`.
  676. - Impact-selected verification; evidence inputs + invalidation scope for reuse
  677. - Mid-run impact path only; terminal full suite + deferred hygiene drain
  678. - One cumulative review: completeness, constitution, declared risks, concrete regressions
  679. - Consolidate blockers before revision; advisory does not delay readiness
  680. - Re-review = revision delta + unresolved blockers only
  681. - New blockers need serious regression / acceptance or constitution breach / security / data
  682. integrity / revision-introduced failure
  683. - Cleanup-only operational changes do not invalidate product proof
  684. - Stop on sufficient exact-tip evidence, not absence of reviewer suggestions
  685. ## Readiness Gate
  686. Branch-level: execution log current, local proof green on current tip, project landing checks green
  687. at the current tip when a profile is present, preview/artifact proof when applicable, plan
  688. Acceptance with proof, landing check clean, final cumulative review clean, PR
  689. comments/checks polled, legality clean, strategic forgetting done, git clean.
  690. Complete-without-merge and complete-and-merge share **one** readiness pipeline.
  691. ## Elves Report
  692. For substantial finite runs, generate static HTML before handoff covering **problems found**,
  693. **lessons learned**, batch timeline, verification proof, residual risks, and human next steps.
  694. 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.
  695. Surface the **Elves Report path** in the final notification. No external assets/scripts. See
  696. `references/elves-report-template.html`.
  697. ## Final Completion
  698. Finite mode only. Acceptance-bearing Final Readiness Review **before** operational-artifact
  699. cleanup. The strict landing check runs on committed session evidence even when the target repository
  700. ignores `.elves-session.json`; see `references/schema-and-acceptance.md` for the force-add and
  701. cleanup sequence. Independent review subagent when available. Then remove survival guide / execution
  702. log / `.elves-session.json` from the PR (keep plan by default; keep learnings). Post-cleanup tip
  703. attestation. Notify with report path. Merge only if authorized — regular merge commit only.
  704. After an authorized merge, tear down the run's own recorded worktree (`worktree_path`):
  705. `./scripts/preflight.sh --gc-worktrees --path <worktree_path>`, report first, then `--apply`;
  706. the `cleanup.worktrees` preference in `config.json.example` records whether teardown runs
  707. on merge, stays report-only, or never runs.
  708. ## Staying Unattended
  709. Never block on prompts. Non-interactive flags. Document decisions. Gates and helper subprocesses
  710. run with closed stdin and explicit timeouts — a silent hang is a failure, not progress. See
  711. `references/autonomy-guide.md`.
  712. ## Ride-Along Protocol
  713. Messages prefixed `[ride-along]`, `ride-along:`, or `ra:`: handle in 1–3 sentences and continue.
  714. Explicit **stop** still halts.
  715. ## Hard Stops
  716. Genuine blocker; merge requested without authorization; destructive action listed as non-negotiable;
  717. collision on branch tip. Everything else: judgment + Decisions made.
  718. ## Structured Session Data
  719. `.elves-session.json` holds `batches` with per-id acceptance evidence, `master_acceptance`,
  720. `continuation_guard`, optional `cobbler` session state, `model_routes`, `review_comments`. After
  721. compaction, trust this file for status. When staging creates a dedicated worktree, record its
  722. path as `worktree_path` alongside `run_id` so post-merge teardown can tell the run's own
  723. worktree from operator-created ones (the schema tolerates extra keys).
  724. ## Persistent Preferences
  725. Safe worker convenience is shared by both hosts at
  726. `${XDG_CONFIG_HOME:-~/.config}/elves/config.json`. Use `cobbler_agents.py preferences
  727. show|set|reset`; writes are private and atomic. Repository safety vetoes outrank everything;
  728. convenience precedence is explicit run intent, repository defaults, global preferences, then
  729. built-ins. Credentials or merge/destructive/protected-ref/approval-bypass authority are rejected.
  730. `config.json` when present also carries legacy batch sizing, notifications, review method,
  731. default branch, and cleanup.
  732. Cobbler under top-level `cobbler` (wins over legacy `council`). See `config.json.example`.
  733. ## Skill Memory
  734. Learnings and `.ai-docs` outlive a single run. Keep them curated. Id-tagged learnings
  735. (`- [L3] …`) are managed by the learnings ledger
  736. (`cobbler_agents.py learnings validate|apply|rollback|digest|migrate`): creates require an
  737. evidence pointer (execution-log entry or commit) and may record an `(expect: …)` validation
  738. note; retire moves entries under Retired Learnings (creating that section at EOF when missing),
  739. never deletes; every applied edit appends before/after to the tracked `learnings-history.jsonl`
  740. sidecar with inverse-edit rollback (**one history row per edit** — one `rollback` undoes only
  741. the latest row; repeat to walk further); the file is written before history so a crash cannot
  742. invent phantom applied edits; and the bounded `## Digest` block is read first at orient, pulling
  743. full entries on demand. Freehand dated learnings stay fully valid; `migrate` is explicit and
  744. idempotent; the ledger never reflows, reorders, or rewrites content it did not edit.
  745. ## v2.24 run tools (host-neutral)
  746. The five v2.24 helpers — futile re-drive guard (`redrive`), learnings ledger (`learnings`),
  747. observed-usage ledger (`usage`), salvage previews (`salvage`), and the continuity watchdog
  748. manager (`continuity`) — are **host-neutral CLI helpers** with identical semantics on Claude
  749. Code, Codex, Grok Build, and Oh My Pi. Invoke as
  750. `python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" <verb> …` from any host; do **not** invent
  751. per-host slash surfaces for them. They are advisory instruments (never landing, merge,
  752. credential, or routing authority). Continuity only writes OS timer templates — Elves never
  753. activates them. Usage is filled only by `usage aggregate --records-file`; close and reconcile
  754. do not write `usage_observed`. Usage ceilings are checkpoints, never stops. See the guide's "v2.24 run tools"
  755. section, `references/host-parity.md`, and `AGENTS.md` (Codex adapter pointer).
  756. `review-route` joins them as a host-neutral helper on the same CLI surface and the same honesty
  757. boundary: it selects an available review route and records requested route, actual route, and
  758. fallback reason. It never claims a review ran and never carries landing, merge, or credential
  759. authority.
  760. ## v2.22 runtime helpers (planning harvest, compact output, lanes)
  761. - **Any-model worker pin:** `resolve_user_specified_worker_model` + handoff cache keys
  762. (`scripts/cobbler_runtime/worker_routing.py`; `references/adaptive-worker-routing.md`).
  763. - **Planning harvest:** `scripts/cobbler_runtime/planning_harvest.py` (beacons, discovery, modes,
  764. lean summary, task sandbox, canvas, mission prep, goal assessor, review filter, merge-recovery lock).
  765. - **Tool output compact:** `scripts/cobbler_runtime/tool_output_compact.py`.
  766. - **Parallelves:** `validate_lane_staging` + `LaneSupervisor` in `parallel_lanes.py`.
  767. - **Fugu module:** `scripts/cobbler_runtime/fugu.py` (shim `run_fugu.sh`).
  768. ## Optional surfaces (outside normal critical path)
  769. Reports, notifications, provider routes, media generation, legacy bounded execution, and untrusted
  770. lanes remain useful but are not the default happy path.
  771. ## Host parity
  772. Claude Code, Codex, Grok Build, and Oh My Pi (omp) provide the same workflow and prewalk safety contract.
  773. Exact-session prewalk preserves the same qualification, trajectory, checkpoint, visibility,
  774. fallback, and authority semantics on every host; supervised transport syntax may differ.
  775. The v2.24 run tools (`redrive`, `learnings`, `usage`, `salvage`, `continuity`, `review-route`) share one CLI
  776. surface and one honesty boundary on every host — see **v2.24 run tools (host-neutral)** above
  777. and `references/host-parity.md`.
  778. **Codex Goals** are optional continuation plumbing — distinct from **Grok Build goal mode**.
  779. ## Compatibility notes
  780. - Missing optional provider access never blocks a native run.
  781. - Record `implementation_lane: fast | untrusted` when using external work drivers.
  782. - Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp). Required prewalk qualifies the
  783. installed transport automatically; experimental prewalk is explicit and still fail-closed during
  784. the real trajectory. Grok as an optional worker under Claude/Codex remains consent-gated.
  785. - 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)

  1. # Elves
  2. ![Elves - they work while you sleep](assets/elves-banner.jpeg)
  3. Elves is an open-source Agent Skill for handing planned development or research work to a separate
  4. worker without locking the run to one model provider. The capable Claude Code, Codex, Grok Build, or
  5. Oh My Pi (omp) driver plans and reviews; a subscription-native (or optional external) worker
  6. implements; durable run files let the work survive context compaction. You write the plan and own
  7. the merge decision. The agent does the middle.
  8. **Current release: v2.40.0**. See [`CHANGELOG.md`](CHANGELOG.md) for version history. Coined terms
  9. are defined once in [`references/glossary.md`](references/glossary.md).
  10. Implementation runs get a draft PR at the first useful pushed commit,
  11. preferably during staging, before bulk execution. The driver opens or reuses
  12. it and checks whether configured bots review drafts. It uses a permitted
  13. documented bot request when needed. If draft review is unavailable, it records
  14. that limit and keeps unfinished work in draft. Bot feedback enters driver
  15. review at safe boundaries. Final independent review still applies. Workers
  16. do not gain PR authority. Read-only audits and harvests do not open PRs.
  17. If staging has no useful diff, a planned worker checkpoint gives the driver
  18. control at the first useful push when the installed route and staging gates
  19. permit it. Otherwise useful staging changes must supply the draft before launch.
  20. The driver opens the draft before bulk
  21. work continues. It checks for the bot's own review, check, or queued job.
  22. **New to Elves?** Use the [practical user guide](https://aigorahub.github.io/elves/) — especially
  23. **[Paste this to your agent](https://aigorahub.github.io/elves/#agent-onboarding)** at the top.
  24. That copy-ready block installs Elves for Claude Code, Codex, Grok Build, and/or Oh My Pi (omp)
  25. (whichever is available) and orients you. The guide also covers the first run, worker choice, live
  26. progress, review, and landing. This README is the repository reference: shell install, safety
  27. model, operations, and an index into the detailed contracts under [`references/`](references/).
  28. **Supported main drivers:** Claude Code, Codex, Grok Build, and Oh My Pi (omp). All four are first-class hosts:
  29. native skill install, doctor validation, automatic required-mode prewalk qualification, and
  30. explicit experimental prewalk. Grok Build is also an optional *worker* under Claude/Codex when
  31. permitted. Oh My Pi is also a main driver (`omp` → `~/.omp/agent/skills/elves`) and an optional
  32. worker under other hosts. Managed install targets: `claude`, `codex`, `grok`, `omp`.
  33. See the guide FAQ
  34. [I opened Grok Build and tried /elves](https://aigorahub.github.io/elves/#troubleshooting).
  35. ---
  36. ## Quick start
  37. Prefer the agent paste in the guide if you already have a supported host open. Otherwise use the
  38. shell one-liners below (Python 3.10+). First-time install needs an explicit host target; `--target
  39. all` only updates hosts that already have an Elves skill root.
  40. ### Windows through WSL2
  41. Elves supports Windows through [WSL2](https://learn.microsoft.com/windows/wsl/install). Native
  42. Win32 execution is not supported. Open PowerShell and check the installed distributions:
  43. ```powershell
  44. wsl --status
  45. wsl --list --verbose
  46. ```
  47. If no distribution is installed, install Ubuntu. If Ubuntu shows version 1, convert it to WSL2:
  48. ```powershell
  49. wsl --install -d Ubuntu
  50. wsl --set-version Ubuntu 2
  51. wsl -d Ubuntu
  52. ```
  53. Docker Desktop's internal WSL distributions do not count as an Elves host. The install doctor
  54. ignores them when it selects a distribution. It reports `wsl_probe_failed` instead of claiming
  55. that no distribution exists when either WSL query fails. Run `wsl --status` and
  56. `wsl --list --verbose` to correct that failure before you retry.
  57. Run the remaining commands inside Ubuntu. Install the Linux prerequisites. Then install Claude
  58. Code, Codex, Grok Build, or Oh My Pi inside the same WSL2 distribution and confirm that its command
  59. is on the Linux `PATH`.
  60. ```bash
  61. sudo apt update
  62. sudo apt install -y git python3 bubblewrap
  63. # Set this to claude, codex, grok, or omp for the host installed inside WSL2.
  64. ELVES_TARGET=codex
  65. ELVES_TMP="$(mktemp -d)"
  66. git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
  67. python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target "$ELVES_TARGET"
  68. case "$ELVES_TARGET" in
  69. claude) ELVES_ROOT="$HOME/.claude/skills/elves" ;;
  70. codex) ELVES_ROOT="$HOME/.codex/skills/elves" ;;
  71. grok) ELVES_ROOT="$HOME/.grok/skills/elves" ;;
  72. omp) ELVES_ROOT="$HOME/.omp/agent/skills/elves" ;;
  73. esac
  74. python3 "$ELVES_ROOT/scripts/install_doctor.py" --doctor
  75. rm -rf "$ELVES_TMP"
  76. ```
  77. Fugu, Grok, and OMP local shortcuts require a qualified `/usr/bin/bwrap` probe. Manus and Devin
  78. perform remote work, but their Bash runners must still start inside WSL2. The doctor reports local
  79. shortcut sandbox readiness separately from external council process-boundary readiness.
  80. ### Install (Claude Code)
  81. ```bash
  82. 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"
  83. ```
  84. This installs `~/.claude/skills/elves/` plus eleven managed alias skills (`/cobbler`,
  85. `/cobbler-mode`, `/council`, `/ec`, `/elves-council`, `/setup-cobbler`, `/setup-council`, `/fugu`,
  86. `/manus`, `/grok`, `/devin`, `/omp`). The sync
  87. helper creates missing aliases and updates only aliases carrying the Elves-managed marker. If it
  88. finds a user-owned alias, it reports the conflict before changing the install and never
  89. overwrites that alias.
  90. ### Install (Codex)
  91. ```bash
  92. 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"
  93. ```
  94. Codex installs the main skill bundle only — no slash aliases. Use `$elves cobbler: <task>` or
  95. natural language such as "Ask the Cobbler…".
  96. Codex users should not need or expect a top-level `/cobbler` command. Do not invent top-level /cobbler.
  97. ### Install (Grok Build)
  98. ```bash
  99. 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"
  100. ```
  101. This installs `~/.grok/skills/elves/` for native Grok Build discovery (first-class host, same
  102. workflow contract as Claude and Codex). No Claude-style slash aliases. Invoke Elves via Grok Build
  103. skill discovery or natural language.
  104. ### Install (Oh My Pi)
  105. ```bash
  106. 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"
  107. ```
  108. This installs `~/.omp/agent/skills/elves/` for native Oh My Pi discovery (first-class host, same
  109. workflow contract as Claude, Codex, and Grok Build). No Claude-style slash aliases. Invoke Elves
  110. via omp skill load or natural language. Elves prewalk is not omp product `--prewalk`. OMP prewalk
  111. accepts `xhigh` and `max` and passes those levels unchanged to `omp --thinking`.
  112. ### Optional provider shortcuts
  113. Focused provider tasks do not require a full Elves run. The contracts below
  114. are unchanged; this section is the readable index. Full requirements, auth
  115. environment names, timeouts, and follow behavior live in
  116. [`references/provider-shortcuts.md`](references/provider-shortcuts.md).
  117. #### Commands
  118. Claude Code:
  119. - `/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`
  120. - `/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`
  121. - `/manus <topic>`
  122. - `/grok <instructions>`
  123. - `/devin <instructions>`
  124. - `/omp <instructions>`
  125. Codex uses the equivalent `$elves fugu|manus|grok|devin|omp …` forms or natural language.
  126. #### Fugu
  127. Plain Fugu supports planning and analysis. `fugu review` keeps the read-only P0-P3 review
  128. contract. Both receive a bounded snapshot of policy-admitted tracked and non-ignored untracked
  129. files. Fugu is limited to planning and read-only review. The runner rejects `--write`.
  130. Profiles:
  131. - regular `fugu/high` (default)
  132. - `--deep` → `fugu/xhigh`
  133. - `--cyber` → `fugu-cyber/xhigh`
  134. - `--ultra` → `fugu-ultra-v2.0/high` when listed, then `fugu-ultra`, then `fugu-ultra-v1.1`
  135. - `--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`.
  136. 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.
  137. `--include` records an exact host-selected path but cannot override exclusions for ignored
  138. trees, credentials, operational state, executable agent configuration, unsafe links/file types, or
  139. repository escapes; the exact path must actually be admitted and copied, and gitignored includes
  140. fail closed before the provider launches (use `--preflight` to check). Both `.env.*` and
  141. `*.env` dotenv-name families plus host-owned internal namespaces are always excluded. macOS read-only cleanup is best-effort,
  142. not proof of recursive descendant absence.
  143. Use `--max-wait` before automatic `--deep`; if any `--include`, run `--preflight` first; prefer
  144. redirect to a log (never `| tail`).
  145. **Host Fugu routing:** when the user says “use Fugu” without an explicit
  146. 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
  147. before launch, and states a short `Fugu route: …` line;
  148. explicit flags always win. The isolation snapshot is always on; the host only adds exact admitted
  149. context via `--include`. See `references/provider-shortcuts.md`
  150. (**Host routing when the user says "use Fugu"**) and `references/fugu-calling-guide.md`.
  151. Regular/deep calls are ephemeral; Ultra and max reserve synthesis time and resume only the
  152. exact isolated session with further tools forbidden. Session state and raw events never leave the
  153. lane; events cross a bounded host-owned pipe, final output remains pinned to a no-follow
  154. 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
  155. Elves' required outer boundary remains authoritative.
  156. Fugu's Linux boundary likewise omits procfs around its credential-bearing
  157. launcher and exposes only a synthetic `/proc/self/exe` symlink to the qualified real Codex
  158. executable.
  159. #### Manus, Devin, and Oh My Pi
  160. Manus supports a normal private
  161. task plus Cobbler-managed `--wide` and deterministic `--fanout` rosters, explicit `--file`
  162. attachments, and duplicate-safe `--resume` that retries only known-failed steps; roster manifests
  163. are validated and exclusively reserved before any upload. A durable pre-create marker prevents
  164. 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
  165. `message`, so the wrapper grants no connector or forced-skill IDs explicitly; the documented API
  166. still loads account-default enabled skills when `enable_skills` is empty, and this route therefore
  167. does not claim skill isolation.
  168. Devin creates
  169. a bounded remote task, including its creation request, without granting stored secrets or knowledge
  170. by default.
  171. Oh My Pi (`/omp` / `$elves omp`) runs headless `omp` over the shared isolation
  172. snapshot with a single provider-matched API key and never modifies the live checkout from the
  173. shortcut (use parked `omp-cli` full-run for implementation labor).
  174. #### Grok
  175. Grok uses
  176. headless mode at `high` reasoning by default, without approval bypass over a disposable tracked-source snapshot in
  177. Elves' required outer kernel sandbox, plus Grok's built-in inner `strict` profile, provider-documented
  178. isolated `dontAsk` settings, and bypass mode locked off. The shortcut requires an explicit
  179. `XAI_API_KEY`; a dedicated Grok tool shell removes both supported key names before any
  180. model-directed command runs, and the Linux boundary omits procfs to prevent parent-environment
  181. inspection. It does not expose a shared OAuth file because Grok applies the same sandbox to
  182. provider and tool reads.
  183. The runner builds argv from the flags the installed Grok Build CLI advertises: an absent safety
  184. flag (isolated `--cwd`, inner `--sandbox strict`, headless `--single`, `--output-format`,
  185. explicit reasoning effort) fails closed, while a quality flag the installed version dropped is
  186. simply not passed. Auto-update is disabled through the isolated `[cli] auto_update` config key
  187. rather than a removed flag. Reasoning effort defaults to `high`; `ELVES_GROK_EFFORT` selects
  188. `low`, `medium`, `high`, or `xhigh`, and `ELVES_GROK_MODEL` pins a model only when the
  189. authenticated live catalog lists it. The runner reports the CLI version, effort, model, the
  190. authentication route the CLI itself names, and any omitted flags.
  191. On a host that cannot nest sandboxes (macOS Seatbelt refuses a second profile inside Elves'
  192. required outer `sandbox-exec` boundary), the runner fails closed with
  193. `grok_inner_sandbox_unavailable` before it builds a snapshot, rather than launching with the
  194. inner profile silently missing. Elves does not drop the inner profile to make a launch succeed,
  195. and the outer boundary is not optional; use a Linux host with the bwrap backend or select
  196. another review route.
  197. **Review snapshot media policy (all harnesses and hosts).** Read-only review snapshots omit
  198. oversized binary media instead of failing the whole review. Video, audio, presentation, archive,
  199. image, font, and 3D binaries above the per-file limit are left out of the snapshot; the 16 MiB
  200. per-file limit is not raised. The context manifest records each omitted path, byte size, and
  201. reason, and every runner prints the same omission block. Source, prose instructions, executable
  202. agent configuration, and explicit `--include` paths still fail closed, with a remediation that asks
  203. for a derived text, image, or transcript artifact. Writable lanes keep fail-closed behavior.
  204. **Fugu is optional (review route fallback).** When a review route is unavailable because of quota,
  205. authentication, catalog, runner, timeout, or provider failure, probe the supported review routes
  206. and select another available independent reviewer instead of stopping. Preserve an explicit user
  207. route when it works; otherwise prefer a supported native reviewer when no optional provider works.
  208. Record requested route, actual route, and fallback reason. Do not claim a review ran when it did
  209. not, and do not let optional-provider failure block the run while a qualified review route exists.
  210. Host-neutral helper: `python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host
  211. <host> --requested <route> --unavailable <route>=<reason>`.
  212. ### Per-project install
  213. Clone into `.claude/skills/elves`, `.codex/skills/elves`, `.grok/skills/elves`, or
  214. `.omp/agent/skills/elves` inside your repo (remove the nested `.git`), or prefer
  215. `scripts/sync_installed_skills.py` over hand-maintaining a second tree.
  216. ### Validate the install
  217. ```bash
  218. # Claude Code:
  219. python3 ~/.claude/skills/elves/scripts/install_doctor.py --startup
  220. # Codex:
  221. python3 ~/.codex/skills/elves/scripts/install_doctor.py --startup
  222. # Grok Build:
  223. python3 ~/.grok/skills/elves/scripts/install_doctor.py --startup
  224. # Oh My Pi:
  225. python3 ~/.omp/agent/skills/elves/scripts/install_doctor.py --startup
  226. ```
  227. ### Update or uninstall
  228. ```bash
  229. # Update every host that already has Elves installed:
  230. python3 /path/to/elves/scripts/sync_installed_skills.py --apply --target all
  231. # Or update one host:
  232. python3 /path/to/elves/scripts/sync_installed_skills.py --apply --target grok
  233. # Uninstall: remove the skill root you installed (and Claude aliases only if you want them gone):
  234. rm -rf ~/.claude/skills/elves ~/.codex/skills/elves ~/.grok/skills/elves ~/.omp/agent/skills/elves
  235. ```
  236. ### No plan yet? Start with Discovery
  237. When you do not know what to work on, ask for a survey instead of a run:
  238. > Do a discovery pass on this repo and tell me what is worth doing.
  239. Discovery is read-only on source. It sweeps the repository against the nine categories in
  240. [`references/audit-playbook.md`](references/audit-playbook.md), returns findings ranked by impact
  241. over effort, and writes nothing outside `advisor-plans/`. Every finding cites `file:line` and a
  242. concrete effect, so "probably slow somewhere" never reaches you. "Not worth doing" is a recorded
  243. verdict, not a silent omission.
  244. Findings you pick become self-contained executor plans in `advisor-plans/`, one per finding, using
  245. [`references/finding-plan-template.md`](references/finding-plan-template.md). Those plans feed the
  246. normal run below. Findings you do not pick are filed with `gh issue create` rather than carried in
  247. anyone's memory.
  248. ### First run
  249. Write a plan (start from [`references/plan-template.md`](references/plan-template.md)), then say,
  250. from your project:
  251. > Implement docs/plans/my-feature.md as an elves run while I'm offline.
  252. The driver stages the run (run docs, branch, dedicated worktree when other agents may touch the
  253. repo, worker packet for delegable runs, preflight), launches the worker, reviews cumulatively,
  254. and stops at a **landable PR** (chat-to-work). Merging happens only when you say so — an explicit
  255. in-session authorization (chat-to-land) or the reviewed-landing command `\land-pr` / `/land-pr`.
  256. See [`references/e2e-chat-to-land.md`](references/e2e-chat-to-land.md) and
  257. [`references/kickoff-prompt-template.md`](references/kickoff-prompt-template.md).
  258. For a machine-checked cold handoff, the session may opt into explicit handoff v1: exact state,
  259. acceptance ownership, branch/HEAD, and a matching bounded Markdown or JSON packet capsule. The
  260. ordinary v2.8 path remains advisory when this schema is absent. The capsule is not prewalk continuity proof.
  261. See [`references/schema-and-acceptance.md`](references/schema-and-acceptance.md).
  262. Projects with deterministic repository-specific landing rituals may track
  263. `.elves/landing-profile.json`. Its declarative path co-change checks are evaluated at the exact
  264. HEAD/base/merge-base and bound to a host-owned digest; schema v1 rejects executable checks and
  265. never launches profile-directed processes. Missing profiles are neutral; profiles can block
  266. readiness but never grant merge, tag, release, protected-ref, secret, connector, or posting
  267. authority. Hosts may `observe` landings, `propose` candidates, explicitly `promote` into the tracked
  268. profile, and apply exact-HEAD `waive` entries — with no auto-promotion. See
  269. [`references/project-landing-profiles.md`](references/project-landing-profiles.md).
  270. ---
  271. ## Who implements
  272. **Default: a subscription-native worker** on the live host (Claude Code, Codex, Grok Build, or Oh My Pi) in a
  273. separate exact session — no external provider required. Optional work drivers when configured and
  274. permitted: trusted Grok Build full-run under Claude/Codex, Devin CLI, or other adapters. Missing
  275. optional provider access never blocks a native run. Repository `allow_grok=false` is an absolute
  276. veto. The host owns packets, protected refs, final gates, PR, and merge — always. Details:
  277. [`references/adaptive-worker-routing.md`](references/adaptive-worker-routing.md),
  278. [`references/prewalk.md`](references/prewalk.md),
  279. [`references/grok-open-source-worker.md`](references/grok-open-source-worker.md),
  280. [`references/grok-implementer-launch-prompt.md`](references/grok-implementer-launch-prompt.md),
  281. [`references/omp-worker.md`](references/omp-worker.md) (Oh My Pi main driver + optional `omp-cli` / `/omp` worker).
  282. Parallel implementation lanes are optional and never the default: serial stays the default, and
  283. `worker.parallel=auto` only recommends lanes when the deterministic width test passes; see
  284. [`references/parallelves.md`](references/parallelves.md).
  285. Trusted Grok implementation launches use `--always-approve` alone: Grok Build treats an explicit
  286. `--permission-mode auto` as an override, so the two flags must not be combined.
  287. Native delegation names both model and effort, and stays inside one model family. GPT-6 Astra
  288. `ultra`/`max`/`xhigh` hands off to the same GPT-6 Astra model at `medium`; GPT-5.6
  289. `xhigh`/extra-high/`ultra` hands off to the same GPT-5.6 model at `medium`; GPT-4.8 Max/UltraCode to
  290. 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
  291. `max`/`ultracode` to the same Opus 5.5 model at `high`. There is no Fable→Opus route. A Fable driver
  292. hands off to `claude-fable-5-1` at `low` rather than crossing families. The one cross-family worker is
  293. the opt-in Grok handoff, which prefers `grok-4.7` at explicit `high` when the live catalog returns
  294. it, then `grok-4.6`, then `grok-4.5`. Composer 2.5 (`grok-composer-2.5-fast`) is retired and is never selected.
  295. ### Optional exact-session prewalk
  296. Prewalk lets one worker orient on a guide model/effort, create a bounded TODO, make
  297. the first real edit, and then resume the **same session in the same worktree** on the execution
  298. route. The packet is sent once; the resume input is only `Continue.`. A new worker that receives a
  299. summary is a normal cold handoff, not prewalk, and cold fallback is forbidden after an edit.
  300. The safe preference is `worker.prewalk: "auto"`, while the launch CLI defaults to `off` for backward
  301. compatibility. `auto` makes no qualification model calls and reuses only matching cached proof.
  302. `required` automatically runs a 180-second, 1 MiB-bounded live canary when proof is absent. The
  303. task worker starts only after session, worktree, stream, route-change, retained-context, and
  304. packet-count checks pass; failure stops with a private evidence path. `experimental` explicitly
  305. accepts qualification uncertainty after static grammar inspection, reports that status, and keeps
  306. every real-run continuity and authority check. Claude Code, Codex, Grok Build, and Oh My Pi share
  307. these semantics. Grok single-phase native-worker launch remains registry-gated. OMP prewalk accepts
  308. `xhigh` and `max` and passes them unchanged to `omp --thinking`. See the
  309. [normative prewalk contract](references/prewalk.md) and
  310. [host parity matrix](references/host-parity.md).
  311. ## Safety model
  312. **The user owns whether Elves may merge.** The worker never merges; the driver merges only with
  313. an explicit opt-in recorded in Run Control, and only with a regular merge commit after final
  314. readiness — never a squash. Readiness (plan Acceptance with proof at the exact HEAD) and merge
  315. authority are independent; **Landable is plan Acceptance with proof**, not green CI plus
  316. `status: complete`.
  317. **Thin safety kernel** (never weakened): exact plan/session/packet acceptance identity;
  318. credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, and redaction checks; no
  319. worker merge/tag/protected-ref/PR/landing authority; test integrity; independent terminal review;
  320. final CI.
  321. The optional **continuity watchdog** stays outside the kernel's authority surfaces: an
  322. operator-owned OS timer that Elves never activates itself, detect-and-report by default, and
  323. every safety decision delegated to `full-run-prepare --resume` — it never resumes a terminal
  324. run and holds no landing, merge, or credential authority
  325. (`references/operations-guide.md`).
  326. **Forbidden commands.** Never: `git reset --hard`, `git checkout .`, `git clean -fd`, force push,
  327. rebase on shared branches, `rm -rf` outside scope, operating on another agent's checkout.
  328. **One run owns one branch and one checkout.** Prefer a dedicated worktree when other agents may
  329. touch the repo (`./scripts/preflight.sh --create-worktree <branch> --base origin/main`;
  330. `--dry-run` first). The helper prints the branch, worktree path, base ref, and collision tripwire,
  331. and does not reuse, delete, or repair existing worktrees. `START_TIP` is the collision tripwire:
  332. any unexplained tip move is a collision and a Hard Stop.
  333. **Worktree lifecycle.** Staging records the created worktree path in `.elves-session.json`;
  334. after merge, the run's worktree is reclaimed with the separate gc helper
  335. (`./scripts/preflight.sh --gc-worktrees`; report by default, `--apply` removes only clean, fully
  336. merged, fully pushed worktrees; unregistered sibling directories are listed and never deleted).
  337. Installed skill bundles ship `scripts/worktree_gc.py` with that helper (and
  338. `scripts/provider_supervisor.py` for full-run provider supervision). Historical `docs/plans/` and
  339. source-repo `docs/elves/` archives stay source-checkout only — never part of the installed skill.
  340. **Unattended by construction.** Gates and helper subprocesses run with closed stdin and explicit
  341. timeouts — a silent hang is a failure, not progress. Worker failures split into transient
  342. (backoff and resume; never consumes the re-drive budget) and substantive (budgeted re-drives,
  343. then split or host-native takeover). Workers keep an untracked progress ledger under
  344. `.elves/runtime/` so recovery starts oriented. See SKILL.md's Worker failure recovery and
  345. [`references/autonomy-guide.md`](references/autonomy-guide.md).
  346. ## What can go wrong
  347. Overnight agent runs fail in predictable ways. Knowing the failure modes makes them preventable.
  348. | Failure | What happens | Mitigation |
  349. |---|---|---|
  350. | **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. |
  351. | **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. |
  352. | **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. |
  353. | **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. |
  354. | **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. |
  355. | **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. |
  356. | **Terminal closes (SSH disconnect)** | The SSH connection drops and the session dies. | Use `tmux` or `screen`. See the [operations guide](references/operations-guide.md). |
  357. | **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. |
  358. | **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. |
  359. | **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. |
  360. Most of these are prevented by the preflight checks. Run preflight, fix the warnings, and most
  361. overnight failures never happen.
  362. ---
  363. ## Configuration
  364. ### Persistent preferences
  365. Copy [`config.json.example`](config.json.example) to `config.json` in your installed skill or
  366. project-local skill when you want defaults to persist across sessions. Put new Cobbler preferences
  367. under the top-level `cobbler` block. The legacy `council` block is for compatibility with older
  368. projects; if both blocks are present, `cobbler` wins. Math preferences belong under `math`.
  369. Shared safe worker convenience also lives at `${XDG_CONFIG_HOME:-~/.config}/elves/config.json`
  370. via `cobbler_agents.py preferences show|set|reset`.
  371. ### Tool configuration
  372. Tool-specific configuration lives in the survival guide under `## Tool Configuration` — the
  373. agent's instructions stay with the session. Minimal example:
  374. ```markdown
  375. ## Tool Configuration
  376. ### Validation Gates
  377. - lint: `npm run lint`
  378. - typecheck: `npm run typecheck`
  379. - build: `npm run build`
  380. - test: `npm test`
  381. ### Review
  382. - method: github-pr-comments
  383. ```
  384. If you don't configure validation gates, Elves auto-discovers them from your project files
  385. (`package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`). Full examples:
  386. [`references/tool-config-examples.md`](references/tool-config-examples.md).
  387. ### Batch sizing
  388. The default batch size is what a team of 4 developers would accomplish in a 2-week sprint. Each
  389. batch must be independently shippable: code, tests, docs, and passing review before moving on.
  390. Override in your plan or survival guide:
  391. ```markdown
  392. ## Batch Sizing
  393. - team-size: 2
  394. - sprint-length: 1 week
  395. ```
  396. ### Review methods
  397. | Tier | Method | Configuration |
  398. |---|---|---|
  399. | **Tier 1** | GitHub PR comments + built-in review | Default (zero config). |
  400. | **Tier 2** | Custom review API | Set `method: custom-api` and `review-api-url` in survival guide. |
  401. | **Tier 3** | Additional checks | Smoke tests, screenshot diffs, or any custom script returning 0/non-zero. |
  402. The agent uses the highest tier you have configured. Persistent false positives (3+ cycles) are
  403. dismissed with a written explanation in the execution log.
  404. Worker confidence now actively guides the primary review on both Claude Code and Codex. Trusted
  405. full-runs return a bounded machine-produced review block at terminal; native workers supply the
  406. same information through `Confidence:` commit trailers. The reviewer starts with that triage,
  407. deep-checks every reservation, low-confidence or conflicting area, and reports what it verified.
  408. Missing signals fall back to the full baseline review, and high confidence never reduces gates or
  409. review scope. See [`references/review-subagent.md`](references/review-subagent.md).
  410. ### Memory hygiene
  411. Long runs clean up as they go: keep live docs concise, archive old execution-log entries, promote
  412. durable lessons, stop idle resources, and write a reactivation handoff when a fresh thread would
  413. be faster. Elves does **not** delete local app state, chat databases, installed skills, plugins,
  414. or automations as part of a coding run. For explicit local maintenance, see the safe-maintenance
  415. pattern in [`references/autonomy-guide.md`](references/autonomy-guide.md).
  416. ---
  417. ## Repository reference index
  418. The compact canonical workflow is [`SKILL.md`](SKILL.md); [`AGENTS.md`](AGENTS.md) is the thin
  419. Codex adapter (invocation surface only — same workflow, same safety). Each contract lives in
  420. exactly one file below; other docs link instead of restating.
  421. **Elves (Grok Bot):** [`skills/elves-grok-bot/SKILL.md`](skills/elves-grok-bot/SKILL.md) is the
  422. unattended-run kernel for Grok Bot non-git work (HubSpot, Gmail, LinkedIn, CRM). Grok Bot is
  423. not Grok Build and not a fifth coding host. Technical name `elves-grok-bot`; invoked via
  424. natural "use elves", not `/goal`. Four files, Stop Gate, 1-minute watchdog, one fire at a
  425. time, terminal status, intent-before-send. Not for coding runs — root `SKILL.md` remains
  426. authoritative for Claude Code, Codex, Grok Build, and Oh My Pi code work.
  427. **Run lifecycle**
  428. - [`references/plan-template.md`](references/plan-template.md) — how to write a plan (stable
  429. `B#-A#` acceptance ids)
  430. - [`references/audit-playbook.md`](references/audit-playbook.md) — Discovery audit categories,
  431. the evidence rule, and the leverage rubric
  432. - [`references/finding-plan-template.md`](references/finding-plan-template.md) — per-finding
  433. executor handoff (distinct from `plan-template.md`, which shapes a batched run)
  434. - [`references/kickoff-prompt-template.md`](references/kickoff-prompt-template.md) — staging
  435. kickoff, including the worker packet and teardown expectations
  436. - [`references/survival-guide-template.md`](references/survival-guide-template.md) — Run Control,
  437. Stop Gate, compaction recovery, and the Out-of-scope findings ledger
  438. - [`references/execution-log-template.md`](references/execution-log-template.md),
  439. [`references/learnings-template.md`](references/learnings-template.md) — run memory
  440. - [`references/schema-and-acceptance.md`](references/schema-and-acceptance.md) — session schema,
  441. acceptance identity, worker packet at staging, work-driver spellings, landing/cleanup order
  442. - [`references/landing-authority.md`](references/landing-authority.md) — readiness vs merge
  443. authority
  444. - [`references/e2e-chat-to-land.md`](references/e2e-chat-to-land.md) — the end-to-end paths
  445. **Delegation and providers**
  446. - [`references/joyful-runs-contract.md`](references/joyful-runs-contract.md) — full-run operator
  447. contract (canonical code: `scripts/cobbler_runtime/canonical_contract.py`)
  448. - [`references/adaptive-worker-routing.md`](references/adaptive-worker-routing.md) — who
  449. implements and why
  450. - [`references/prewalk.md`](references/prewalk.md) — exact-session guide→execution trajectory,
  451. qualification, checkpoints, and recovery
  452. - [`references/parallelves.md`](references/parallelves.md) — Cobbler-coordinated parallel
  453. implementation lanes: serial default, recommend-only width test, trunk -> lanes -> integration
  454. - [`references/follow-mode.md`](references/follow-mode.md) — the parked driver's sanitized stream
  455. - [`references/grok-open-source-worker.md`](references/grok-open-source-worker.md) and
  456. [`references/grok-implementer-launch-prompt.md`](references/grok-implementer-launch-prompt.md)
  457. — external workers
  458. - [`references/model-onboarding.md`](references/model-onboarding.md),
  459. [`references/cobbler-setup-recipes.md`](references/cobbler-setup-recipes.md) — setup
  460. - [`references/provider-shortcuts.md`](references/provider-shortcuts.md) — focused Fugu,
  461. Manus, Grok Build, and Devin command routes
  462. - [`references/omp-worker.md`](references/omp-worker.md) — Oh My Pi main driver and optional `omp-cli` / `/omp` worker
  463. - [`references/host-parity.md`](references/host-parity.md) — Claude Code / Codex parity
  464. - [`references/project-landing-profiles.md`](references/project-landing-profiles.md) — tracked
  465. repository-specific exact-HEAD readiness checks
  466. **Quality and proof**
  467. - [`references/proof-and-review.md`](references/proof-and-review.md) — impact-selected proof,
  468. convergent review
  469. - [`references/verification-patterns.md`](references/verification-patterns.md),
  470. [`references/validation-guide.md`](references/validation-guide.md) — gates
  471. - [`references/review-subagent.md`](references/review-subagent.md) — independent review
  472. - [`references/autonomy-guide.md`](references/autonomy-guide.md) — staying unattended
  473. - [`references/operations-guide.md`](references/operations-guide.md) — sleep prevention, tmux,
  474. monitoring, notifications, SessionStart hook, daily briefing
  475. **Domain workflows**
  476. - [`references/math-workflow.md`](references/math-workflow.md) and the `references/math-*.md`
  477. family — the math research pack
  478. - [`references/open-ended-guide.md`](references/open-ended-guide.md) — open-ended runs
  479. - [`references/council-workflow.md`](references/council-workflow.md),
  480. [`references/council-prompts.md`](references/council-prompts.md),
  481. [`references/councilelves-launch-prompt.md`](references/councilelves-launch-prompt.md) — legacy
  482. Council surfaces (Council is a deprecated alias of Cobbler)
  483. **Templates and reports**
  484. - [`references/elves-report-template.html`](references/elves-report-template.html) — end-of-run
  485. report
  486. - [`references/runtime-helper-paths.md`](references/runtime-helper-paths.md) — installed vs
  487. source-checkout helper paths
  488. ## Maintainers' gates (this repository)
  489. ```bash
  490. # Elves source checkout:
  491. python3 scripts/verify_repo.py --ci
  492. # before operational-artifact cleanup, from a clean worktree:
  493. python3 scripts/verify_repo.py --final-readiness \
  494. --session .elves-session.json
  495. # after the narrow operational-artifact cleanup commit, on its clean current tip:
  496. python3 scripts/verify_repo.py --ci --base-ref origin/main
  497. test -z "$(git status --porcelain)"
  498. ```
  499. These are maintainers' gates for this source checkout; the repo-only helper is not shipped in a
  500. global skill install. Installed runs use their target project's gates plus the installed
  501. `elves_landing_check.py` (see
  502. [`references/runtime-helper-paths.md`](references/runtime-helper-paths.md)):
  503. ```bash
  504. python3 "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py" \
  505. --session <session-path> --repo-root .
  506. ```
  507. When the target tracks `.elves/landing-profile.json`, the landing check evaluates it automatically.
  508. The standalone installed command is:
  509. ```bash
  510. python3 "$ELVES_SKILL_ROOT/scripts/landing_profile.py" check \
  511. --repo-root . --base origin/main --json
  512. ```
  513. Learning commands (`observe`, `propose`, `candidates`, `promote`, `waive`, `clear-waiver`) use the
  514. same CLI. Only `promote` rewrites the tracked profile; runtime learning state stays under
  515. `.elves/runtime/landing-profile/`.
  516. Intentional source-checkout public-API breaks must be declared in the tracked
  517. `api-break-approvals.json` for the exact `--version`. Every entry names one surface, a non-empty
  518. reason, and a tracked in-repo plan. Strict verification rejects malformed, stale, untracked, or
  519. plan-less approvals.
  520. ## File structure
  521. ```text
  522. elves/
  523. ├── SKILL.md # canonical workflow (all hosts)
  524. ├── AGENTS.md # thin Codex adapter
  525. ├── README.md # this file
  526. ├── CHANGELOG.md # version history (the only home of "vX adds…")
  527. ├── config.json.example # persistent preferences
  528. ├── aliases/ # managed Claude Code alias skills
  529. ├── guide/ # published user guide (GitHub Pages)
  530. ├── references/ # one authoritative file per contract (see index)
  531. ├── scripts/ # helpers + cobbler_runtime package
  532. ├── tests/ # unittest suite (hermetic: fd-0 devnull guard)
  533. └── .ai-docs/ # durable architecture/conventions/gotchas
  534. ```
  535. ## Platform support
  536. | Platform | File | Subagents | Notes |
  537. |---|---|---|---|
  538. | Claude Code | SKILL.md | Yes | Full feature set |
  539. | Codex | SKILL.md | Varies | Use review subagents when available; otherwise do the review directly. `AGENTS.md` remains the repo-local Codex companion |
  540. | Claude.ai | SKILL.md (zip upload) | No | Upload as skill |
  541. | Any Agent Skills compatible | SKILL.md | Varies | Open standard |
  542. ## Philosophy
  543. Convert idle hours into shipped code: try, check, feed back, repeat. Memory lives in files, not
  544. chat. Root cause over band-aids; centralize over duplicate; extend over create; favor boring
  545. technology. The human owns what is worth building and whether it merges — the agent owns the
  546. middle.
  547. Agy reviews always use `/boost` in plan mode, including reviews of fixes.
  548. The reviewer uses a separate session from the code writers. Boost failure
  549. requires an authorized independent fallback or a block; a plain Agy response
  550. does not satisfy review. Pass the absolute admitted workspace to all Boost
  551. workers. Use a supervised terminal when headless transport is unqualified.
  552. Keep required isolation. Approve scoped review actions and wait for child
  553. completion plus a final report at the exact commit. Headless success alone
  554. does not prove a review. See [the review rules](references/review-subagent.md).
  555. A clean Agy review also needs context coverage. Read changed files, relevant
  556. callers, tests, instructions, and task docs. The host checks the coverage
  557. record against the diff and read evidence. Missing required context blocks
  558. a clean result.
  559. ## Contributing
  560. Issues and pull requests are welcome. If you find a bug, have a feature idea, or want to add
  561. support for a new platform or tool, open an issue to discuss it first.
  562. When submitting a PR:
  563. - Keep changes focused: one concern per PR.
  564. - Update the relevant template or reference file if your change affects agent behavior.
  565. - Test your change with at least one real overnight run if possible.
  566. - For cross-file skill/doc changes, run:
  567. ```bash
  568. python3 scripts/check_repo_consistency.py
  569. ```
  570. ## Disclaimer
  571. This software is provided "as is", without warranty of any kind, express or implied. Neither
  572. Aigora nor John Ennis are liable for any claims, damages, or other liability arising from using
  573. this software. That includes code changes, data loss, security incidents, infrastructure costs, or
  574. anything else that happens. The [MIT license](LICENSE) already says this, but we want to be clear
  575. about it here too.
  576. Elves expects you to grant your AI agent the permissions it needs to run autonomously. That might
  577. mean file system access, git push, GitHub CLI auth, shell command execution, or other tool
  578. approvals depending on your platform. If the agent has to pause and wait for permission during an
  579. unattended run, it'll stall. So the skill works best when you pre-approve what the agent will
  580. need. You're granting those permissions at your own risk. Know what you're allowing before you
  581. walk away.
  582. There's nothing uniquely dangerous about Elves. It uses standard tools (git, GitHub, your existing
  583. test suite) and it has safety measures (forbidden commands, test integrity rules, scoped rollback
  584. refs). But no software is foolproof, and an agent running for hours with broad permissions can
  585. make mistakes. Always review the PR before merging.
  586. ## License
  587. MIT, see [LICENSE](LICENSE).
  588. Copyright (c) 2026 Aigora.
  589. ## Teams on one task
  590. Ask for a driver with helpers, or ask several models to propose and compare
  591. solutions. Elves uses its existing model routes. It records contributor identities
  592. and keeps the landing reviewer independent. Optional Lantern reports arrive at
  593. driver checkpoints. Persistent writer lanes check dependencies, worktree identity,
  594. and actual changed files before driver integration.
  595. 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
  1. """Declarative repo-consistency policy inventory and phrase scenarios.
  2. Extracted from check_repo_consistency.py so the generic engine stays small.
  3. Semantic/mutation tests assert behavior, not preferred marketing phrases alone.
  4. """
  5. from __future__ import annotations
  6. from pathlib import Path
  7. REPO_ROOT = Path(__file__).resolve().parent.parent
  8. VERSION_FILES = {
  9. "SKILL.md": REPO_ROOT / "SKILL.md",
  10. "AGENTS.md": REPO_ROOT / "AGENTS.md",
  11. }
  12. # Surfaces that display the release version in prose rather than frontmatter.
  13. # VERSION_FILES only reads frontmatter, so these are invisible to it and can ship
  14. # stale behind a green check. `{version}` is substituted with the repo skill version.
  15. INLINE_VERSION_SURFACES = {
  16. "SKILL.md": ["User guide (v{version})"],
  17. "README.md": ["**Current release: v{version}**"],
  18. "guide/index.html": ["v{version} source and releases"],
  19. }
  20. CHANGELOG_PATH = REPO_ROOT / "CHANGELOG.md"
  21. RECOVERY_ORDER_FILES = {
  22. "SKILL.md": REPO_ROOT / "SKILL.md",
  23. "AGENTS.md": REPO_ROOT / "AGENTS.md",
  24. "references/kickoff-prompt-template.md": REPO_ROOT / "references" / "kickoff-prompt-template.md",
  25. "references/survival-guide-template.md": REPO_ROOT / "references" / "survival-guide-template.md",
  26. }
  27. RECOVERY_ORDER_TOKENS = [
  28. "survival guide",
  29. ".elves-session.json",
  30. "learnings",
  31. "plan",
  32. "execution log",
  33. ".ai-docs/manifest.md",
  34. ]
  35. PENDING_DOCS_FILES = {
  36. "SKILL.md": REPO_ROOT / "SKILL.md",
  37. "AGENTS.md": REPO_ROOT / "AGENTS.md",
  38. "references/review-subagent.md": REPO_ROOT / "references" / "review-subagent.md",
  39. }
  40. DURABLE_DOCS = [
  41. REPO_ROOT / "docs" / "elves" / "learnings.md",
  42. REPO_ROOT / ".ai-docs" / "manifest.md",
  43. REPO_ROOT / ".ai-docs" / "architecture.md",
  44. REPO_ROOT / ".ai-docs" / "conventions.md",
  45. REPO_ROOT / ".ai-docs" / "gotchas.md",
  46. REPO_ROOT / ".ai-docs" / "context-index.md",
  47. REPO_ROOT / "references" / "learnings-template.md",
  48. ]
  49. NONSTOP_GUARDRAIL_PHRASES = {
  50. "SKILL.md": [
  51. "Stop Gate",
  52. "continuation_guard",
  53. "After every host-owned commit and push, re-read the survival guide before doing anything else.",
  54. "Do not wait for user acknowledgment",
  55. ],
  56. "references/survival-guide-template.md": [
  57. "## Stop Gate",
  58. "## Forbidden Stop Reasons",
  59. "Stop allowed right now",
  60. "Every completed batch must end with a commit and push",
  61. "continue without waiting for user acknowledgment",
  62. ],
  63. "references/kickoff-prompt-template.md": [
  64. "Every completed batch must end with a commit and push before you start anything else.",
  65. "Immediately after every commit and push, re-read the survival guide before any other action.",
  66. "Do not send a final response unless the survival guide Stop Gate says stopping is allowed or a true blocker forces it.",
  67. ],
  68. "references/open-ended-guide.md": [
  69. "## Stop Gate Pattern",
  70. "## Forbidden Stop Reasons",
  71. "continuation_guard.stop_allowed: false",
  72. ],
  73. }
  74. # Discovery phase: the read-only survey that precedes Planning when no task is named.
  75. # Anchors only. The boundary (read-only on source, writes confined to advisor-plans/)
  76. # and the two contracts (evidence, leverage) must restate wherever Discovery appears.
  77. DISCOVERY_GUARDRAIL_PHRASES = {
  78. "SKILL.md": [
  79. "## Discovery",
  80. "**read-only on source**",
  81. "advisor-plans/",
  82. "references/audit-playbook.md",
  83. "references/finding-plan-template.md",
  84. "gh issue create",
  85. ],
  86. "references/audit-playbook.md": [
  87. "## Finding format",
  88. "## Prioritization rubric",
  89. ],
  90. "references/finding-plan-template.md": [
  91. "advisor-plans/NNN-short-slug.md",
  92. "zero context",
  93. ],
  94. "README.md": [
  95. "references/audit-playbook.md",
  96. ],
  97. }
  98. # Out-of-scope findings: work a run notices that the plan does not cover. The rule is
  99. # "file it, never fix it, never drop it", and it must reach the worker-facing surfaces,
  100. # not only SKILL.md. Anchors only.
  101. OUT_OF_SCOPE_GUARDRAIL_PHRASES = {
  102. "SKILL.md": [
  103. "## Out-of-Scope Findings",
  104. "gh issue create",
  105. "never file a duplicate",
  106. "deferred hygiene",
  107. "Scout Mode",
  108. ],
  109. "references/survival-guide-template.md": [
  110. "## Out-of-scope findings",
  111. "Filed this run:",
  112. "Could not file:",
  113. ],
  114. "references/kickoff-prompt-template.md": [
  115. "do not fix it and do not widen the batch",
  116. "gh issue create",
  117. ],
  118. }
  119. # Section/contract anchors only — do not pin motivational prose byte-for-byte.
  120. # Editorial rewording of effort guidance must not break CI.
  121. EFFORT_GUARDRAIL_PHRASES = {
  122. "SKILL.md": [
  123. "## Effort Standard",
  124. "Work as hard as you can",
  125. "plan acceptance and blockers",
  126. "deferred hygiene",
  127. ],
  128. "references/survival-guide-template.md": [
  129. "## Effort Standard",
  130. "Work as hard as you can",
  131. "## Deferred hygiene",
  132. "impact path mid-run",
  133. ],
  134. "references/kickoff-prompt-template.md": [
  135. "Work as hard as you can",
  136. "Do not coast after the first success",
  137. "deferred hygiene",
  138. "impact-path",
  139. ],
  140. "references/open-ended-guide.md": [
  141. "## Sustain Effort",
  142. "Work as hard as you can",
  143. "deferred hygiene",
  144. "impact path",
  145. ],
  146. }
  147. # Mid-run impact path vs terminal full suite + deferred hygiene (v2.20.0).
  148. # Without these pins, validation-guide can reintroduce "zero debt every batch" and
  149. # fight the proof budget again.
  150. MIDRUN_TERMINAL_HYGIENE_PHRASES = {
  151. "SKILL.md": [
  152. "deferred hygiene",
  153. "impact path",
  154. "full suite",
  155. "validate once, verify changes, attest final",
  156. ],
  157. "references/validation-guide.md": [
  158. "validate once, verify changes, attest final",
  159. "Deferred hygiene",
  160. "Mid-run vs terminal",
  161. "impact path",
  162. "weaken, skip, or delete tests",
  163. ],
  164. "references/proof-and-review.md": [
  165. "deferred hygiene",
  166. "full suite",
  167. "impact path",
  168. "per-batch driver reviews",
  169. ],
  170. "references/survival-guide-template.md": [
  171. "Deferred hygiene",
  172. "full suite at terminal",
  173. "impact-selected proof during work",
  174. ],
  175. "references/execution-log-template.md": [
  176. "Deferred hygiene",
  177. ],
  178. }
  179. FINAL_READINESS_REVIEW_PHRASES = {
  180. "SKILL.md": [
  181. "Final Readiness Review",
  182. "git diff <default-branch>...HEAD",
  183. "review subagent",
  184. ],
  185. "references/review-subagent.md": [
  186. "## Final Readiness Review",
  187. "git diff [DEFAULT_BRANCH]...HEAD",
  188. ],
  189. "references/kickoff-prompt-template.md": [
  190. "Require a final readiness review",
  191. "git diff <default-branch>...HEAD",
  192. ],
  193. }
  194. SINGLE_KICKOFF_PHRASES = {
  195. "SKILL.md": [
  196. "Default user path: one kickoff",
  197. "Trusted full-run delegation keeps that path",
  198. "chat-to-work",
  199. "chat-to-land",
  200. "Legacy two-call handoff",
  201. "full-run",
  202. "parked",
  203. ],
  204. "references/kickoff-prompt-template.md": [
  205. "Recommended: one kickoff",
  206. "trusted full-run / parked-monitor",
  207. "Chat-to-work (E2E, no merge)",
  208. "Chat-to-land (E2E through merge)",
  209. "Use separate calls only for the legacy path",
  210. ],
  211. "references/e2e-chat-to-land.md": [
  212. "recommended default user path",
  213. "Trusted Grok full-run delegation is the optional parked shape",
  214. "without waiting for a second human call",
  215. "Legacy / advanced",
  216. ],
  217. }
  218. FUTILE_REDRIVE_GUARD_PHRASES = {
  219. "SKILL.md": [
  220. "redrive_futile:workspace_unchanged",
  221. "manufacture futility",
  222. "do not repeat the previous approach",
  223. "redrive record-failure|evaluate|status",
  224. ],
  225. "references/e2e-chat-to-land.md": [
  226. "redrive_futile:workspace_unchanged",
  227. "manufacture futility",
  228. "do not repeat the previous approach",
  229. ],
  230. "references/glossary.md": [
  231. "redrive_futile:workspace_unchanged",
  232. "Futile re-drive",
  233. ],
  234. }
  235. LEARNINGS_LEDGER_PHRASES = {
  236. "SKILL.md": [
  237. "learnings validate|apply|rollback|digest|migrate",
  238. "learnings-history.jsonl",
  239. "never deletes",
  240. ],
  241. "references/learnings-template.md": [
  242. "learnings validate|apply|rollback|digest|migrate",
  243. "learnings-history.jsonl",
  244. "never automatic",
  245. ],
  246. "references/glossary.md": [
  247. "Learnings ledger",
  248. "learnings-history.jsonl",
  249. ],
  250. }
  251. USAGE_OBSERVED_PHRASES = {
  252. "references/survival-guide-template.md": [
  253. "Observed usage so far",
  254. "observed ≠ billed",
  255. "never a stop",
  256. ],
  257. "references/schema-and-acceptance.md": [
  258. "usage_observed",
  259. "usage_ceiling_checkpoint",
  260. "never a routing",
  261. "observed ≠ billed",
  262. ],
  263. }
  264. CURRENT_STATE_AUDIT_PHRASES = {
  265. "SKILL.md": [
  266. "the current state against every requirement",
  267. "memory of earlier work",
  268. ],
  269. "references/open-ended-guide.md": [
  270. "the current state against every requirement",
  271. "memory of earlier work",
  272. ],
  273. "references/kickoff-prompt-template.md": [
  274. "the current state against every requirement",
  275. "memory of earlier work",
  276. ],
  277. }
  278. CONTINUITY_WATCHDOG_PHRASES = {
  279. "references/operations-guide.md": [
  280. "never resumes a terminal run",
  281. "the OS owns the timer",
  282. "continuity install",
  283. ],
  284. "references/glossary.md": [
  285. "Continuity watchdog",
  286. "never resumes a terminal run",
  287. ],
  288. }
  289. SALVAGE_PREVIEW_PHRASES = {
  290. "SKILL.md": [
  291. "salvage tail --log",
  292. "never a completion report",
  293. ],
  294. "references/e2e-chat-to-land.md": [
  295. "salvage tail --log",
  296. "never a completion report",
  297. ],
  298. }
  299. SINGLE_KICKOFF_FORBIDDEN_PHRASES = {
  300. "README.md": [
  301. "Use the launch template from the same reference file in a fresh call",
  302. "**Two-step operator flow**",
  303. ],
  304. "AGENTS.md": [
  305. "do not launch in that same call",
  306. "Execution starts only from a fresh short launch prompt in the next call",
  307. ],
  308. "references/kickoff-prompt-template.md": [
  309. "**Stage and launch in separate calls**",
  310. "**If you only send one message, the agent should stage first**",
  311. "wait for your final launch command",
  312. ],
  313. }
  314. _SINGLE_KICKOFF_SURFACES = (
  315. "SKILL.md",
  316. "AGENTS.md",
  317. "README.md",
  318. "references/kickoff-prompt-template.md",
  319. "references/e2e-chat-to-land.md",
  320. "references/grok-implementer-launch-prompt.md",
  321. )
  322. SINGLE_KICKOFF_UNSCOPED_PATTERNS = {
  323. label: [
  324. r"\b(?:wait|stop)\b[^.\n]{0,160}\b(?:second|fresh|separate|another|final)\b[^.\n]{0,100}\b(?:launch|call|message|command)\b",
  325. r"\b(?:second|fresh|separate|another)\s+(?:human\s+)?(?:launch|call|message|command)\b",
  326. ]
  327. for label in _SINGLE_KICKOFF_SURFACES
  328. }
  329. EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS = {
  330. label: [r"full-run-\*"]
  331. for label in (
  332. "SKILL.md",
  333. "AGENTS.md",
  334. "README.md",
  335. "references/grok-implementer-launch-prompt.md",
  336. )
  337. }
  338. INSTALLED_HELPER_PATH_PHRASES = {
  339. "SKILL.md": [
  340. "source-checkout shorthand",
  341. "active Elves skill root",
  342. "~/.claude/skills/elves",
  343. "~/.codex/skills/elves",
  344. "~/.grok/skills/elves",
  345. "~/.omp/agent/skills/elves",
  346. "$ELVES_SKILL_ROOT/scripts/acceptance_contract.py",
  347. "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py",
  348. "installed Elves bundle never requires a repo-only helper",
  349. ],
  350. "references/runtime-helper-paths.md": [
  351. "## Source checkout shorthand",
  352. "## Installed Claude Code, Codex, Grok Build, or Oh My Pi skill",
  353. "## Shipped call-site runtime deps",
  354. "## Source-only archives",
  355. "target repository as the working directory",
  356. "$HOME/.claude/skills/elves",
  357. "$HOME/.codex/skills/elves",
  358. "$HOME/.grok/skills/elves",
  359. "$HOME/.omp/agent/skills/elves",
  360. "scripts/acceptance_contract.py",
  361. "scripts/elves_landing_check.py",
  362. "scripts/worktree_gc.py",
  363. "scripts/provider_supervisor.py",
  364. "docs/plans/",
  365. "Never make an ordinary installed Elves run",
  366. "depend on a repo-only helper",
  367. ],
  368. "references/grok-implementer-launch-prompt.md": [
  369. "runtime-helper-paths.md",
  370. "source-checkout shorthand",
  371. ],
  372. }
  373. _INSTALLED_FINAL_READINESS_SURFACES = (
  374. "SKILL.md",
  375. "AGENTS.md",
  376. "references/kickoff-prompt-template.md",
  377. "references/review-subagent.md",
  378. "references/survival-guide-template.md",
  379. )
  380. INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS = {
  381. label: [
  382. r"python3\s+(?:\./)?scripts/(?:verify_repo|release_checklist|check_repo_consistency|installed_bundle_smoke|pr_portfolio_report|sync_installed_skills)\.py\b"
  383. ]
  384. for label in _INSTALLED_FINAL_READINESS_SURFACES
  385. }
  386. REPO_CONSISTENCY_WORKFLOW_PHRASES = {
  387. ".github/workflows/repo-consistency.yml": [
  388. '"api-break-approvals.json"',
  389. '"config.json.example"',
  390. '".env*"',
  391. '"openapi.json"',
  392. '"openapi.yaml"',
  393. '"swagger.json"',
  394. '".github/ISSUE_TEMPLATE/**"',
  395. '".github/workflows/repo-consistency.yml"',
  396. '".github/workflows/pages.yml"',
  397. '"aliases/**"',
  398. '"guide/**"',
  399. '"PRODUCT.md"',
  400. '"docs/cobbler.md"',
  401. '"docs/openapi.json"',
  402. '"scripts/**"',
  403. "fetch-depth: 0",
  404. "Unreleased",
  405. "Development commits verify Unreleased",
  406. "scripts/release_checklist.py",
  407. "read_frontmatter_version",
  408. 'BASE_REF="$(git describe --tags --abbrev=0 --exclude="v${VERIFY_VERSION}" HEAD^)"',
  409. 'python3 scripts/verify_repo.py --ci --version "$VERIFY_VERSION"',
  410. "--base-ref",
  411. "actions/checkout@v6",
  412. "actions/setup-python@v6",
  413. ],
  414. }
  415. ACCEPTANCE_EVIDENCE_PHRASES = {
  416. "SKILL.md": [
  417. "plan Acceptance with proof",
  418. "acceptance",
  419. "elves_landing_check.py",
  420. "God-file",
  421. "one batch per close commit",
  422. ],
  423. "references/survival-guide-template.md": [
  424. "plan Acceptance with proof",
  425. "Evidence / SCRATCH Layout",
  426. "elves_landing_check.py",
  427. ],
  428. "references/execution-log-template.md": [
  429. "**Validate:**",
  430. "Plan Acceptance proof",
  431. ],
  432. "references/plan-template.md": [
  433. "characterization-only",
  434. "acceptance: [{criterion, met, evidence}]",
  435. ],
  436. }
  437. LANDING_CHECK_CONTRACT_PHRASES = {
  438. label: [
  439. "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py",
  440. "--session <session-path> --repo-root .",
  441. "plan_path",
  442. "equality assertion",
  443. ]
  444. for label in (
  445. "SKILL.md",
  446. "AGENTS.md",
  447. "references/survival-guide-template.md",
  448. )
  449. }
  450. LANDING_CHECK_BARE_FORBIDDEN_PATTERNS = {
  451. label: [r"python3\s+(?:\./)?scripts/elves_landing_check\.py\b"]
  452. for label in LANDING_CHECK_CONTRACT_PHRASES
  453. }
  454. CODEX_GOALS_SECTION_HEADINGS = {}
  455. CODEX_GOALS_SECTION_PHRASES = {
  456. }
  457. CODEX_GOALS_SECTION_FORBIDDEN_PHRASES = {
  458. "README.md": [
  459. "docs/elves/survival-guide.md",
  460. "docs/plans/my-plan.md",
  461. "docs/elves/execution-log.md",
  462. ],
  463. }
  464. REPO_CONSISTENCY_WORKFLOW_FORBIDDEN_PHRASES = {
  465. ".github/workflows/repo-consistency.yml": [
  466. "actions/checkout@v4",
  467. "actions/setup-python@v5",
  468. ],
  469. }
  470. REVIEWED_PR_LANDING_PHRASES = {
  471. "README.md": [
  472. "\\land-pr",
  473. "/land-pr",
  474. ],
  475. "SKILL.md": [
  476. "## Reviewed PR Landing Command",
  477. "\\land-pr",
  478. "/land-pr",
  479. "gh pr merge --merge",
  480. "default when bots are expected",
  481. "Fugu review of the current PR diff, when needed and authorized",
  482. "$elves fugu review",
  483. "Never invent a raw Fugu call",
  484. "A landing request alone does not authorize a paid Fugu call",
  485. "bump the version when the repository versions",
  486. "**Can it merge?**",
  487. "**Was it tested?**",
  488. "Local tests passed on <head SHA>",
  489. "never count as tested",
  490. "same-day back-merge PR",
  491. ],
  492. "references/review-subagent.md": [
  493. "### Reviewed PR Landing Command",
  494. "\\land-pr",
  495. "/land-pr",
  496. "gh pr merge --merge",
  497. "one-off merge opt-in",
  498. "Fugu review of the current PR diff, when needed and authorized",
  499. "$elves fugu review",
  500. "Hosts must not invent a raw Fugu call",
  501. "A landing request alone does not authorize Fugu",
  502. "bump the version when the repository versions",
  503. "Local tests passed on <head SHA>",
  504. "commits/${HEAD_SHA}/check-runs",
  505. ],
  506. "references/e2e-chat-to-land.md": [
  507. "\\land-pr",
  508. "/land-pr",
  509. "gh pr merge --merge",
  510. "Fugu review of the current PR diff, when needed and authorized",
  511. "$elves fugu review",
  512. "Hosts must not invent a raw Fugu call",
  513. "A landing request alone does not authorize Fugu",
  514. "bump the version when the repository versions",
  515. ],
  516. "references/survival-guide-template.md": [
  517. "reviewed-pr-landing-command",
  518. "\\land-pr",
  519. "/land-pr",
  520. "one-off explicit merge opt-in",
  521. ],
  522. "references/kickoff-prompt-template.md": [
  523. "reviewed-PR landing command",
  524. "\\land-pr",
  525. "/land-pr",
  526. "gh pr merge --merge",
  527. "Fugu review of the current PR diff only when needed and authorized",
  528. "$elves fugu review",
  529. "never invent a raw Fugu call",
  530. "bump the version when the repository versions",
  531. ],
  532. "references/plan-template.md": [
  533. "reviewed-PR landing command",
  534. "\\land-pr",
  535. "/land-pr",
  536. ],
  537. }
  538. REVIEWED_PR_LANDING_FORBIDDEN_PHRASES = {
  539. "SKILL.md": [
  540. "Only if the user has set a merge-on-green preference in Run Control do you merge yourself",
  541. "A merge is requested and the user has not set a merge-on-green preference.",
  542. ],
  543. "AGENTS.md": [
  544. "Only if the user has set a merge-on-green preference in Run Control do you merge yourself",
  545. "A merge is requested and the user has not set a merge-on-green preference.",
  546. "that gate stays with the user unless they set a merge-on-green preference.",
  547. ],
  548. "references/kickoff-prompt-template.md": [
  549. "merge policy (default: you never merge; opt-in: merge-commit-on-green)",
  550. "only if the user explicitly set a merge-on-green preference",
  551. ],
  552. "references/review-subagent.md": [
  553. 'gh api "repos/OWNER/REPO/commits/HEAD/check-runs"',
  554. ],
  555. }
  556. MEMORY_HYGIENE_PHRASES = {
  557. "SKILL.md": [
  558. "## Strategic Forgetting",
  559. "chats are for execution",
  560. "memory and resource hygiene",
  561. ],
  562. "references/survival-guide-template.md": [
  563. "## Strategic Forgetting",
  564. "## Memory and Resource Hygiene",
  565. ],
  566. "references/autonomy-guide.md": [
  567. "## Memory Pressure And Strategic Forgetting",
  568. "Local app maintenance",
  569. ],
  570. }
  571. ELVES_REPORT_PHRASES = {
  572. "SKILL.md": [
  573. "## Elves Report",
  574. "problems found",
  575. "lessons learned",
  576. "/tmp/elves-report-<repo-slug>-<yyyy-mm-dd>.html",
  577. "references/elves-report-template.html",
  578. "collapsible `<details>` sections",
  579. "committed examples and reusable templates non-identifying",
  580. "Elves Report path",
  581. ],
  582. "references/survival-guide-template.md": [
  583. "## Elves Report",
  584. "problems found",
  585. "lessons learned",
  586. "/tmp/elves-report-<repo-slug>-<yyyy-mm-dd>.html",
  587. "references/elves-report-template.html",
  588. ],
  589. "references/execution-log-template.md": [
  590. "**Elves Report:**",
  591. "**Problems found:**",
  592. "**Lessons learned:**",
  593. ],
  594. "references/elves-report-template.html": [
  595. "Elves Report",
  596. "Problems Found",
  597. "Lessons Learned",
  598. "Batch Ledger",
  599. "<details class=\"batch\"",
  600. ],
  601. "docs/elves-report-proof-of-concept.html": [
  602. "Elves Report",
  603. "assets/elves-banner.jpeg",
  604. "Problems found",
  605. "Lessons learned",
  606. "Batch Ledger",
  607. "<details class=\"batch\"",
  608. ],
  609. }
  610. WORKSPACE_ISOLATION_PHRASES = {
  611. "SKILL.md": [
  612. "One run owns one branch and one checkout",
  613. "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
  614. "--dry-run",
  615. "branch, worktree path, base ref, and collision tripwire",
  616. "does not reuse, delete, or repair existing worktrees",
  617. "collision tripwire",
  618. ],
  619. "README.md": [
  620. "One run owns one branch and one checkout",
  621. "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
  622. "--dry-run",
  623. "branch, worktree path, base ref, and collision tripwire",
  624. "does not reuse, delete, or repair existing worktrees",
  625. "collision tripwire",
  626. ],
  627. "references/survival-guide-template.md": [
  628. "One run owns one branch and one checkout",
  629. "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
  630. "--dry-run",
  631. "branch, worktree path, base ref, and collision tripwire",
  632. "does not reuse, delete, or repair existing worktrees",
  633. "collision tripwire",
  634. ],
  635. "references/kickoff-prompt-template.md": [
  636. "git worktree",
  637. "./scripts/preflight.sh --create-worktree <branch> --base origin/main",
  638. "--dry-run",
  639. "branch, worktree path, base ref, and collision tripwire",
  640. "does not reuse, delete, or repair existing worktrees",
  641. ],
  642. "scripts/preflight.sh": [
  643. "Workspace Ownership",
  644. "preflight_worktree.py",
  645. "--create-worktree",
  646. "git worktree list --porcelain",
  647. "Current branch is checked out in one worktree",
  648. "(current checkout)",
  649. "Recommended dedicated worktree",
  650. "Use one owned branch and checkout per Elves run before launching",
  651. ],
  652. "scripts/preflight_worktree.py": [
  653. "DEFAULT_BASE_REF = \"origin/main\"",
  654. "--create-worktree",
  655. "--worktree-dir",
  656. "--base",
  657. "--dry-run",
  658. "git worktree add",
  659. "Default base origin/main does not resolve; pass --base <ref>.",
  660. "Requested --worktree-dir already exists",
  661. "Created dedicated worktree",
  662. "Recommended dedicated worktree",
  663. "collision tripwire:",
  664. ],
  665. }
  666. OPERATOR_DOC_PHRASES = {
  667. ".ai-docs/manifest.md": [
  668. "curated layer above the run-specific `docs/elves/*` memory surfaces",
  669. "`<plan_path>` from `.elves-session.json`",
  670. "`<survival_guide_path>` from `.elves-session.json`",
  671. "`<execution_log_path>` from `.elves-session.json`",
  672. "`<learnings_path>` from `.elves-session.json`",
  673. "Promotion flow: `execution log -> learnings -> .ai-docs`",
  674. ],
  675. ".ai-docs/architecture.md": [
  676. "## Memory layers",
  677. "live run control, checkpoint semantics, active compute, next exact batch",
  678. "Live operator state belongs in the survival guide and should be rewritten in place.",
  679. "changes almost always cross multiple surfaces",
  680. ],
  681. ".ai-docs/conventions.md": [
  682. "Run control is live metadata",
  683. "survival guide's `Run Control` block",
  684. "survival guide's `Stop Gate`",
  685. "Active Compute",
  686. "Every completed batch must end with `update docs -> commit -> push -> re-read survival guide`",
  687. "Repo-only maintenance helpers stay in the checkout.",
  688. "pin it with a `*_PHRASES` map",
  689. ],
  690. ".ai-docs/gotchas.md": [
  691. "Stop Gate",
  692. "continuation_guard",
  693. "same working tree on the same branch",
  694. "dedicated `git worktree` per run",
  695. "Paid pods, remote jobs, and long-lived local services",
  696. "Local project installs can quietly shadow global installs.",
  697. ],
  698. ".github/ISSUE_TEMPLATE/overnight_run_report.md": [
  699. "- **Run mode:**",
  700. "- **Checkpoint semantics:**",
  701. "- **Active compute:**",
  702. "Run-control behavior",
  703. "What you changed in your setup afterward",
  704. ],
  705. "references/kickoff-prompt-template.md": [
  706. "Set `## Run Control` explicitly",
  707. "checkpoint semantics",
  708. "may-continue-after-checkpoint",
  709. "actual stop conditions",
  710. "`Active Compute` if relevant",
  711. "collision tripwire",
  712. ],
  713. }
  714. MATH_MODULE_PHRASES = {
  715. "SKILL.md": [
  716. "## Math Research Workflows",
  717. "Cobbler-managed Elves domain workflow",
  718. "Discovery Sprint",
  719. "Native host subagents or direct analysis are the default",
  720. "useful optional math role preset",
  721. "Google Cloud AlphaEvolve",
  722. "math-alphaevolve.md",
  723. "Never treat model output",
  724. ],
  725. "references/survival-guide-template.md": [
  726. "### Math Configuration (optional)",
  727. "math-coordination: cobbler-managed-domain-workflow",
  728. "math-provider-policy: native-first-with-optional-external-routes",
  729. "math-required-env: []",
  730. "subfield_scout: native-subagent",
  731. "math-external-route-examples",
  732. "record the",
  733. "fallback in the model-call ledger",
  734. ],
  735. "references/tool-config-examples.md": [
  736. "## Math Research Workflow",
  737. "math-coordination: cobbler-managed-domain-workflow",
  738. "math-provider-policy: native-first-with-optional-external-routes",
  739. "math-required-env: []",
  740. "OPENROUTER_API_KEY",
  741. "math-ledger-dir: docs/math",
  742. ],
  743. "references/math-workflow.md": [
  744. "Cobbler-managed Elves domain workflow",
  745. "Cobbler Harness Mapping",
  746. "## The Discovery Sprint",
  747. "## Cross-Pollination",
  748. "## Claim Lifecycle",
  749. "math-artifact-ledgers.md",
  750. "math-alphaevolve.md",
  751. "Evolutionary example search",
  752. ],
  753. "references/math-plan-template.md": [
  754. "## Batch 1: Discovery Sprint",
  755. "algebraic/combinatorial analogs",
  756. "Every `quick_win` item has a plausible proof path",
  757. "evolutionary_search: alphaevolve",
  758. ],
  759. "references/math-provider-config.md": [
  760. "Cobbler-managed domain-workflow setting",
  761. "No provider key is required by this template",
  762. "## Role Slots",
  763. "native-first-with-optional-external-routes",
  764. "OPENROUTER_API_KEY",
  765. "record-before-switching-provider",
  766. "evolutionary_search",
  767. "math-alphaevolve.md",
  768. ],
  769. "references/math-alphaevolve.md": [
  770. "Google Cloud **AlphaEvolve**",
  771. "not a proof engine",
  772. "evolutionary_search",
  773. "independent-local-replay-only",
  774. "gcloud-impersonation",
  775. "deterministic local evaluator",
  776. ],
  777. "references/math-review-prompts.md": [
  778. "## Subfield Scout",
  779. "## Proof Critic",
  780. "## Source Auditor",
  781. "## Formalization Scout",
  782. "## Evolutionary Search (AlphaEvolve / similar)",
  783. ],
  784. "references/math-artifact-ledgers.md": [
  785. "domain evidence ledgers",
  786. "## Claim Ledger",
  787. "## Source Ledger",
  788. "## Model-Call Ledger",
  789. "## Human-Verification Ledger",
  790. "alphaevolve:<task-id>",
  791. ],
  792. "config.json.example": [
  793. '"math"',
  794. '"coordination": "cobbler-managed-domain-workflow"',
  795. '"provider_policy": "native-first-with-optional-external-routes"',
  796. '"required_env": []',
  797. '"subfield_scout"',
  798. '"evolutionary_search"',
  799. '"alphaevolve"',
  800. '"fallback_policy": "record-before-switching-provider"',
  801. ],
  802. }
  803. DOMAIN_WORKFLOW_PHRASES = {
  804. "SKILL.md": [
  805. "## Coordination Architecture",
  806. "**Elves** is the execution system",
  807. "**Cobbler** is the default coordinator",
  808. "**Domain workflows** are specialized Cobbler-managed packs",
  809. "**Math** is the first domain workflow",
  810. "**Providers** are optional role routes",
  811. "cobbler.default_for_session",
  812. ],
  813. "docs/cobbler.md": [
  814. "## The coordination hierarchy",
  815. "**Elves** handles execution",
  816. "**Cobbler** handles coordination",
  817. "**Domain workflows** handle specialized work under Cobbler",
  818. "Math is the first domain workflow",
  819. "cobbler.default_for_session",
  820. ],
  821. "references/council-workflow.md": [
  822. "Elves executes, Cobbler coordinates, domain workflows specialize, and providers",
  823. "route optional roles",
  824. "Math is the first Cobbler-managed domain workflow",
  825. "domain evidence artifacts",
  826. ],
  827. "references/kickoff-prompt-template.md": [
  828. "Cobbler Session State",
  829. "cobbler.default_for_session: true",
  830. "math as a Cobbler-managed domain workflow",
  831. ],
  832. "references/survival-guide-template.md": [
  833. "## Cobbler Session State",
  834. "Cobbler default",
  835. "cobbler.default_for_session: true",
  836. "Math is a Cobbler-managed domain workflow",
  837. ],
  838. "references/review-subagent.md": [
  839. "Cobbler Session State",
  840. "cobbler.default_for_session",
  841. "Math Domain Workflow Context",
  842. "math ledgers are treated as domain evidence artifacts",
  843. ],
  844. "references/execution-log-template.md": [
  845. "Math ledger status",
  846. ],
  847. "references/math-workflow.md": [
  848. "Cobbler-managed Elves domain workflow",
  849. "Cobbler is the coordinator",
  850. "Present/record",
  851. "Reclassify",
  852. ],
  853. "references/math-provider-config.md": [
  854. "Math provider routing is a Cobbler-managed domain-workflow setting",
  855. "No provider key is required by this template",
  856. "Missing optional provider access never blocks ordinary Cobbler use or a",
  857. "math Discovery Sprint",
  858. ],
  859. "references/math-plan-template.md": [
  860. "Math is a Cobbler-managed Elves",
  861. "math-coordination: cobbler-managed-domain-workflow",
  862. "math-required-env: []",
  863. ],
  864. "references/math-review-prompts.md": [
  865. "Cobbler role templates for the math domain workflow",
  866. "Every math role should receive the same context packet",
  867. "Configured",
  868. "external providers are optional role routes",
  869. ],
  870. "references/math-artifact-ledgers.md": [
  871. "domain evidence ledgers",
  872. "not a separate Cobbler, Council, or run-state ledger",
  873. "native-subagent",
  874. ],
  875. "references/tool-config-examples.md": [
  876. "Math is a Cobbler-managed domain workflow",
  877. "math-coordination: cobbler-managed-domain-workflow",
  878. "math-required-env: []",
  879. ],
  880. "references/council-provider-config.md": [
  881. "Math has its own Cobbler-managed domain workflow provider slots",
  882. "host-native or direct analysis is the fallback",
  883. "provider becomes required only when the project survival guide says",
  884. "so explicitly",
  885. ],
  886. "config.json.example": [
  887. '"coordination": "cobbler-managed-domain-workflow"',
  888. '"provider_policy": "native-first-with-optional-external-routes"',
  889. '"required_env": []',
  890. '"external_route_examples"',
  891. ],
  892. ".ai-docs/architecture.md": [
  893. "## Coordination hierarchy",
  894. "Elves executes",
  895. "Cobbler coordinates",
  896. "Domain workflows specialize",
  897. "Math is the first domain workflow",
  898. ],
  899. ".ai-docs/conventions.md": [
  900. "Cobbler is the default coordinator after an Elves invocation",
  901. "cobbler.default_for_session",
  902. "Math is a Cobbler-managed domain workflow",
  903. ],
  904. ".ai-docs/gotchas.md": [
  905. "Normal Cobbler and ordinary Elves must not require OpenRouter",
  906. "math-required-env: []",
  907. ],
  908. }
  909. DOMAIN_WORKFLOW_FORBIDDEN_PHRASES = {
  910. label: [
  911. "Elves can also run configurable mathematical research workflows",
  912. "OpenRouter is the baseline provider",
  913. "OpenRouter is the baseline model provider",
  914. "OpenRouter is the minimum useful setup",
  915. "Use OpenRouter first when no richer local setup exists",
  916. "math-provider-policy: openrouter-first",
  917. '"provider_policy": "openrouter-first"',
  918. "math-required-env:\n - OPENROUTER_API_KEY",
  919. '"required_env": ["OPENROUTER_API_KEY"]',
  920. ]
  921. for label in (
  922. "SKILL.md",
  923. "AGENTS.md",
  924. "README.md",
  925. "references/survival-guide-template.md",
  926. "references/tool-config-examples.md",
  927. "references/math-workflow.md",
  928. "references/math-provider-config.md",
  929. "references/math-plan-template.md",
  930. "references/math-review-prompts.md",
  931. "references/math-artifact-ledgers.md",
  932. "references/council-workflow.md",
  933. "references/council-provider-config.md",
  934. "config.json.example",
  935. )
  936. }
  937. DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS = {
  938. label: [
  939. r"\bmath\b[^.\n]*(?:peer|separate)\s+(?:coordinator|orchestrator|orchestration\s+layer)\b",
  940. r"\bmath\b[^.\n]*(?:requires|needs)\s+openrouter\b",
  941. r"\bopenrouter\b\s+is\s+required\s+for\s+math\b",
  942. r"\bopenrouter_api_key\b\s+(?:is\s+)?(?:required|must\s+be\s+set)\b",
  943. r"\bmath-required-env:\s*\n\s*-\s*OPENROUTER_API_KEY\b",
  944. ]
  945. for label in DOMAIN_WORKFLOW_FORBIDDEN_PHRASES
  946. }
  947. PUBLIC_API_SURFACE_SNAPSHOT_PHRASES = {
  948. ".gitignore": [
  949. ".elves/",
  950. ],
  951. "SKILL.md": [
  952. "Public API surface snapshots are optional regression evidence.",
  953. "Use existing structured sources before inventing scanners",
  954. "If no credible source exists, record `unavailable` with the reason instead of fabricating",
  955. "A missing snapshot source is not blocking unless `required: true` was explicitly set in the survival guide.",
  956. "`required: true` is valid only when explicitly set by the user or project survival guide.",
  957. "Do not infer required mode from project type, provider config, framework choice, or the presence of API files.",
  958. "Snapshot artifacts are run artifacts, not product docs",
  959. "Temporary snapshot artifacts should not remain in final product PR diffs unless the user explicitly",
  960. "Record shapes and field names, not secrets, bearer tokens, cookies, customer payloads, or production sample data.",
  961. "A snapshot proves public surface shape only; it is not a substitute for tests, E2E checks, review, or the human-owned constitution.",
  962. "public API surface delta when configured",
  963. ],
  964. "references/survival-guide-template.md": [
  965. "api-surface-snapshot:",
  966. "enabled: auto",
  967. "required: false",
  968. "Public API surface snapshots are optional regression evidence",
  969. "A missing snapshot source is not blocking unless required: true was explicitly set",
  970. "Snapshot artifacts are run artifacts, not product docs",
  971. ],
  972. "references/execution-log-template.md": [
  973. "Public API surface snapshot:",
  974. "N/A / unavailable reason / no delta / additive / planned breaking / unexpected breaking",
  975. ],
  976. "references/review-subagent.md": [
  977. "API surface snapshot artifacts when configured",
  978. "Public API surface snapshots",
  979. "optional regression evidence",
  980. "A missing snapshot source is not blocking unless `required: true` was explicitly set",
  981. "A snapshot proves public surface shape only; it is not a substitute",
  982. ],
  983. "references/kickoff-prompt-template.md": [
  984. "Configure optional public API surface snapshot behavior",
  985. "api-surface-snapshot.enabled: auto",
  986. "required: false",
  987. ".elves/api-surface/",
  988. ],
  989. "references/tool-config-examples.md": [
  990. "## Public API Surface Snapshot",
  991. "enabled: auto",
  992. "required: false",
  993. "Use existing structured sources before inventing scanners",
  994. "If no credible source exists, record `unavailable` with the reason instead of fabricating a snapshot",
  995. "A snapshot proves public surface shape only; it is not a substitute",
  996. ],
  997. "config.json.example": [
  998. '"api_surface_snapshot"',
  999. '"enabled": "auto"',
  1000. '"required": false',
  1001. '".elves/api-surface/baseline.json"',
  1002. '"unexpected_breaking_change": "blocking"',
  1003. "snapshots are regression evidence, not authority",
  1004. ],
  1005. "TODO.md": [
  1006. "public API surfaces",
  1007. "implemented `cobbler_runtime.public_api_snapshot` compatibility gate",
  1008. ],
  1009. }
  1010. PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS = {
  1011. label: [
  1012. r"\bapi\s+snapshots?\s+(?:are|is)\s+required\b",
  1013. r"\bmust\s+generate\s+an?\s+api\s+snapshot\b",
  1014. r"\brequired:\s*true\s+by\s+default\b",
  1015. r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\binfer\s+required\s+mode\b",
  1016. r"\bsnapshots?\s+replace\s+(?:tests|the constitution|review)\b",
  1017. r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\bcommit\s+snapshot\s+artifacts\b",
  1018. r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\brecord\s+(?:raw\s+)?(?:secrets|bearer tokens|cookies|customer payloads|production sample data)\b",
  1019. r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\bcapture\s+(?:raw\s+)?(?:secrets|bearer tokens|cookies|customer payloads|production sample data)\b",
  1020. r"(?<!do not )(?<!never )(?<!don't )(?<!should not )(?<!must not )\binclude\s+(?:raw\s+)?(?:secrets|bearer tokens|cookies|customer payloads|production sample data)\b",
  1021. ]
  1022. for label in (
  1023. "SKILL.md",
  1024. "AGENTS.md",
  1025. "README.md",
  1026. "references/survival-guide-template.md",
  1027. "references/execution-log-template.md",
  1028. "references/review-subagent.md",
  1029. "references/kickoff-prompt-template.md",
  1030. "references/tool-config-examples.md",
  1031. "config.json.example",
  1032. )
  1033. }
  1034. COUNCIL_MODULE_PHRASES = {
  1035. "README.md": [
  1036. "/cobbler",
  1037. "/setup-cobbler",
  1038. "$elves cobbler: <task>",
  1039. "Ask the Cobbler",
  1040. "Codex users should not need or expect a top-level `/cobbler` command",
  1041. "Council is a deprecated alias of Cobbler",
  1042. ],
  1043. "SKILL.md": [
  1044. "## Cobbler",
  1045. "Cobbler",
  1046. "/cobbler",
  1047. "$elves cobbler: <task>",
  1048. "/council",
  1049. "/ec",
  1050. "/elves-council",
  1051. "$elves council: <task>",
  1052. "Host honesty matters",
  1053. "do not assume Codex has a top-level `/cobbler` command",
  1054. "Codex Goals are optional continuation plumbing",
  1055. "not required for a Quick Cobbler answer",
  1056. "default orchestration model",
  1057. "Cobbler-first coordination is the default for Elves runs",
  1058. "worker agents may edit the repo",
  1059. "Quick Cobbler is the default one-off answer mode",
  1060. "read-only",
  1061. "stateless",
  1062. "Codex subagents",
  1063. "Claude Code subagents",
  1064. "read-only lens analysis directly",
  1065. "Optional model routing is role-scoped",
  1066. "provider model such as `openrouter:<model-id>`",
  1067. "resolve dissent by",
  1068. "Recommendation",
  1069. "Why this fits",
  1070. "Strongest dissent",
  1071. "Risks",
  1072. "Next move",
  1073. "Confidence",
  1074. "run state",
  1075. "Provider-backed council is optional",
  1076. "must not require",
  1077. "vendor identity",
  1078. ],
  1079. "references/council-workflow.md": [
  1080. "# Cobbler Workflow",
  1081. "Cobbler is the default coordination layer",
  1082. "Council is the compatibility path",
  1083. "Claude Code primary: `/cobbler <task>`",
  1084. "Codex primary: `$elves cobbler: <task>`",
  1085. "Codex compatibility: `$elves council: <task>`",
  1086. "Do not document Codex as having a top-level `/cobbler`",
  1087. "Run Cobbler is the default coordination pattern inside an Elves run",
  1088. "Worker agents may edit",
  1089. "Quick Cobbler is the default one-off answer mode",
  1090. "Quick Cobbler is the default one-off answer mode. It is always read-only and stateless",
  1091. "Role agents do not see each other's reports before synthesis",
  1092. "Run Cobbler reuses existing Elves memory surfaces",
  1093. "Provider-backed council is not a third Cobbler mode",
  1094. "use must not require OpenRouter",
  1095. "Optional model routing is role-scoped",
  1096. "fall back to native subagents",
  1097. "model prestige",
  1098. "Do not make Quick Cobbler require OpenRouter",
  1099. "Recommendation",
  1100. "Why this fits",
  1101. "Strongest dissent",
  1102. "Risks",
  1103. "Next move",
  1104. "Confidence",
  1105. "Do not create a separate PR, branch, survival guide, execution log, or ledger",
  1106. ],
  1107. "references/council-prompts.md": [
  1108. "# Cobbler Prompt Templates",
  1109. "Cobbler roles are lenses with obligations, not theatrical personas",
  1110. "Do not read or rely on other role reports",
  1111. "Work scope",
  1112. "worker edit with assigned files",
  1113. "Run Cobbler is the default coordination",
  1114. "Return one fitted answer",
  1115. "Recommendation",
  1116. "Why this fits",
  1117. "Strongest dissent",
  1118. "Next move",
  1119. "why_this_fits",
  1120. "strongest_dissent",
  1121. "next_move",
  1122. ],
  1123. "references/council-provider-config.md": [
  1124. "# Cobbler Provider-Backed Council Configuration",
  1125. "Cobbler-first coordination is the default for Elves runs",
  1126. "Normal Cobbler",
  1127. "$elves cobbler: <task>",
  1128. "use must work without",
  1129. "Cobbler-first Elves runs and Quick Cobbler one-off answers need no provider configuration",
  1130. "cobbler-coordination-default: cobbler-first",
  1131. "cobbler-model-routing-policy: native-first",
  1132. "provider:model-id",
  1133. "fall back to native",
  1134. "cobbler-provider-backed-required-env: []",
  1135. "Do not make ordinary Cobbler or Council-compatible use",
  1136. "Do not create a separate Council ledger",
  1137. ],
  1138. "references/codex-goals.md": [
  1139. "Goals keeps Codex moving; Cobbler coordinates the Elves loop",
  1140. "Codex Goals are not required for Quick Cobbler",
  1141. "$elves cobbler: <task>",
  1142. "Ask the Cobbler",
  1143. "$elves council: <task>",
  1144. "You only need a Quick Cobbler answer",
  1145. "`survival_guide_path`",
  1146. "`learnings_path`",
  1147. "`plan_path`",
  1148. "`execution_log_path`",
  1149. "do not substitute generic filenames",
  1150. ],
  1151. "references/tool-config-examples.md": [
  1152. "## Cobbler",
  1153. "Default Cobbler coordination block for Elves runs",
  1154. "Cobbler-first is the default orchestration",
  1155. "Quick Cobbler requires no external provider",
  1156. "cobbler-coordination-default: cobbler-first",
  1157. "cobbler-default-backend: native-subagents",
  1158. "cobbler-model-routing-policy: native-first",
  1159. "cobbler-provider-backed-fallback: native-subagent-and-note",
  1160. "openrouter:<model-id>",
  1161. "low, medium, high, or xhigh",
  1162. "cobbler-run-logging: existing-elves-memory",
  1163. "cobbler-provider-backed-required-env: []",
  1164. "Legacy `council-*` config keys remain compatibility aliases",
  1165. ],
  1166. "references/survival-guide-template.md": [
  1167. "Coordination mode",
  1168. "### Cobbler Coordination Defaults",
  1169. "Cobbler-first coordination is the default for Elves runs",
  1170. "Provider-backed council is optional",
  1171. "cobbler-coordination-default: cobbler-first",
  1172. "cobbler-default-backend: native-subagents",
  1173. "cobbler-model-routing-policy: native-first",
  1174. "cobbler-provider-backed-fallback: native-subagent-and-note",
  1175. "openrouter:<model-id>",
  1176. "low, medium, high, or xhigh",
  1177. "cobbler-run-logging: existing-elves-memory",
  1178. "cobbler-provider-backed-required-env: []",
  1179. "Legacy `council-*` config keys remain compatibility aliases",
  1180. ],
  1181. "config.json.example": [
  1182. '"cobbler"',
  1183. '"council"',
  1184. '"coordination_default": "cobbler-first"',
  1185. '"default_for_elves_runs": true',
  1186. '"primary_invocations"',
  1187. '"default_answer_shape"',
  1188. '"provider_backed_council"',
  1189. '"compatibility_for": "cobbler"',
  1190. '"precedence": "cobbler"',
  1191. '"default_backend": "native-subagents"',
  1192. '"quick_read_only": true',
  1193. '"quick_stateless": true',
  1194. '"run_logging": "existing-elves-memory"',
  1195. '"model_routing_policy": "native-first"',
  1196. '"fallback": "native-subagent-and-note"',
  1197. '"external_route_example": "openrouter:<model-id>"',
  1198. '"required_env": []',
  1199. '"provider_policy": "optional-external-providers"',
  1200. ],
  1201. }
  1202. COUNCIL_SECTION_HEADINGS = {
  1203. "SKILL.md": "## Cobbler",
  1204. "AGENTS.md": "## Cobbler",
  1205. }
  1206. CLAUDE_ALIAS_MARKER = "<!-- elves-managed-alias: claude-skill-alias v1 -->"
  1207. CLAUDE_ALIAS_SKILL_PHRASES = {
  1208. "aliases/claude/cobbler/SKILL.md": [
  1209. CLAUDE_ALIAS_MARKER,
  1210. "name: cobbler",
  1211. "/cobbler",
  1212. "default orchestration model",
  1213. "Use the installed `elves` skill",
  1214. "For one-off Quick Cobbler answers, stay read-only and stateless",
  1215. "worker agents may edit scoped files",
  1216. "Claude Code subagents",
  1217. "Recommendation",
  1218. "Why this fits",
  1219. "Strongest dissent",
  1220. "Next move",
  1221. "must not require OpenRouter",
  1222. ],
  1223. "aliases/claude/cobbler-mode/SKILL.md": [
  1224. CLAUDE_ALIAS_MARKER,
  1225. "name: cobbler-mode",
  1226. "/cobbler-mode",
  1227. "Cobbler Mode",
  1228. "default orchestration model",
  1229. "current-thread",
  1230. "Cobbler Mode: on",
  1231. "Cobbler Mode: off",
  1232. "not durable run state",
  1233. "For one-off Quick Cobbler answers, stay read-only and stateless",
  1234. "worker agents may edit scoped files",
  1235. "Claude Code subagents",
  1236. "Recommendation",
  1237. "Why this fits",
  1238. "Strongest dissent",
  1239. "Next move",
  1240. "must not require OpenRouter",
  1241. ],
  1242. "aliases/claude/setup-cobbler/SKILL.md": [
  1243. CLAUDE_ALIAS_MARKER,
  1244. "name: setup-cobbler",
  1245. "/setup-cobbler",
  1246. "onboard plan|show|apply|probe",
  1247. "Never stage",
  1248. ".elves/models.toml",
  1249. "must not require OpenRouter",
  1250. ],
  1251. "aliases/claude/setup-council/SKILL.md": [
  1252. CLAUDE_ALIAS_MARKER,
  1253. "name: setup-council",
  1254. "/setup-council",
  1255. "onboard plan|show|apply|probe",
  1256. "compatibility",
  1257. "must not require OpenRouter",
  1258. "Never stage",
  1259. ],
  1260. "aliases/claude/council/SKILL.md": [
  1261. CLAUDE_ALIAS_MARKER,
  1262. "name: council",
  1263. "/council",
  1264. "compatibility alias",
  1265. "default orchestration model",
  1266. "installed `elves`",
  1267. "For one-off Quick Cobbler answers, stay read-only and stateless",
  1268. "worker agents may edit scoped files",
  1269. "Claude Code subagents",
  1270. "Recommendation",
  1271. "Why this fits",
  1272. "Strongest dissent",
  1273. "Next move",
  1274. "must not require OpenRouter",
  1275. ],
  1276. "aliases/claude/ec/SKILL.md": [
  1277. CLAUDE_ALIAS_MARKER,
  1278. "name: ec",
  1279. "/ec",
  1280. "compatibility alias",
  1281. "default orchestration model",
  1282. "installed `elves`",
  1283. "For one-off Quick Cobbler answers, stay read-only and stateless",
  1284. "worker agents may edit scoped files",
  1285. "Claude Code subagents",
  1286. "Recommendation",
  1287. "Why this fits",
  1288. "Strongest dissent",
  1289. "Next move",
  1290. "must not require OpenRouter",
  1291. ],
  1292. "aliases/claude/elves-council/SKILL.md": [
  1293. CLAUDE_ALIAS_MARKER,
  1294. "name: elves-council",
  1295. "/elves-council",
  1296. "compatibility alias",
  1297. "default orchestration model",
  1298. "installed `elves`",
  1299. "For one-off Quick Cobbler answers, stay read-only and stateless",
  1300. "worker agents may edit scoped files",
  1301. "Claude Code subagents",
  1302. "Recommendation",
  1303. "Why this fits",
  1304. "Strongest dissent",
  1305. "Next move",
  1306. "must not require OpenRouter",
  1307. ],
  1308. "aliases/claude/fugu/SKILL.md": [
  1309. CLAUDE_ALIAS_MARKER,
  1310. "name: fugu",
  1311. "/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>",
  1312. "/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>",
  1313. "Provider shortcut protocols",
  1314. "run_fugu.sh",
  1315. "codex-fugu",
  1316. "fugu/high",
  1317. "fugu-ultra-v1.1",
  1318. "read-only",
  1319. "non-ignored",
  1320. "runner rejects `--write`",
  1321. ],
  1322. "aliases/claude/manus/SKILL.md": [
  1323. CLAUDE_ALIAS_MARKER,
  1324. "name: manus",
  1325. "/manus <topic>",
  1326. "--wide",
  1327. "--fanout",
  1328. "--resume",
  1329. "Cobbler",
  1330. "Provider shortcut protocols",
  1331. "run_manus.sh",
  1332. "MANUS_API_KEY",
  1333. "bounded wait",
  1334. ],
  1335. "aliases/claude/grok/SKILL.md": [
  1336. CLAUDE_ALIAS_MARKER,
  1337. "name: grok",
  1338. "/grok <instructions>",
  1339. "Provider shortcut protocols",
  1340. "run_grok.sh",
  1341. "non-bypass permission posture",
  1342. ],
  1343. "aliases/claude/devin/SKILL.md": [
  1344. CLAUDE_ALIAS_MARKER,
  1345. "name: devin",
  1346. "/devin <instructions>",
  1347. "Provider shortcut protocols",
  1348. "run_devin.sh",
  1349. "DEVIN_API_KEY",
  1350. "bounded wait",
  1351. ],
  1352. }
  1353. CODEX_INSTALL_COBBLER_PHRASES = {
  1354. "README.md": [
  1355. "--target codex",
  1356. "Do not invent top-level /cobbler",
  1357. "Codex installs the main skill bundle only",
  1358. "$elves cobbler: <task>",
  1359. ],
  1360. }
  1361. COBBLER_CONFIG_PREFERENCE_PHRASES = {
  1362. "README.md": [
  1363. "Put new Cobbler preferences",
  1364. "under the top-level `cobbler` block",
  1365. "is for compatibility with older",
  1366. "if both blocks are present, `cobbler` wins",
  1367. ],
  1368. "SKILL.md": [
  1369. "Cobbler preferences belong under the top-level `cobbler` block",
  1370. "if both blocks are present",
  1371. "`cobbler` wins",
  1372. ],
  1373. "config.json.example": [
  1374. '"precedence": "cobbler"',
  1375. "If both blocks are present, cobbler wins",
  1376. ],
  1377. }
  1378. COUNCIL_FORBIDDEN_PHRASES = {
  1379. "README.md": [
  1380. "ordinary `/council` requires OpenRouter",
  1381. "normal `/council` requires OpenRouter",
  1382. "ordinary Cobbler requires OpenRouter",
  1383. "normal Cobbler requires OpenRouter",
  1384. "Cobbler requires `OPENROUTER_API_KEY`",
  1385. "Council requires `OPENROUTER_API_KEY`",
  1386. "Cobbler is optional for Elves runs",
  1387. "Cobbler only runs when invoked",
  1388. "Run Cobbler is just Quick Cobbler inside a run",
  1389. "Run Cobbler is Quick Cobbler inside an existing Elves run",
  1390. "Use `/cobbler` in Codex",
  1391. "Use `/council` in Codex",
  1392. "Quick Cobbler requires Codex Goals",
  1393. "Cobbler requires `/goal`",
  1394. ],
  1395. "SKILL.md": [
  1396. "ordinary `/council` requires OpenRouter",
  1397. "normal `/council` requires OpenRouter",
  1398. "ordinary Cobbler requires OpenRouter",
  1399. "normal Cobbler requires OpenRouter",
  1400. "Cobbler requires `OPENROUTER_API_KEY`",
  1401. "Council requires `OPENROUTER_API_KEY`",
  1402. "Elves can also run Cobbler",
  1403. "Cobbler is optional for Elves runs",
  1404. "Cobbler only runs when invoked",
  1405. "Run Cobbler is just Quick Cobbler inside a run",
  1406. "Run Cobbler is Quick Cobbler inside an existing Elves run",
  1407. "Use `/cobbler` in Codex",
  1408. "Use `/council` in Codex",
  1409. "Quick Cobbler requires Codex Goals",
  1410. "Cobbler requires `/goal`",
  1411. ],
  1412. "AGENTS.md": [
  1413. "ordinary `/council` requires OpenRouter",
  1414. "normal `/council` requires OpenRouter",
  1415. "ordinary Cobbler requires OpenRouter",
  1416. "normal Cobbler requires OpenRouter",
  1417. "Cobbler requires `OPENROUTER_API_KEY`",
  1418. "Council requires `OPENROUTER_API_KEY`",
  1419. "Elves can also run Cobbler",
  1420. "Cobbler is optional for Elves runs",
  1421. "Cobbler only runs when invoked",
  1422. "Run Cobbler is just Quick Cobbler inside a run",
  1423. "Run Cobbler is Quick Cobbler inside an existing Elves run",
  1424. "Use `/cobbler` in Codex",
  1425. "Use `/council` in Codex",
  1426. "Quick Cobbler requires Codex Goals",
  1427. "Cobbler requires `/goal`",
  1428. ],
  1429. "references/codex-goals.md": [
  1430. "Quick Cobbler requires Codex Goals",
  1431. "Cobbler requires `/goal`",
  1432. "Use `/cobbler` in Codex",
  1433. "Use `/council` in Codex",
  1434. "docs/elves/survival-guide.md",
  1435. "docs/plans/my-plan.md",
  1436. "docs/elves/execution-log.md",
  1437. ],
  1438. "references/council-workflow.md": [
  1439. "ordinary `/council` requires OpenRouter",
  1440. "normal `/council` requires OpenRouter",
  1441. "Council requires `OPENROUTER_API_KEY`",
  1442. "Council can edit files",
  1443. "Council can create branches",
  1444. "Council can open PRs",
  1445. "# Elves Council Workflow",
  1446. "Quick Council is the default",
  1447. "Run Council reuses existing Elves memory surfaces",
  1448. "Deep Council is optional",
  1449. "Do not make Quick Council require OpenRouter",
  1450. "Quick Cobbler is read-only and stateless unless",
  1451. "Quick Cobbler is the default one-off answer mode. It is read-only and stateless unless",
  1452. "### Provider-Backed Council",
  1453. ],
  1454. "references/council-provider-config.md": [
  1455. "ordinary `/council` requires OpenRouter",
  1456. "normal `/council` requires OpenRouter",
  1457. "Council requires `OPENROUTER_API_KEY`",
  1458. "# Council Provider Configuration",
  1459. "Quick Council needs no provider configuration",
  1460. "Deep Council is opt-in",
  1461. "council-deep-required-env",
  1462. ],
  1463. "references/council-prompts.md": [
  1464. "# Elves Council Prompts",
  1465. "Council roles are lenses with obligations",
  1466. "You are synthesizing independent Elves Council reports",
  1467. "Mode: [Quick Cobbler / Run Cobbler / Provider-backed council]",
  1468. ],
  1469. "references/tool-config-examples.md": [
  1470. "## Elves Council",
  1471. "Quick Council requires no external provider key",
  1472. "Optional Deep Council provider diversity",
  1473. "council-deep-required-env",
  1474. ],
  1475. "references/survival-guide-template.md": [
  1476. "### Elves Council Configuration (optional)",
  1477. "External providers are optional Deep Council",
  1478. "Optional Deep Council provider diversity",
  1479. "council-deep-required-env",
  1480. ],
  1481. }
  1482. COBBLER_FORBIDDEN_PATTERNS = {
  1483. label: [
  1484. r"\bquick\s+cobbler\s+(?:needs|requires)\s+openrouter\b",
  1485. r"\bnormal\s+cobbler\s+requires\s+(?:an\s+)?external\s+provider\s+key\b",
  1486. r"\bcobbler\s+requires\s+openrouter\b",
  1487. r"\bcouncil-compatible\s+use\s+requires\s+openrouter\b",
  1488. r"\bopenrouter_api_key\b\s+is\s+required\s+for\s+cobbler\b",
  1489. r"\bcobbler\s+is\s+optional\s+for\s+elves\s+runs\b",
  1490. r"\bcobbler\s+only\s+runs\s+when\s+invoked\b",
  1491. r"\brun\s+cobbler\s+is\s+(?:just\s+)?quick\s+cobbler\s+inside\s+(?:an?\s+)?(?:active\s+)?(?:elves\s+)?run\b",
  1492. r"\bquick\s+cobbler\b[^.\n]*(?:unless|except)\b[^.\n]*(?:active\s+elves\s+run|implementation|edit|mutate)\b",
  1493. r"\bcobbler\s+mode\s+persists\s+across\s+threads\b",
  1494. r"\bcobbler\s+mode\s+starts\s+an?\s+elves\s+run\b",
  1495. r"\bcobbler\s+mode\s+requires\s+codex\s+goals\b",
  1496. r"\bcobbler\s+mode\s+can\s+edit\s+files\s+by\s+default\b",
  1497. r"\buse\s+`?/cobbler-mode`?\s+in\s+codex\b",
  1498. ]
  1499. for label in (
  1500. "SKILL.md",
  1501. "AGENTS.md",
  1502. "README.md",
  1503. "references/council-workflow.md",
  1504. "references/council-provider-config.md",
  1505. "references/tool-config-examples.md",
  1506. "references/survival-guide-template.md",
  1507. "config.json.example",
  1508. "aliases/claude/cobbler/SKILL.md",
  1509. "aliases/claude/cobbler-mode/SKILL.md",
  1510. "aliases/claude/council/SKILL.md",
  1511. "aliases/claude/ec/SKILL.md",
  1512. "aliases/claude/elves-council/SKILL.md",
  1513. )
  1514. }
  1515. COBBLER_MODE_PHRASES = {
  1516. "SKILL.md": [
  1517. "Cobbler Mode is the lowest-friction way",
  1518. "/cobbler-mode",
  1519. "$elves cobbler-mode",
  1520. "Cobbler Mode: on",
  1521. "Cobbler Mode: off",
  1522. "current-thread conversation state",
  1523. "not durable run state",
  1524. "daemon",
  1525. "Codex slash command",
  1526. ],
  1527. "references/council-workflow.md": [
  1528. "### Cobbler Mode",
  1529. "not a third Cobbler behavior mode",
  1530. "/cobbler-mode",
  1531. "$elves cobbler-mode",
  1532. "Cobbler Mode: on",
  1533. "Cobbler Mode: off",
  1534. "current-thread conversation state",
  1535. "not durable run state",
  1536. "branch, PR, survival guide, execution log, Codex Goal",
  1537. ],
  1538. "aliases/claude/cobbler-mode/SKILL.md": [
  1539. "name: cobbler-mode",
  1540. "/cobbler-mode",
  1541. "Cobbler Mode",
  1542. "default orchestration model",
  1543. "current-thread",
  1544. "Cobbler Mode: on",
  1545. "Cobbler Mode: off",
  1546. "not durable run state",
  1547. "daemon",
  1548. ],
  1549. }
  1550. COBBLER_HARNESS_LOOP_PHRASES = {
  1551. "SKILL.md": [
  1552. "capability scan",
  1553. "route and medium selection",
  1554. "context packet",
  1555. "execute agents/tools/skills",
  1556. "collect evidence",
  1557. "fit answer",
  1558. "present/record",
  1559. "reclassify",
  1560. ],
  1561. "docs/cobbler.md": [
  1562. "capability scan",
  1563. "Route and medium selection",
  1564. "Context packet",
  1565. "Execute agents/tools/skills",
  1566. "Collect evidence",
  1567. "Fit answer",
  1568. "Present/record",
  1569. "Reclassify",
  1570. "does not copy Fable's model identity",
  1571. ],
  1572. "references/council-workflow.md": [
  1573. "capability scan",
  1574. "route and medium selection",
  1575. "context packet",
  1576. "execute agents/tools/skills",
  1577. "collect evidence",
  1578. "fit answer",
  1579. "Present/record",
  1580. "Reclassify",
  1581. ],
  1582. "references/council-prompts.md": [
  1583. "Capability scan",
  1584. "Route and medium",
  1585. "Context packet",
  1586. "Evidence",
  1587. "Present/record",
  1588. "Reclassify",
  1589. ],
  1590. "references/tool-config-examples.md": [
  1591. "cobbler-harness-loop",
  1592. "capability-scan",
  1593. "route-and-medium-selection",
  1594. "context-packet",
  1595. "execute-agents-tools-skills",
  1596. "collect-evidence",
  1597. "fit-answer",
  1598. "present-record",
  1599. "reclassify",
  1600. ],
  1601. "references/survival-guide-template.md": [
  1602. "cobbler-harness-loop",
  1603. "capability-scan",
  1604. "route-and-medium-selection",
  1605. "context-packet",
  1606. "execute-agents-tools-skills",
  1607. "collect-evidence",
  1608. "fit-answer",
  1609. "present-record",
  1610. "reclassify",
  1611. ],
  1612. "config.json.example": [
  1613. '"harness_loop"',
  1614. '"capability_scan"',
  1615. '"route_and_medium_selection"',
  1616. '"context_packet"',
  1617. '"execute_agents_tools_skills"',
  1618. '"collect_evidence"',
  1619. '"fit_answer"',
  1620. '"present_record"',
  1621. '"reclassify"',
  1622. ],
  1623. "aliases/claude/cobbler/SKILL.md": [
  1624. "capability scan",
  1625. "route and medium selection",
  1626. "context packet",
  1627. "execute agents/tools/skills",
  1628. "collect evidence",
  1629. "fit answer",
  1630. "present/record",
  1631. "reclassify",
  1632. ],
  1633. "aliases/claude/cobbler-mode/SKILL.md": [
  1634. "capability scan",
  1635. "route and medium selection",
  1636. "context packet",
  1637. "execute agents/tools/skills",
  1638. "collect evidence",
  1639. "fit answer",
  1640. "present/record",
  1641. "reclassify",
  1642. ],
  1643. "aliases/claude/council/SKILL.md": [
  1644. "capability scan",
  1645. "route and medium selection",
  1646. "context packet",
  1647. "execute agents/tools/skills",
  1648. "collect evidence",
  1649. "fit answer",
  1650. "present/record",
  1651. "reclassify",
  1652. ],
  1653. "aliases/claude/ec/SKILL.md": [
  1654. "capability scan",
  1655. "route and medium selection",
  1656. "context packet",
  1657. "execute agents/tools/skills",
  1658. "collect evidence",
  1659. "fit answer",
  1660. "present/record",
  1661. "reclassify",
  1662. ],
  1663. "aliases/claude/elves-council/SKILL.md": [
  1664. "capability scan",
  1665. "route and medium selection",
  1666. "context packet",
  1667. "execute agents/tools/skills",
  1668. "collect evidence",
  1669. "fit answer",
  1670. "present/record",
  1671. "reclassify",
  1672. ],
  1673. }
  1674. COBBLER_HARNESS_DRIFT_PATTERNS = {
  1675. label: [
  1676. r"\bquick\s+cobbler\b[^.\n]*(?:edits|mutates|commits|pushes|opens\s+prs)\b",
  1677. r"\bcontext\s+packet\b[^.\n]*(?:includes|contains)\s+(?:secrets|tokens|credentials|cookies)\b",
  1678. r"\bprovider-backed\s+council\b[^.\n]*(?:required|default)\b",
  1679. r"\breclassify\b[^.\n]*(?:by\s+changing\s+run\s+state|by\s+creating\s+a\s+new\s+run)\b",
  1680. ]
  1681. for label in COBBLER_HARNESS_LOOP_PHRASES
  1682. }
  1683. FULL_RUN_MODEL_ROUTING_PHRASES = {
  1684. "SKILL.md": [
  1685. "Full-run model routing is a separate optional staging preference",
  1686. "`model-routing` phase preferences",
  1687. "native-first by default",
  1688. "requested route, actual route, and material fallback reason",
  1689. "`requested_route`, `actual_route`, and `fallback_reason`",
  1690. "Missing optional provider access",
  1691. "`required: true`",
  1692. ],
  1693. "references/survival-guide-template.md": [
  1694. "### Full-Run Model Routing (optional)",
  1695. "policy: native-first",
  1696. "fallback: host-native",
  1697. "implement-model: strongest-host-native",
  1698. "JSON keys: requested_route, actual_route, fallback_reason",
  1699. ],
  1700. "references/execution-log-template.md": [
  1701. "**Phase routing (optional):**",
  1702. "Requested route",
  1703. "Actual route",
  1704. "Fallback reason",
  1705. ],
  1706. "references/review-subagent.md": [
  1707. "## Phase Route Context",
  1708. "requested route, actual route, and fallback reason",
  1709. "required: true",
  1710. "Missing optional provider access is not a",
  1711. ],
  1712. "references/tool-config-examples.md": [
  1713. "## Full-Run Model Routing",
  1714. "model-routing:",
  1715. "native-subagent, host-default",
  1716. "openrouter:<model-id>",
  1717. "Do not treat bare aliases as provider model IDs",
  1718. ],
  1719. "references/council-workflow.md": [
  1720. "Run Cobbler is not the same thing as full-run model routing",
  1721. "requested route, actual route, and material fallback reason",
  1722. "separate council ledger",
  1723. ],
  1724. "references/council-prompts.md": [
  1725. "Full-run model routing belongs to Elves run control",
  1726. "not the Quick Cobbler role selector",
  1727. ],
  1728. "references/council-provider-config.md": [
  1729. "## Full-Run Phase Routes",
  1730. "Provider-backed council slots may satisfy read-only full-run model-routing phases",
  1731. "Do not make implementation provider-backed by default",
  1732. "route, actual route, and fallback reason",
  1733. ],
  1734. "config.json.example": [
  1735. '"model_routing"',
  1736. '"policy": "native-first"',
  1737. '"fallback": "host-native"',
  1738. '"required": false',
  1739. '"provider_backed_allowed": false',
  1740. '"log_material_fallbacks": true',
  1741. ],
  1742. }
  1743. FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES = {
  1744. label: [
  1745. "ordinary Elves requires OpenRouter",
  1746. "normal Elves requires OpenRouter",
  1747. "model-routing requires OpenRouter",
  1748. "full-run model routing requires OpenRouter",
  1749. "required: true is the default",
  1750. "route mismatch is always blocking",
  1751. "implementation routes to external providers by default",
  1752. "Quick Cobbler uses model-routing",
  1753. ]
  1754. for label in (
  1755. "SKILL.md",
  1756. "AGENTS.md",
  1757. "README.md",
  1758. "references/survival-guide-template.md",
  1759. "references/execution-log-template.md",
  1760. "references/review-subagent.md",
  1761. "references/tool-config-examples.md",
  1762. "references/council-workflow.md",
  1763. "references/council-prompts.md",
  1764. "references/council-provider-config.md",
  1765. "config.json.example",
  1766. )
  1767. }
  1768. FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS = {
  1769. label: [
  1770. r"\bfull-run\s+model\s+routing\s+requires\s+(?:an\s+)?external\s+provider\s+key\b",
  1771. r"\bmodel-routing\s+requires\s+openrouter\b",
  1772. r"\brequired:\s*true\s+is\s+(?:the\s+)?default\b",
  1773. r"(?<!do not )\bmake\s+implementation\s+provider-backed\s+by\s+default\b",
  1774. ]
  1775. for label in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES
  1776. }
  1777. # Who implements: host-native default + optional external implementer / host-import writer.
  1778. IMPLEMENTATION_LANES_PHRASES = {
  1779. "SKILL.md": [
  1780. "### Who implements (native default, optional extras)",
  1781. "Default: host-native only",
  1782. "Vanilla Cobbler uses whatever host is running the skill",
  1783. "same pattern as the math module",
  1784. "implementation_lane: fast | untrusted",
  1785. "cobbler_agents.py implement prepare|launch|gate|resume-batch|status",
  1786. "references/grok-implementer-launch-prompt.md",
  1787. "the default overnight path",
  1788. "cobbler_agents.py worker",
  1789. "Do not invent top-level Codex slash commands",
  1790. ],
  1791. "CHANGELOG.md": [
  1792. "### Optional external batch implementer",
  1793. "implementation_lane: fast | untrusted",
  1794. "cobbler_agents.py implement prepare|launch|gate|resume-batch|status",
  1795. "references/grok-implementer-launch-prompt.md",
  1796. "not the default overnight path",
  1797. "### Docs: native-first implement framing",
  1798. "vanilla Cobbler is host-native",
  1799. ],
  1800. "references/grok-implementer-launch-prompt.md": [
  1801. "This is not the Elves default",
  1802. "implementation_lane: fast | untrusted",
  1803. "cobbler_agents.py implement prepare",
  1804. "not** use that lease path as the default",
  1805. "Omit `implementation_lane` entirely for host-native runs",
  1806. ],
  1807. "references/councilelves-launch-prompt.md": [
  1808. "Vanilla path",
  1809. "Claude Code or Codex out of the box",
  1810. "implementation_lane: fast | untrusted",
  1811. "cobbler_agents.py implement prepare|launch|gate|resume-batch|status",
  1812. "not** use the untrusted lease path as the default overnight",
  1813. "cobbler_agents.py worker",
  1814. ],
  1815. }
  1816. # External-agent setup (v1.20.0 Batch 5).
  1817. SETUP_COBBLER_PHRASES = {
  1818. "SKILL.md": [
  1819. "### External-agent setup and model onboarding",
  1820. "Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp)",
  1821. "bounded live qualification canary",
  1822. "/setup-cobbler",
  1823. "/setup-council",
  1824. "$elves setup-cobbler",
  1825. "$elves setup-council",
  1826. "not a top-level",
  1827. "cobbler_agents.py onboard",
  1828. "cobbler_agents.py setup",
  1829. ".elves/models.toml",
  1830. "references/model-onboarding.md",
  1831. "references/cobbler-setup-recipes.md",
  1832. ],
  1833. "docs/cobbler.md": [
  1834. "/setup-cobbler",
  1835. "/setup-council",
  1836. "$elves setup-cobbler",
  1837. "$elves setup-council",
  1838. "model onboarding",
  1839. "cobbler-setup-recipes.md",
  1840. "model-onboarding.md",
  1841. "Never stage",
  1842. ],
  1843. "references/cobbler-setup-recipes.md": [
  1844. "/setup-cobbler",
  1845. "/setup-council",
  1846. "$elves setup-cobbler",
  1847. "onboard plan",
  1848. "verified",
  1849. "experimental",
  1850. "custom",
  1851. "OPENROUTER_API_KEY",
  1852. "native-only",
  1853. "remaining_quota",
  1854. "Never stage",
  1855. ],
  1856. "references/model-onboarding.md": [
  1857. "Model Onboarding",
  1858. "Claude Code, Codex, Grok Build, and Oh My Pi",
  1859. "Supported hosts (main drivers)",
  1860. "not been our focus",
  1861. "many have not been heavily",
  1862. "Antigravity CLI",
  1863. "Prefer a PR",
  1864. "onboard plan",
  1865. "onboard apply",
  1866. "onboard probe",
  1867. "Never stage",
  1868. "host-native",
  1869. ],
  1870. "aliases/claude/setup-cobbler/SKILL.md": [
  1871. "model onboarding",
  1872. "onboard plan|show|apply|probe",
  1873. "Never stage",
  1874. ".elves/models.toml",
  1875. "must not require OpenRouter",
  1876. ],
  1877. }
  1878. # Coordinator-to-implementer handoff + git-history-as-operator-UI standards (v1.20.0 Batch 1).
  1879. IMPLEMENTER_HANDOFF_PHRASES = {
  1880. "SKILL.md": [
  1881. "## Coordinator-to-Implementer Handoff Standard",
  1882. "intent / why",
  1883. "Build On targets",
  1884. "owned surfaces",
  1885. "forbidden surfaces",
  1886. "acceptance evidence",
  1887. "failure modes / pitfalls",
  1888. "HEAD / run-doc paths / route-session identity / output format",
  1889. "blocking coordinator defect",
  1890. ],
  1891. "references/plan-template.md": [
  1892. "Coordinator-to-implementer handoff",
  1893. "Build On targets",
  1894. "Owned surfaces",
  1895. "Forbidden surfaces",
  1896. "acceptance evidence",
  1897. "Failure modes / pitfalls",
  1898. "HEAD / run-doc paths / route-session identity / output format",
  1899. ],
  1900. "references/survival-guide-template.md": [
  1901. "Coordinator-to-implementer handoff",
  1902. "Build On targets",
  1903. "owned surfaces",
  1904. "forbidden surfaces",
  1905. "acceptance evidence",
  1906. ],
  1907. "references/execution-log-template.md": [
  1908. "Handoff standard",
  1909. "Build On targets",
  1910. "owned surfaces",
  1911. "forbidden surfaces",
  1912. "acceptance evidence",
  1913. ],
  1914. "references/review-subagent.md": [
  1915. "Coordinator-to-implementer handoff obligations",
  1916. "blocking coordinator defect",
  1917. "Build On targets",
  1918. "owned surfaces",
  1919. "forbidden surfaces",
  1920. "acceptance evidence",
  1921. ],
  1922. }
  1923. RISK_TIER_PHRASES = {
  1924. "SKILL.md": [
  1925. "Thin safety kernel",
  1926. "validate once, verify changes, attest final",
  1927. "low | standard | high",
  1928. "trusted | untrusted",
  1929. "touched surfaces",
  1930. "risk checkpoints",
  1931. "terminal readiness",
  1932. "exact HEAD",
  1933. "impact-selected",
  1934. ],
  1935. "references/joyful-runs-contract.md": [
  1936. "low",
  1937. "standard",
  1938. "high",
  1939. "trusted",
  1940. "untrusted",
  1941. "ready=true never grants merge permission",
  1942. ],
  1943. "references/proof-and-review.md": [
  1944. "validate once, verify changes, attest final",
  1945. "impact path",
  1946. "delta re-review",
  1947. ],
  1948. }
  1949. PROGRESS_COMMIT_PHRASES = {
  1950. "SKILL.md": [
  1951. "## Git History as Operator UI",
  1952. "[<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>",
  1953. "Forbid vague subjects",
  1954. "audited detached handoff commits",
  1955. "never own refs, remotes, push, PRs, or canonical run memory",
  1956. "Reserve the `Close` phase for acceptance-backed batch completion",
  1957. "Protected refs, PR operations, and merge never dispatch model inference",
  1958. ],
  1959. "references/plan-template.md": [
  1960. "Contract|Implement|Validate|Review|Close",
  1961. "Forbid vague subjects",
  1962. "audited detached handoff commits",
  1963. "never own refs/remotes/push/PR/run-memory",
  1964. "Close` requires",
  1965. ],
  1966. "references/survival-guide-template.md": [
  1967. "Contract|Implement|Validate|Review|Close",
  1968. "Forbid vague subjects",
  1969. "audited detached handoff commits",
  1970. "Close` requires acceptance",
  1971. "Git/PR ops never dispatch model inference",
  1972. ],
  1973. "references/execution-log-template.md": [
  1974. "Contract|Implement|Validate|Review|Close",
  1975. "forbid vague subjects",
  1976. "audited detached handoff commits",
  1977. "never own refs/remotes/push/PR/run-memory",
  1978. ],
  1979. "references/review-subagent.md": [
  1980. "Git history as operator UI",
  1981. "Contract|Implement|Validate|Review|Close",
  1982. "audited detached handoff commits",
  1983. "Close` appears only with acceptance evidence",
  1984. "did not dispatch model inference",
  1985. ],
  1986. }
  1987. # Vague subjects must remain present as anti-pattern examples on skill mirrors.
  1988. PROGRESS_COMMIT_ANTIPATTERN_EXAMPLES = {
  1989. "SKILL.md": [
  1990. "[feat/payments · Batch 3/12] Updates",
  1991. "[feat/payments · Batch 3/12 · Implement] progress",
  1992. "[feat/payments · Batch 3/12 · Implement] WIP",
  1993. "[feat/payments · Batch 3/12 · Implement] fixes",
  1994. ],
  1995. }
  1996. PUBLIC_WORDING_FILES = [
  1997. REPO_ROOT / "SKILL.md",
  1998. REPO_ROOT / "AGENTS.md",
  1999. REPO_ROOT / "README.md",
  2000. REPO_ROOT / "CHANGELOG.md",
  2001. REPO_ROOT / "config.json.example",
  2002. ]
  2003. PUBLIC_WORDING_FORBIDDEN_PHRASES = [
  2004. # Exact model names are valid in the route-identity contract. Keep
  2005. # prohibiting branding/persona claims that describe Cobbler as Fable-like.
  2006. "Fable-like",
  2007. "Fable-style",
  2008. "inspired by Fable",
  2009. "Fable-powered",
  2010. "cobbled together",
  2011. "cobbled-together",
  2012. ]
  2013. # Persona claims that describe Cobbler as *being* Fable (or other host models as
  2014. # product personas), matched case-insensitively. Bare model identifiers
  2015. # (`Fable 5`, `claude-fable-5`, route tables) remain legitimate and must not match.
  2016. PUBLIC_WORDING_FORBIDDEN_PATTERNS = [
  2017. r"powered\s+by\s+fable",
  2018. r"built\s+on\s+fable",
  2019. r"backed\s+by\s+fable",
  2020. r"driven\s+by\s+fable",
  2021. r"runs\s+on\s+fable",
  2022. r"fable\s+under\s+the\s+hood",
  2023. r"fable\s+persona",
  2024. # "is Fable" / "is a Fable …" product-persona claims (not "Fable 5 model").
  2025. r"\bis\s+(?:a\s+)?fable(?:\s+model|\s+persona|\s+agent)?\b(?!\s*[0-9])",
  2026. # Claude/Anthropic persona claims for Cobbler/Elves product identity.
  2027. r"powered\s+by\s+claude",
  2028. r"powered\s+by\s+anthropic",
  2029. r"claude\s+persona",
  2030. r"anthropic\s+persona",
  2031. ]
  2032. # --- Elves 2.3: thin AGENTS adapter + compact SKILL pins ---
  2033. _AGENTS_THIN_POINTER = [
  2034. 'thin Codex adapter',
  2035. 'canonical workflow is',
  2036. 'SKILL.md',
  2037. 'Codex Goals',
  2038. 'Grok Build goal mode',
  2039. 'chat-to-work',
  2040. 'chat-to-land',
  2041. 'plan Acceptance with proof',
  2042. 'Stop Gate',
  2043. 'continuation_guard',
  2044. '\\land-pr',
  2045. '/land-pr',
  2046. 'source-checkout shorthand',
  2047. 'active Elves skill root',
  2048. '$ELVES_SKILL_ROOT/scripts/elves_landing_check.py',
  2049. '--session <session-path> --repo-root .',
  2050. 'Build On',
  2051. 'owned surfaces',
  2052. 'forbidden surfaces',
  2053. 'acceptance evidence',
  2054. 'blocking coordinator defect',
  2055. 'Contract|Implement|Validate|Review|Close',
  2056. 'Forbid vague subjects',
  2057. '[feat/auth · Batch 3/12] Updates',
  2058. '[feat/auth · Batch 3/12 · Implement] progress',
  2059. 'One run owns one branch and one checkout',
  2060. 'optional regression evidence',
  2061. ]
  2062. # One whole-file thin-adapter check replaces the per-corpus AGENTS.md shims:
  2063. # AGENTS.md is a pointer file, so it carries each contract's NAME exactly once
  2064. # and the corpora that own the contracts no longer pin AGENTS.md separately.
  2065. AGENTS_POINTER_PHRASES = {"AGENTS.md": list(_AGENTS_THIN_POINTER)}
  2066. if isinstance(COUNCIL_MODULE_PHRASES, dict):
  2067. COUNCIL_MODULE_PHRASES = dict(COUNCIL_MODULE_PHRASES)
  2068. COUNCIL_MODULE_PHRASES["AGENTS.md"] = [
  2069. "$elves cobbler: <task>",
  2070. "$elves council: <task>",
  2071. "Ask the Cobbler",
  2072. "Codex Goals",
  2073. "Grok Build goal mode",
  2074. "capability-proven enhancement",
  2075. "one-packet fallback",
  2076. "authenticated live catalog",
  2077. ]
  2078. if isinstance(COBBLER_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in COBBLER_FORBIDDEN_PATTERNS:
  2079. COBBLER_FORBIDDEN_PATTERNS = {k: v for k, v in COBBLER_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2080. if isinstance(COBBLER_HARNESS_DRIFT_PATTERNS, dict) and 'AGENTS.md' in COBBLER_HARNESS_DRIFT_PATTERNS:
  2081. COBBLER_HARNESS_DRIFT_PATTERNS = {k: v for k, v in COBBLER_HARNESS_DRIFT_PATTERNS.items() if k != 'AGENTS.md'}
  2082. if isinstance(DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS:
  2083. DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS = {k: v for k, v in DOMAIN_WORKFLOW_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2084. if isinstance(EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS:
  2085. EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS = {k: v for k, v in EXACT_FULL_RUN_COMMAND_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2086. if isinstance(FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS:
  2087. FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS = {k: v for k, v in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2088. if isinstance(INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS:
  2089. INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS = {k: v for k, v in INSTALLED_REPO_ONLY_HELPER_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2090. if isinstance(LANDING_CHECK_BARE_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in LANDING_CHECK_BARE_FORBIDDEN_PATTERNS:
  2091. LANDING_CHECK_BARE_FORBIDDEN_PATTERNS = {k: v for k, v in LANDING_CHECK_BARE_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2092. if isinstance(PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS, dict) and 'AGENTS.md' in PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS:
  2093. PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS = {k: v for k, v in PUBLIC_API_SURFACE_SNAPSHOT_FORBIDDEN_PATTERNS.items() if k != 'AGENTS.md'}
  2094. if isinstance(SINGLE_KICKOFF_UNSCOPED_PATTERNS, dict) and 'AGENTS.md' in SINGLE_KICKOFF_UNSCOPED_PATTERNS:
  2095. SINGLE_KICKOFF_UNSCOPED_PATTERNS = {k: v for k, v in SINGLE_KICKOFF_UNSCOPED_PATTERNS.items() if k != 'AGENTS.md'}
  2096. if isinstance(COUNCIL_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in COUNCIL_FORBIDDEN_PHRASES:
  2097. COUNCIL_FORBIDDEN_PHRASES = {k: v for k, v in COUNCIL_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
  2098. if isinstance(DOMAIN_WORKFLOW_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in DOMAIN_WORKFLOW_FORBIDDEN_PHRASES:
  2099. DOMAIN_WORKFLOW_FORBIDDEN_PHRASES = {k: v for k, v in DOMAIN_WORKFLOW_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
  2100. if isinstance(FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES:
  2101. FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES = {k: v for k, v in FULL_RUN_MODEL_ROUTING_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
  2102. if isinstance(REVIEWED_PR_LANDING_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in REVIEWED_PR_LANDING_FORBIDDEN_PHRASES:
  2103. REVIEWED_PR_LANDING_FORBIDDEN_PHRASES = {k: v for k, v in REVIEWED_PR_LANDING_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
  2104. if isinstance(SINGLE_KICKOFF_FORBIDDEN_PHRASES, dict) and 'AGENTS.md' in SINGLE_KICKOFF_FORBIDDEN_PHRASES:
  2105. SINGLE_KICKOFF_FORBIDDEN_PHRASES = {k: v for k, v in SINGLE_KICKOFF_FORBIDDEN_PHRASES.items() if k != 'AGENTS.md'}
  2106. if isinstance(ACCEPTANCE_EVIDENCE_PHRASES, dict) and 'SKILL.md' in ACCEPTANCE_EVIDENCE_PHRASES:
  2107. ACCEPTANCE_EVIDENCE_PHRASES = dict(ACCEPTANCE_EVIDENCE_PHRASES)
  2108. ACCEPTANCE_EVIDENCE_PHRASES['SKILL.md'] = ['plan Acceptance with proof', 'acceptance', 'elves_landing_check.py', 'God-file', 'one batch per close commit']
  2109. if isinstance(COBBLER_CONFIG_PREFERENCE_PHRASES, dict) and 'SKILL.md' in COBBLER_CONFIG_PREFERENCE_PHRASES:
  2110. COBBLER_CONFIG_PREFERENCE_PHRASES = dict(COBBLER_CONFIG_PREFERENCE_PHRASES)
  2111. COBBLER_CONFIG_PREFERENCE_PHRASES['SKILL.md'] = ['config.json', 'cobbler', 'council']
  2112. if isinstance(COBBLER_HARNESS_LOOP_PHRASES, dict) and 'SKILL.md' in COBBLER_HARNESS_LOOP_PHRASES:
  2113. COBBLER_HARNESS_LOOP_PHRASES = dict(COBBLER_HARNESS_LOOP_PHRASES)
  2114. COBBLER_HARNESS_LOOP_PHRASES['SKILL.md'] = ['capability scan', 'context packet', 'Cobbler-first', 'fit answer']
  2115. if isinstance(COBBLER_MODE_PHRASES, dict) and 'SKILL.md' in COBBLER_MODE_PHRASES:
  2116. COBBLER_MODE_PHRASES = dict(COBBLER_MODE_PHRASES)
  2117. COBBLER_MODE_PHRASES['SKILL.md'] = ['Cobbler Mode', 'cobbler-mode', 'not durable run state']
  2118. if isinstance(COUNCIL_MODULE_PHRASES, dict) and 'SKILL.md' in COUNCIL_MODULE_PHRASES:
  2119. COUNCIL_MODULE_PHRASES = dict(COUNCIL_MODULE_PHRASES)
  2120. 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']
  2121. if isinstance(DOMAIN_WORKFLOW_PHRASES, dict) and 'SKILL.md' in DOMAIN_WORKFLOW_PHRASES:
  2122. DOMAIN_WORKFLOW_PHRASES = dict(DOMAIN_WORKFLOW_PHRASES)
  2123. 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']
  2124. if isinstance(EFFORT_GUARDRAIL_PHRASES, dict) and 'SKILL.md' in EFFORT_GUARDRAIL_PHRASES:
  2125. EFFORT_GUARDRAIL_PHRASES = dict(EFFORT_GUARDRAIL_PHRASES)
  2126. EFFORT_GUARDRAIL_PHRASES['SKILL.md'] = [
  2127. '## Effort Standard',
  2128. 'Work as hard as you can',
  2129. 'plan acceptance and blockers',
  2130. 'deferred hygiene',
  2131. ]
  2132. if isinstance(ELVES_REPORT_PHRASES, dict) and 'SKILL.md' in ELVES_REPORT_PHRASES:
  2133. ELVES_REPORT_PHRASES = dict(ELVES_REPORT_PHRASES)
  2134. 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']
  2135. if isinstance(FINAL_READINESS_REVIEW_PHRASES, dict) and 'SKILL.md' in FINAL_READINESS_REVIEW_PHRASES:
  2136. FINAL_READINESS_REVIEW_PHRASES = dict(FINAL_READINESS_REVIEW_PHRASES)
  2137. FINAL_READINESS_REVIEW_PHRASES['SKILL.md'] = ['Final Readiness Review', 'git diff <default-branch>...HEAD', 'review subagent']
  2138. if isinstance(FULL_RUN_MODEL_ROUTING_PHRASES, dict) and 'SKILL.md' in FULL_RUN_MODEL_ROUTING_PHRASES:
  2139. FULL_RUN_MODEL_ROUTING_PHRASES = dict(FULL_RUN_MODEL_ROUTING_PHRASES)
  2140. FULL_RUN_MODEL_ROUTING_PHRASES['SKILL.md'] = ['model routing', 'native-first', 'fallback', 'Missing optional provider access']
  2141. if isinstance(IMPLEMENTATION_LANES_PHRASES, dict) and 'SKILL.md' in IMPLEMENTATION_LANES_PHRASES:
  2142. IMPLEMENTATION_LANES_PHRASES = dict(IMPLEMENTATION_LANES_PHRASES)
  2143. IMPLEMENTATION_LANES_PHRASES['SKILL.md'] = ['trusted Grok', 'full-run', 'parked', 'untrusted', 'Do not invent top-level Codex slash commands', 'implementation_lane: fast | untrusted']
  2144. if isinstance(IMPLEMENTER_HANDOFF_PHRASES, dict) and 'SKILL.md' in IMPLEMENTER_HANDOFF_PHRASES:
  2145. IMPLEMENTER_HANDOFF_PHRASES = dict(IMPLEMENTER_HANDOFF_PHRASES)
  2146. 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']
  2147. if isinstance(INSTALLED_HELPER_PATH_PHRASES, dict) and 'SKILL.md' in INSTALLED_HELPER_PATH_PHRASES:
  2148. INSTALLED_HELPER_PATH_PHRASES = dict(INSTALLED_HELPER_PATH_PHRASES)
  2149. 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']
  2150. if isinstance(LANDING_CHECK_CONTRACT_PHRASES, dict) and 'SKILL.md' in LANDING_CHECK_CONTRACT_PHRASES:
  2151. LANDING_CHECK_CONTRACT_PHRASES = dict(LANDING_CHECK_CONTRACT_PHRASES)
  2152. LANDING_CHECK_CONTRACT_PHRASES['SKILL.md'] = ['$ELVES_SKILL_ROOT/scripts/elves_landing_check.py', '--session <session-path> --repo-root .', 'plan_path', 'equality assertion']
  2153. if isinstance(MATH_MODULE_PHRASES, dict) and 'SKILL.md' in MATH_MODULE_PHRASES:
  2154. MATH_MODULE_PHRASES = dict(MATH_MODULE_PHRASES)
  2155. 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']
  2156. if isinstance(MEMORY_HYGIENE_PHRASES, dict) and 'SKILL.md' in MEMORY_HYGIENE_PHRASES:
  2157. MEMORY_HYGIENE_PHRASES = dict(MEMORY_HYGIENE_PHRASES)
  2158. MEMORY_HYGIENE_PHRASES['SKILL.md'] = ['## Strategic Forgetting', 'chats are for execution', 'memory and resource hygiene']
  2159. if isinstance(NONSTOP_GUARDRAIL_PHRASES, dict) and 'SKILL.md' in NONSTOP_GUARDRAIL_PHRASES:
  2160. NONSTOP_GUARDRAIL_PHRASES = dict(NONSTOP_GUARDRAIL_PHRASES)
  2161. 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']
  2162. if isinstance(PROGRESS_COMMIT_PHRASES, dict) and 'SKILL.md' in PROGRESS_COMMIT_PHRASES:
  2163. PROGRESS_COMMIT_PHRASES = dict(PROGRESS_COMMIT_PHRASES)
  2164. 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']
  2165. if isinstance(PUBLIC_API_SURFACE_SNAPSHOT_PHRASES, dict) and 'SKILL.md' in PUBLIC_API_SURFACE_SNAPSHOT_PHRASES:
  2166. PUBLIC_API_SURFACE_SNAPSHOT_PHRASES = dict(PUBLIC_API_SURFACE_SNAPSHOT_PHRASES)
  2167. 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']
  2168. if isinstance(REVIEWED_PR_LANDING_PHRASES, dict) and 'SKILL.md' in REVIEWED_PR_LANDING_PHRASES:
  2169. REVIEWED_PR_LANDING_PHRASES = dict(REVIEWED_PR_LANDING_PHRASES)
  2170. 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']
  2171. if isinstance(RISK_TIER_PHRASES, dict) and 'SKILL.md' in RISK_TIER_PHRASES:
  2172. RISK_TIER_PHRASES = dict(RISK_TIER_PHRASES)
  2173. 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']
  2174. if isinstance(SETUP_COBBLER_PHRASES, dict) and 'SKILL.md' in SETUP_COBBLER_PHRASES:
  2175. SETUP_COBBLER_PHRASES = dict(SETUP_COBBLER_PHRASES)
  2176. 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']
  2177. if isinstance(SINGLE_KICKOFF_PHRASES, dict) and 'SKILL.md' in SINGLE_KICKOFF_PHRASES:
  2178. SINGLE_KICKOFF_PHRASES = dict(SINGLE_KICKOFF_PHRASES)
  2179. 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']
  2180. if isinstance(WORKSPACE_ISOLATION_PHRASES, dict) and 'SKILL.md' in WORKSPACE_ISOLATION_PHRASES:
  2181. WORKSPACE_ISOLATION_PHRASES = dict(WORKSPACE_ISOLATION_PHRASES)
  2182. 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']
  2183. ADAPTIVE_WORKER_ROUTING_PHRASES = {
  2184. "SKILL.md": [
  2185. "subscription-native worker",
  2186. "authenticated live",
  2187. "same GPT-6 Astra model at `medium`",
  2188. "same GPT-5.6 model at `medium`",
  2189. "same Fable 5.1 model at `low`",
  2190. "same Opus 5.5 model at `high`",
  2191. "Native delegation stays inside one model family",
  2192. "prefer `grok-4.7` at explicit `high`",
  2193. "Composer 2.5 is retired",
  2194. "${XDG_CONFIG_HOME:-~/.config}/elves/config.json",
  2195. "approval-bypass authority",
  2196. ],
  2197. "AGENTS.md": [
  2198. "exact same-model/lower-effort route map",
  2199. "references/adaptive-worker-routing.md",
  2200. ],
  2201. "README.md": [
  2202. "Native delegation names both model and effort",
  2203. "same GPT-6 Astra model at `medium`",
  2204. "same GPT-5.6 model at `medium`",
  2205. "same Fable 5.1 model at `low`",
  2206. "same Opus 5.5 model at `high`",
  2207. "There is no Fable→Opus route",
  2208. "`grok-4.7` at explicit `high`",
  2209. "Composer 2.5",
  2210. ],
  2211. "references/adaptive-worker-routing.md": [
  2212. "repository safety veto > explicit run intent > repository defaults > global convenience",
  2213. "authenticated live",
  2214. "exact observed model identity",
  2215. "same observed `gpt-6-astra` model ID at `medium`",
  2216. "same observed GPT-5.6 model ID at `medium`",
  2217. "same observed `claude-fable-5-1` model ID at `low`",
  2218. "same observed `claude-opus-5-5` model ID at `high`",
  2219. "Native delegation stays inside one model family",
  2220. "Elves no longer defines a",
  2221. "`grok-4.7` at `high` when present in the live catalog",
  2222. "Composer 2.5 is retired",
  2223. "codex exec resume <thread-id>",
  2224. "a session ID is not such an object",
  2225. ],
  2226. "guide/index.html": [
  2227. "Same model, lower effort",
  2228. "GPT-6 Astra <code>medium</code>",
  2229. "GPT-5.6 <code>medium</code>",
  2230. "Fable 5.1 <code>low</code>",
  2231. "Opus 5.5 <code>high</code>",
  2232. "stays inside one model family",
  2233. "<code>grok-4.7</code> at <code>high</code>",
  2234. "Composer 2.5 is retired",
  2235. ],
  2236. "CHANGELOG.md": [
  2237. "Explicit delegation route identity and Grok highest-effort default",
  2238. "same GPT-5.6 identity at `medium`",
  2239. "Remove the Fable→Opus cross-model route",
  2240. "same observed `claude-opus-5` model at `high`",
  2241. "authenticated live-catalog default at explicit",
  2242. "Prefer **`grok-4.5` at `high`**",
  2243. "Adaptive subscription-native workers",
  2244. "authenticated live-catalog models",
  2245. "prompt/KV cache",
  2246. ],
  2247. }
  2248. # The Fugu shortcut's model/effort profiles are restated on six surfaces, and the
  2249. # only Fugu coverage used to be the Claude alias phrase group. A model rename could
  2250. # therefore land everywhere except one page and still pass: that is exactly how
  2251. # `guide/index.html` kept saying `fugu-ultra/high` after every other surface moved
  2252. # to `fugu-ultra-v1.1/high`. Pin all five profiles per surface, in that surface's
  2253. # own markup, so the next rename has to be complete.
  2254. FUGU_SHORTCUT_PROFILE_PHRASES = {
  2255. "SKILL.md": [
  2256. "`fugu/high`",
  2257. "`fugu/xhigh`",
  2258. "`fugu-cyber/xhigh`",
  2259. "`fugu-ultra-v2.0/high`",
  2260. "`fugu-ultra-v1.1/max`",
  2261. ],
  2262. "AGENTS.md": [
  2263. "`fugu/high`",
  2264. "`fugu/xhigh`",
  2265. "`fugu-cyber/xhigh`",
  2266. "`fugu-ultra-v2.0/high`",
  2267. "`fugu-ultra-v1.1/max`",
  2268. ],
  2269. "README.md": [
  2270. "`fugu/high`",
  2271. "`fugu/xhigh`",
  2272. "`fugu-cyber/xhigh`",
  2273. "`fugu-ultra-v2.0/high`",
  2274. "`fugu-ultra-v1.1/max`",
  2275. ],
  2276. "guide/index.html": [
  2277. "<code>fugu/high</code>",
  2278. "<code>fugu/xhigh</code>",
  2279. "<code>fugu-cyber/xhigh</code>",
  2280. "<code>fugu-ultra-v2.0/high</code>",
  2281. "<code>fugu-ultra-v1.1/max</code>",
  2282. ],
  2283. "references/provider-shortcuts.md": [
  2284. "`fugu` / `high`",
  2285. "`fugu` / `xhigh`",
  2286. "`fugu-cyber` / `xhigh`",
  2287. "`fugu-ultra-v2.0` / `high`",
  2288. "`fugu-ultra-v1.1` / `max`",
  2289. ],
  2290. "aliases/claude/fugu/SKILL.md": [
  2291. "`fugu/high`",
  2292. "`fugu/xhigh`",
  2293. "`fugu-cyber/xhigh`",
  2294. "`fugu-ultra-v2.0/high`",
  2295. "`fugu-ultra-v1.1/max`",
  2296. ],
  2297. }
  2298. # The complete /fugu invocation grammar on every restating surface. The v2.17.1
  2299. # release fixed `--max` missing from these grammars after v2.17.0 shipped it on
  2300. # one surface only; this group pins the full task and review forms so a flag
  2301. # added to the runner cannot land on five surfaces and miss the sixth again.
  2302. # (The alias surface's grammar is pinned with the alias phrase group.)
  2303. FUGU_INVOCATION_GRAMMAR_PHRASES = {
  2304. "SKILL.md": [
  2305. "`/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
  2306. "`/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
  2307. ],
  2308. "AGENTS.md": [
  2309. "`$elves fugu [--deep\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
  2310. "`$elves fugu [--deep\\|--cyber\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
  2311. ],
  2312. "README.md": [
  2313. "`/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
  2314. "`/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
  2315. ],
  2316. "guide/index.html": [
  2317. "<code>/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] &lt;planning-task&gt;</code>",
  2318. "<code>/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review &lt;scope&gt;</code>",
  2319. ],
  2320. "references/provider-shortcuts.md": [
  2321. "`/fugu [--deep\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`",
  2322. "`/fugu [--deep\\|--cyber\\|--ultra\\|--max] [--max-wait SECONDS] [--preflight] review <scope>`",
  2323. ],
  2324. }
  2325. # Host-side Fugu routing when the user omits a profile flag. Without these pins,
  2326. # a surface can keep saying "default is regular fugu/high" while the host-routing
  2327. # contract (choose lane before launch; isolation snapshot always on; profile locks
  2328. # model) drifts on the others. Keep the shared decision anchors short so ordinary
  2329. # editorial rewording of surrounding prose does not fail CI.
  2330. FUGU_HOST_ROUTING_PHRASES = {
  2331. "SKILL.md": [
  2332. "Host Fugu routing",
  2333. "Fugu route:",
  2334. 'Host routing when the user says "use Fugu"',
  2335. "isolation snapshot is always on",
  2336. "explicit user flags always win",
  2337. "Use plain regular Fugu by default",
  2338. "successful Cyber call in the current session",
  2339. "must explicitly select `--ultra` or `--max`",
  2340. ],
  2341. "AGENTS.md": [
  2342. "Host Fugu routing",
  2343. "Fugu route:",
  2344. 'Host routing when the user says "use Fugu"',
  2345. "isolation snapshot is always on",
  2346. "explicit user flags always win",
  2347. "Plain regular Fugu is the default",
  2348. "successful Cyber call in the current",
  2349. "must explicitly select `--ultra`",
  2350. ],
  2351. "README.md": [
  2352. "Host Fugu routing",
  2353. "Fugu route:",
  2354. 'Host routing when the user says "use Fugu"',
  2355. "isolation snapshot is always on",
  2356. "explicit flags always win",
  2357. "Plain regular Fugu is the default",
  2358. "successful Cyber call in the current session",
  2359. "must explicitly select Ultra or Max",
  2360. ],
  2361. "guide/index.html": [
  2362. "Fugu route:",
  2363. 'Host routing when the user says "use Fugu"',
  2364. "isolation snapshot is always on",
  2365. "flags always win",
  2366. "Plain regular Fugu is the default",
  2367. "successful Cyber call in the current session",
  2368. "must explicitly select Ultra or Max",
  2369. ],
  2370. "references/provider-shortcuts.md": [
  2371. 'Host routing when the user says "use Fugu"',
  2372. "does not score complexity",
  2373. "isolation snapshot is not optional",
  2374. "plain `fugu/high` by default",
  2375. "successful Cyber call in the current session",
  2376. "must explicitly select `--ultra` or `--max`",
  2377. "Explicit user flags",
  2378. "always win",
  2379. "runner flag",
  2380. "select `--cyber` only",
  2381. ],
  2382. "aliases/claude/fugu/SKILL.md": [
  2383. "Host Fugu routing",
  2384. "Fugu route:",
  2385. 'Host routing when the user says "use Fugu"',
  2386. "isolation snapshot is always on",
  2387. "Explicit user flags always win",
  2388. "bare `fugu/high` by default",
  2389. "successful Cyber call in the current session",
  2390. "must explicitly select `--ultra` or `--max`",
  2391. ],
  2392. }
  2393. PREWALK_PHRASES = {
  2394. "SKILL.md": [
  2395. "Exact-session prewalk",
  2396. "A fresh session",
  2397. "with a copied packet or summary is not prewalk",
  2398. "post-edit cold fallback is forbidden",
  2399. "Static help proves",
  2400. "bounded live qualification canary",
  2401. "experimental",
  2402. "references/prewalk.md",
  2403. ],
  2404. "AGENTS.md": [
  2405. "Prewalk:",
  2406. "cold packet handoff is not prewalk",
  2407. "references/prewalk.md",
  2408. ],
  2409. "README.md": [
  2410. "Optional exact-session prewalk",
  2411. "same session in the same worktree",
  2412. "180-second",
  2413. "experimental",
  2414. "references/prewalk.md",
  2415. ],
  2416. "references/prewalk.md": [
  2417. "Elves **prewalk** is a trajectory property",
  2418. "separately qualified worker session",
  2419. "execution route with only",
  2420. "retained_safe",
  2421. "post-edit cold fallback",
  2422. "`required` automatically runs one bounded live qualification canary",
  2423. "`experimental` is an explicit operator acceptance",
  2424. "grok_prewalk_qualification_canary",
  2425. "single-phase native-worker launch",
  2426. "It never stores model output",
  2427. ],
  2428. "references/host-parity.md": [
  2429. "Exact-session prewalk parity",
  2430. "one redacted logical follow stream",
  2431. "no post-edit cold fallback",
  2432. "prewalk.md",
  2433. "automatic required-mode qualification",
  2434. "exact_session_experimental",
  2435. "single-phase native-worker launch",
  2436. ],
  2437. "references/adaptive-worker-routing.md": [
  2438. "Optional exact-session prewalk route",
  2439. "requested/actual prewalk mode",
  2440. "help probes always report false",
  2441. "actual mode `off`",
  2442. "qualification_required",
  2443. "exact_session_experimental",
  2444. "single-phase native-worker launch",
  2445. ],
  2446. "guide/index.html": [
  2447. "Use exact-session prewalk",
  2448. "same session in the same",
  2449. "180-second",
  2450. "exact_session_experimental",
  2451. "references/prewalk.md",
  2452. ],
  2453. "CHANGELOG.md": [
  2454. "Automatic prewalk qualification",
  2455. "180-second",
  2456. "exact_session_experimental",
  2457. "private `.attempt.json`",
  2458. "Grok single-phase native-worker",
  2459. ],
  2460. }
  2461. EXPLICIT_HANDOFF_V1_PHRASES = {
  2462. "SKILL.md": [
  2463. "strict explicit",
  2464. "handoff v1",
  2465. "advisory, never",
  2466. "does not turn a cold handoff into exact-session prewalk",
  2467. ],
  2468. "AGENTS.md": [
  2469. "explicitly declared handoff-v1",
  2470. "strict",
  2471. "host-neutral",
  2472. ],
  2473. "README.md": [
  2474. "machine-checked cold handoff",
  2475. "ordinary v2.8 path remains advisory",
  2476. "not prewalk continuity proof",
  2477. ],
  2478. "references/schema-and-acceptance.md": [
  2479. "Optional explicit handoff v1",
  2480. "Presence is the opt-in",
  2481. "Both formats are bounded",
  2482. "It is not trajectory continuity",
  2483. ],
  2484. "references/survival-guide-template.md": [
  2485. "Handoff validation:",
  2486. "explicit-v1",
  2487. "never proof of exact-session prewalk continuity",
  2488. ],
  2489. "CHANGELOG.md": [
  2490. "Explicit handoff v1 staging contract",
  2491. "advisory-only",
  2492. "never proves exact-session prewalk continuity",
  2493. ],
  2494. }
  2495. GROK_OPEN_SOURCE_WORKER_PHRASES = {
  2496. "SKILL.md": [
  2497. "authenticated live",
  2498. "behaviorally proven headless goal mode",
  2499. "one-packet fallback",
  2500. "Native Claude Code and Codex",
  2501. ],
  2502. "CHANGELOG.md": [
  2503. "authenticated live-catalog models",
  2504. "behaviorally proven headless `/goal`",
  2505. "one-packet fallback",
  2506. "Native Codex and Claude Code routes",
  2507. ],
  2508. "docs/elves/learnings.md": [
  2509. "authenticated live catalog's parsed default",
  2510. "another exact catalog member",
  2511. "`/goal status` command resolution",
  2512. "did not reach terminal state",
  2513. "one-packet prompt fallback",
  2514. "mode-safe terminal-canary JSON artifact",
  2515. "digest ID",
  2516. "full-run-await",
  2517. ],
  2518. "references/adaptive-worker-routing.md": [
  2519. "authenticated live",
  2520. "behaviorally verified headless `/goal`",
  2521. "one-packet prompt fallback",
  2522. "--grok-goal-behavioral-evidence <artifact.json>",
  2523. "exact installed version/build",
  2524. "--host claude",
  2525. ],
  2526. "references/cobbler-setup-recipes.md": [
  2527. "authenticated live catalog",
  2528. "one-packet fallback",
  2529. "full-run-await --json",
  2530. "grok-open-source-worker.md",
  2531. ],
  2532. "references/grok-implementer-launch-prompt.md": [
  2533. "authenticated live-catalog parsed default",
  2534. "one-packet prompt path",
  2535. "full-run-await",
  2536. "Claude Code and Codex remain complete without Grok",
  2537. ],
  2538. "references/grok-open-source-worker.md": [
  2539. "https://github.com/xai-org/grok-build",
  2540. "curl -fsSL https://x.ai/cli/install.sh | bash",
  2541. "--allow-grok --probe-grok",
  2542. "ELVES_HOST=claude",
  2543. "--host \"$ELVES_HOST\"",
  2544. "grok_goal_terminal_canary",
  2545. "prompt_sha256",
  2546. "64 KiB",
  2547. "32 KiB",
  2548. "digest-derived evidence ID",
  2549. "narrow auth projection",
  2550. "command resolution",
  2551. "terminal state",
  2552. "one-packet fallback",
  2553. "full-run-launch --json",
  2554. "full-run-await --json",
  2555. "full-run-reconcile --json",
  2556. "--host-tests-pass",
  2557. "--resume --grant-grok-auth",
  2558. "/goal resume",
  2559. "## Qualified prewalk lane (distinct from trusted full-run)",
  2560. "--permission-mode auto",
  2561. "grok_prewalk_qualification_canary",
  2562. "Required mode automatically runs the bounded live canary",
  2563. "single-phase Grok native-worker launch gated",
  2564. "commit `98c3b24`",
  2565. "source commit `7cfcb20`",
  2566. ],
  2567. "guide/index.html": [
  2568. "https://github.com/xai-org/grok-build",
  2569. "curl -fsSL https://x.ai/cli/install.sh | bash",
  2570. "--provider grok --allow-grok --probe-grok",
  2571. "ELVES_HOST=claude",
  2572. "--host \"$ELVES_HOST\"",
  2573. "mode-safe JSON canary artifact",
  2574. "prompt digest",
  2575. "narrow OAuth projection",
  2576. "command resolution",
  2577. "terminal",
  2578. "one-packet fallback",
  2579. "implement full-run-await --session-id",
  2580. "implement full-run-launch --session-id",
  2581. "implement full-run-reconcile --json",
  2582. "--host-tests-pass",
  2583. "--grant-grok-auth --grant-github-push",
  2584. ],
  2585. "references/host-parity.md": [
  2586. "narrow auth projection",
  2587. "command resolution",
  2588. "catalog lookup and model inference",
  2589. "validated terminal objective-canary artifact",
  2590. "exact installed version/build",
  2591. "prompt digest",
  2592. "one-packet fallback",
  2593. "catalog qualify",
  2594. "--host claude",
  2595. "--host codex",
  2596. "live driver's transport",
  2597. ],
  2598. }
  2599. _GROK_UPSTREAM_PIN_RE = None # lazily compiled in grok_upstream_commit_pin_errors
  2600. def grok_upstream_commit_pin_errors(semantic_commit: str | None = None) -> list[str]:
  2601. """Cross-check the doc-pinned Grok upstream short SHA against runtime.
  2602. The reference doc pin ("source commit `<short>`" over
  2603. references/grok-open-source-worker.md) and
  2604. worker_routing.GROK_UPSTREAM_SEMANTIC_COMMIT describe the same upstream
  2605. commit; a one-sided bump of either must fail consistency. Tests may inject
  2606. a semantic_commit to exercise the disagreeing state.
  2607. """
  2608. import re
  2609. import sys
  2610. global _GROK_UPSTREAM_PIN_RE
  2611. if _GROK_UPSTREAM_PIN_RE is None:
  2612. _GROK_UPSTREAM_PIN_RE = re.compile(r"source commit `([0-9a-f]{7,40})`")
  2613. if semantic_commit is None:
  2614. scripts_dir = str(REPO_ROOT / "scripts")
  2615. if scripts_dir not in sys.path:
  2616. sys.path.insert(0, scripts_dir)
  2617. from cobbler_runtime.worker_routing import ( # noqa: PLC0415
  2618. GROK_UPSTREAM_SEMANTIC_COMMIT,
  2619. )
  2620. semantic_commit = GROK_UPSTREAM_SEMANTIC_COMMIT
  2621. pins = [
  2622. match
  2623. for phrase in GROK_OPEN_SOURCE_WORKER_PHRASES.get(
  2624. "references/grok-open-source-worker.md", []
  2625. )
  2626. for match in _GROK_UPSTREAM_PIN_RE.findall(phrase)
  2627. ]
  2628. errors: list[str] = []
  2629. if not pins:
  2630. errors.append(
  2631. "consistency policy no longer pins the Grok upstream `source commit` "
  2632. "phrase over references/grok-open-source-worker.md"
  2633. )
  2634. for pin in pins:
  2635. if not str(semantic_commit or "").startswith(pin):
  2636. errors.append(
  2637. f"doc-pinned Grok upstream source commit `{pin}` is not a prefix "
  2638. "of worker_routing.GROK_UPSTREAM_SEMANTIC_COMMIT "
  2639. f"`{semantic_commit}`; bump both sides together"
  2640. )
  2641. return errors
  2642. GROK_OPEN_SOURCE_WORKER_FORBIDDEN_PHRASES = {
  2643. "docs/elves/learnings.md": [
  2644. "use permitted Grok Composer 2.5 Fast for regular clear work",
  2645. "resume, `/goal`, streaming JSON",
  2646. ],
  2647. }
  2648. WORKER_CONFIDENCE_SIGNAL_PHRASES = {
  2649. "SKILL.md": [
  2650. "**Confidence trailer**",
  2651. "`Confidence: <level>` alone when `unsure_about` is empty",
  2652. "never a lazy default",
  2653. "flagged `unsure_about` areas get a deeper pass",
  2654. "it does not skip gates or waive review in either direction",
  2655. "`review_context.review_prompt_block`",
  2656. "**Confidence-Guided Review**",
  2657. "Claude Code and Codex use this identical contract",
  2658. ],
  2659. "references/review-subagent.md": [
  2660. "## Worker confidence triage (read before the diff):",
  2661. "An empty `unsure_about` list is a valid, complete answer",
  2662. "The signal is triage only, never authority",
  2663. "calibration observation to note in the report, not a violation",
  2664. "The coordinator **must attach that",
  2665. "block verbatim** to the primary Final Readiness prompt",
  2666. "### Confidence-Guided Review",
  2667. "Claude Code and Codex follow the same rule and prompt shape",
  2668. ],
  2669. "references/host-parity.md": [
  2670. "`elves-worker-confidence-review-v1`",
  2671. "attach its `review_prompt_block` verbatim",
  2672. "confidence to reduce review or gates",
  2673. ],
  2674. "README.md": [
  2675. "Worker confidence now actively guides the primary review on both Claude Code and Codex",
  2676. "Missing signals fall back to the full baseline review",
  2677. "high confidence never reduces gates or",
  2678. "review scope",
  2679. ],
  2680. "guide/index.html": [
  2681. "Worker confidence actively guides that review on both Claude Code and Codex",
  2682. "Missing signals",
  2683. "high confidence never removes a gate or review step",
  2684. ],
  2685. "scripts/cobbler_agents.py": [
  2686. 'review_context.get("review_prompt_block")',
  2687. 'print(review_context["review_prompt_block"])',
  2688. ],
  2689. "scripts/cobbler_runtime/full_run.py": [
  2690. '"schema": "elves-worker-confidence-review-v1"',
  2691. '"confidence_can_reduce_scope": False',
  2692. '"flagged_areas_require_deeper_pass": True',
  2693. '"missing_signal_falls_back_to_full_review": True',
  2694. ],
  2695. "references/grok-implementer-launch-prompt.md": [
  2696. "**worker confidence signal**",
  2697. "an empty list means \"I verified everything I touched and have no reservations,\"",
  2698. "review triage only, never authority",
  2699. "include your confidence (high | medium | low) and any areas you were unsure about, if any",
  2700. ],
  2701. "references/survival-guide-template.md": [
  2702. "The packet also carries the confidence-reporting requirement:",
  2703. "empty list is a valid, complete answer; triage signal only, never authority.",
  2704. ],
  2705. "CHANGELOG.md": [
  2706. "Worker confidence signal (audit B5)",
  2707. "never a lazy default",
  2708. "review triage only, never authority",
  2709. ],
  2710. }
  2711. PARALLELVES_CONTRACT_PHRASES = {
  2712. "references/parallelves.md": [
  2713. "not a runtime scheduler, and not an authority change",
  2714. "exactly one coordination hierarchy: Cobbler routes lanes the way it already routes",
  2715. "Cobbler lenses are read-only responders; Parallelves lanes",
  2716. "is shared; the authority model is not. Lanes never gain merge, PR, or protected-ref authority.",
  2717. "Serial remains the default everywhere.",
  2718. "`auto` may only recommend lanes when every",
  2719. "Nothing auto-launches.",
  2720. "no sentence in this contract claims a runtime lane orchestrator, and none exists",
  2721. "`parallel_declined:<gate>:<detail>` reason, recorded as provenance.",
  2722. "`parallel_declined:worker_dominance:no_recorded_timings`",
  2723. "in a driver-owned order, and produces one PR for the whole run.",
  2724. "composes existing per-session worker runs (native or trusted full-run), one\nper lane, per each host's documented grammar",
  2725. "The cross-lane entropy review is mandatory before the integration PR is review-ready.",
  2726. "Per-lane confidence signals order the",
  2727. "Going parallel is a reversible bet.",
  2728. "most one lane's result lands.",
  2729. "`off` (default) | `auto`. `auto` is recommend-only and",
  2730. "2-3 lanes maximum in v1",
  2731. "Automatic required-mode",
  2732. "Runtime lane supervision is explicitly future work and ships in no v1 batch.",
  2733. ],
  2734. "references/glossary.md": [
  2735. "default, recommend-only `auto`, no runtime orchestrator, no authority change",
  2736. "feature branch on pairwise-disjoint owned surfaces, under the existing worker authority model.",
  2737. "a serial batch that builds shared foundations before lanes fork",
  2738. "per-lane review structurally cannot see.",
  2739. "budget, risk posture) that must pass before `auto` may recommend lanes",
  2740. "judges, and at most one lane's result lands.",
  2741. "the width test records for every declined gate; parallelism is never silently withheld.",
  2742. ],
  2743. "AGENTS.md": [
  2744. "**Parallel lanes (Parallelves):** serial default; `worker.parallel=auto` is recommend-only and\n nothing auto-launches",
  2745. ],
  2746. "guide/index.html": [
  2747. "Serial stays the default.",
  2748. "<code>auto</code> only recommends lanes when a deterministic width test passes. Nothing\n launches lanes automatically",
  2749. ],
  2750. "README.md": [
  2751. "serial default, recommend-only width test, trunk -> lanes -> integration",
  2752. "serial stays the default, and\n`worker.parallel=auto` only recommends lanes when the deterministic width test passes",
  2753. ],
  2754. "SKILL.md": [
  2755. "parallel lanes are an earned\nrouting outcome, never a mode switch",
  2756. "`worker.parallel=auto` may only recommend lanes, every decline records a\nconcrete `parallel_declined:<gate>:<detail>` reason, and nothing auto-launches",
  2757. "mandatory cross-lane entropy review",
  2758. ],
  2759. "references/review-subagent.md": [
  2760. "this cross-lane pass is mandatory\nbefore the integration PR is review-ready",
  2761. "the cumulative integration diff, every\nlane's per-lane review record, and every lane's confidence signals",
  2762. "cross-lane question classes that per-lane review structurally cannot see",
  2763. "**Duplicated helpers across lanes**",
  2764. "**Convention divergence**",
  2765. "**Conflicting approaches to shared concerns**",
  2766. "low-confidence lanes and\nflagged `unsure_about` areas are reviewed first",
  2767. "calibration observation to note in the report, not a violation; the signal remains\ntriage only, never authority",
  2768. ],
  2769. "references/host-parity.md": [
  2770. "identical semantics on Claude Code and\nCodex: serial default, recommend-only `auto`",
  2771. "The lanes tooling is\ndeterministic and host-neutral; both hosts invoke it the same way",
  2772. "Per-lane worker launches introduce no new invocation grammar",
  2773. "same subscription-native default and optional-provider rules as any worker",
  2774. "nothing in\nthis section launches lanes at runtime",
  2775. ],
  2776. "references/schema-and-acceptance.md": [
  2777. "advisory in v1, exactly like the pre-handoff-v1",
  2778. "records lane state for recovery and does not validate it",
  2779. "plus the runtime fields `branch`, `worktree`, `session_id`, and `status`",
  2780. "A session without\n`lanes` is serial (the default).",
  2781. "Declaring `lanes` launches nothing and grants nothing",
  2782. ],
  2783. "CHANGELOG.md": [
  2784. "Serial remains the default everywhere; there is no runtime lane\n orchestrator in v1 and no sentence claims one.",
  2785. "The test is recommend-only; every declined gate records a concrete\n `parallel_declined:<gate>:<detail>` reason, and nothing auto-launches.",
  2786. ],
  2787. "references/plan-template.md": [
  2788. "Omitting this section means serial (the default).",
  2789. "`owned_surfaces`, and `batches`, plus a `trunk:` batch list built serially before lanes fork.",
  2790. "Declaring lanes never launches anything: `worker.parallel=auto` may only recommend them when",
  2791. "the width test passes, and every decline records a concrete reason.",
  2792. ],
  2793. }
  2794. # Read-only review snapshots omit oversized binary media; every other category still
  2795. # fails closed. Restating surfaces must not drift into "raise the limit" or
  2796. # "skip the review" wording.
  2797. REVIEW_SNAPSHOT_MEDIA_PHRASES = {
  2798. label: [
  2799. "omit oversized binary media",
  2800. "16 MiB per-file limit is not raised",
  2801. "derived text, image, or transcript artifact",
  2802. ]
  2803. 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']
  2804. }
  2805. REVIEW_SNAPSHOT_MEDIA_FORBIDDEN_PHRASES = {
  2806. label: [
  2807. "raise the 16 MiB",
  2808. "raises the per-file limit",
  2809. ]
  2810. 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']
  2811. }
  2812. # Fugu is one optional review route. Restating surfaces must keep the reroute,
  2813. # the recorded route triple, and the no-false-claim rule together.
  2814. REVIEW_ROUTE_FALLBACK_PHRASES = {
  2815. label: [
  2816. "quota, authentication, catalog, runner, timeout, or provider failure",
  2817. "requested route, actual route, and fallback reason",
  2818. "review-route",
  2819. ]
  2820. 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']
  2821. }
  2822. REVIEW_ROUTE_FALLBACK_FORBIDDEN_PHRASES = {
  2823. label: [
  2824. "Fugu is required",
  2825. "blocks the run when Fugu",
  2826. ]
  2827. 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']
  2828. }
  2829. # The Grok runner follows the installed CLI's advertised flags. Restating
  2830. # surfaces must keep the fail-closed safety set, the config-key auto-update
  2831. # replacement, and the catalog-bound model rule together, and must not claim a
  2832. # flag the runner no longer hardcodes.
  2833. GROK_LAUNCH_SURFACE_PHRASES = {
  2834. label: [
  2835. "flags the installed Grok Build CLI advertises"
  2836. if label != "guide/index.html"
  2837. else "flags the installed CLI advertises",
  2838. "fails closed",
  2839. "auto_update",
  2840. "authenticated live catalog lists it",
  2841. "cannot nest sandboxes",
  2842. "outer boundary is not optional",
  2843. ]
  2844. for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'guide/index.html', 'references/provider-shortcuts.md', 'aliases/claude/grok/SKILL.md']
  2845. }
  2846. GROK_LAUNCH_SURFACE_FORBIDDEN_PHRASES = {
  2847. label: [
  2848. "self-checking",
  2849. "always passes --check",
  2850. ]
  2851. for label in ['SKILL.md', 'AGENTS.md', 'README.md', 'guide/index.html', 'references/provider-shortcuts.md', 'aliases/claude/grok/SKILL.md']
  2852. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.