AGENTS.md git:20261015.e76a55fB

Immutable. This exact content never changes and is served at /api/v1/blob/bcdce54d790ab506.

# AGENTS.md

## What this repo is

A collection of **Agent Skills** (Markdown SOPs + helper Bash scripts) published
as both a Claude Code marketplace (`.claude-plugin/marketplace.json`) and a
Cursor marketplace (`.cursor-plugin/marketplace.json`). It is not a deployable
service. There are no repo-level dependency manifests (no `package.json`,
lockfile, or Makefile at the root); the toolchain — `bash`, `git`, Node.js/npm,
and `python3` 3.11+ (`tomllib`) — is expected to be preinstalled, so a startup
update script has nothing to install.

Components:

- `skills/implementation-loop/` — the backend-neutral implementation loop skill.
  Uniform backend modules live under `backends/{claude,codex,grok,cursor}/`, each with
  `dispatch.sh`, `runtime.md`, `selftest.sh`, and `fixture-driver.sh`; grok also
  has `verify-worktree.sh`. `backends/backends.tsv` registers their capabilities.
  Shared suites and the opt-in real-backend gate live under `tests/`; the frozen
  Codex matrix is `tests/codex-cases.tsv`. `scripts/run-gate.sh` remains the
  backend-neutral gate, while the other eight `scripts/*.sh` executables are
  one-release forwarding shims removed in 0.5.0. The shared observable interface
  is recorded in `references/dispatch-contract.md` and enforced by the contract
  suites. `scripts/loop-coordinator` is the foreground, headless coordinator:
  it drafts specs through a judge, records engineer approval, and performs a
  diagnostic diff review. Its operator guide is `references/coordinator.md`;
  `tests/coordinator-selftest.sh` uses temporary repositories and CLI stubs.
- `skills/engineering-mode/` — goal-first wrapper over the loop. Shared
  playbooks in `references/playbooks/`, plus `scripts/tree-oid.sh` and its
  selftest.
- `skills/web-slides/` — a scaffolder (`scripts/scaffold.sh`) that generates a
  runnable Vite + React + TypeScript slide deck. The only runnable "app".
- `cursor-implementation-loop/` — the generated Cursor plugin port. It ships
  two skills (`cursor-implementation-loop`, `cursor-engineering-mode`) and two
  agents (`agents/loop-implementer.md`, `agents/loop-independent-reviewer.md`).
  Edit shared inputs under `skills/` or Cursor-authored inputs under
  `hosts/cursor/`, then run `bash build.sh`; do not hand-edit the generated
  tree. Manifest: `.cursor-plugin/plugin.json`.
- `build.sh`, `hosts/cursor/`, `tests/build-{inventory.py,selftest.sh}` — the
  deterministic Cursor-package generator, its host-only overlay, and its
  external-inventory/selftest tooling. `bash build.sh --check` verifies the
  committed tree and its recorded version decision without rewriting it.
- `install-cursor.sh` / `install-cursor-selftest.sh` — root-level one-line
  installer for the Cursor plugin (`curl … install-cursor.sh | bash`), plus its
  own selftest.
- `plans/`, `docs/` — design plans and review records; prose only, no CI hooks.

## Invariants CI will hold you to

`.github/workflows/selftest.yml` runs two jobs. Reproduce locally from the repo
root in this order — all suites are self-contained, need no network, and the
backend CLIs are **not** required (they are only needed to dispatch a live
run):

1. `bash -n` syntax checks on every shipped shell script: the builder and its
   selftest, backend modules and fixture drivers, shared tests, the gate, all
   forwarding shims, the two generated Cursor gate scripts, and both installer
   scripts.
2. **Generated Cursor package checks:** `bash build.sh --check`, two builds into
   separate temporary destinations with byte-identical external inventories,
   then `bash tests/build-selftest.sh` (expect `selftest: PASS (21 checks)`).
   The inventory records path, type, mode, and SHA-256 independently of the
   embedded manifest. Edit `skills/` or `hosts/cursor/`, run `bash build.sh`,
   and record the version decision in `hosts/cursor/version-decision.tsv`.
3. Playbooks must stay platform-neutral: no `read-only` / `investigate` words
   and no `codex-dispatch` references anywhere under either
   `references/playbooks/` tree.
4. `bash skills/implementation-loop/backends/codex/selftest.sh` — expect
   `selftest: PASS (267 checks)`, then
   `bash skills/implementation-loop/tests/gate-selftest.sh` — expect
   `selftest: PASS (207 checks)`. Their split total is 474. The Codex cases
   use python3 for secure state, argv, and fixture validation; python3 3.11+ is
   part of the repo toolchain. The Codex suite also starts, signals, and kills
   real stub processes to cover stop signals and `--recover-stale`; it needs no
   network and no codex CLI.
5. `bash skills/implementation-loop/backends/grok/selftest.sh` — expect
   `selftest: PASS (276 checks)`.
6. `bash skills/implementation-loop/backends/cursor/selftest.sh` — expect
   `selftest: PASS (142 checks)`.
   `bash skills/implementation-loop/backends/claude/selftest.sh` — expect
   `selftest: PASS (307 checks)`.
7. `bash skills/implementation-loop/tests/journal-selftest.sh` — expect
   `selftest: PASS (268 checks)`; `bash skills/implementation-loop/tests/index-selftest.sh`
   — expect `selftest: PASS (106 checks)`;
   `bash skills/implementation-loop/tests/console-selftest.sh` — expect
   `selftest: PASS (165 checks)`; and
   `bash skills/implementation-loop/tests/calibration-selftest.sh` — expect
   `selftest: PASS (121 checks)`. The journal, console, and calibration suites
   each run `tests/link-count-cases.py`, which loads that script's Python body
   and calls its `validate_regular` directly.
8. `bash skills/implementation-loop/tests/contract-core.sh`,
   `bash skills/implementation-loop/tests/contract-negative.sh`, and
   `bash skills/implementation-loop/tests/shim-selftest.sh` — expect all green.
   The contract-core per-backend counts are claude 64, codex 66, cursor 70,
   and grok 66. Contract-negative expects
   `contract-negative: PASS (44 checks; 22 broken adapters rejected)`.
9. `bash skills/implementation-loop/tests/evidence-selftest.sh` (the
   `scripts/loop-evidence` record card) — expect `selftest: PASS (157 checks)`.
10. `bash skills/implementation-loop/tests/coordinator-selftest.sh` — expect
    `selftest: PASS (735 checks)`. It uses only local temporary repositories
    and backend CLI stubs, and never calls a real agent. `COORD_SELFTEST_JOBS`
    defaults to 4; set it to 1 for declaration-order serial execution.
11. `bash cursor-implementation-loop/skills/cursor-implementation-loop/scripts/gate-selftest.sh`
   — expect `selftest: PASS (207 checks)`.
12. `bash install-cursor-selftest.sh` — expect `selftest: PASS (64 checks)`.
13. Packaging checks: both marketplace JSON manifests must parse; every
   `SKILL.md` (under `skills/` and `cursor-implementation-loop/skills/`) must
   have non-empty `name:` and `description:` frontmatter; engineering-mode and
   Codex-loop Markdown must have no dangling relative links.
14. `tree-oid` job (runs on ubuntu **and** macos):
   `bash skills/engineering-mode/scripts/tree-oid-selftest.sh` and the
   Cursor copy — expect `selftest: PASS (202 checks)` each. Keep these scripts
   portable across GNU and BSD userlands.

## Shell gotcha: locale prefixes in forked shells

Inside `$(...)`, `( ... )`, `<( ... )`, or a function called from one of them,
write `env LC_ALL=C cmd`, never a bare `LC_ALL=C cmd` (same for `LANG` and other
`LC_*`). After a bare prefix the forked shell restores its own locale; with
Homebrew bash 5.3 on macOS and no `LANG`/`LC_*` in the environment that restore
can segfault, so the substitution returns 139 and `set -e` ends the script.
A bare prefix in a script's own main shell is safe. `env` runs external
commands only, not shell functions or builtins.

## Manual backend integration gate

`skills/implementation-loop/tests/integration-test.sh` is the manual,
opt-in pre-release gate for backend changes. It exercises the real claude, codex, grok,
and cursor-agent sandboxes, needs authenticated CLIs, and makes real API calls.
`--backend claude|grok|cursor|codex|all` is repeatable and deduplicated; `--require
codex` implies codex and fails unless every frozen non-managed Codex case runs
exactly once with no skip/failure and complete provenance. Unavailable or
logged-out backends otherwise remain skips. `--require claude` implies claude and
fails if any Claude case is skipped. CI only runs `bash -n` on this
script and never executes it.

## Running the web-slides app (non-obvious gotchas)

Scaffold, then run the Vite dev server:

```bash
cd /tmp                                   # a scratch parent dir, NOT the repo
bash <repo>/skills/web-slides/scripts/scaffold.sh ws-demo --theme=midnight-press
cd ws-demo && npm run dev                 # serves http://localhost:5174/
```

- **Pass a RELATIVE target dir and run from the intended parent.** Current
  `npm create vite` (create-vite v9+) resolves the project path against the
  cwd and mishandles a leading `/`, so an absolute target like `/tmp/ws-demo`
  gets scaffolded into `$PWD/tmp/ws-demo` and the script's later `cd` fails.
  Don't scaffold from inside the repo checkout — it would drop an untracked
  deck into the repo.
- The first `npm create vite` invocation may no-op while it downloads
  `create-vite`; if the target dir wasn't created, just re-run — the package
  is cached the second time.
- The scaffolder runs `npm install` and `npx tsc --noEmit` itself and aborts
  on type errors, so a successful scaffold already typechecks.
- Dev server port is fixed to `5174` in `templates/vite.config.ts`. In the
  deck: click the stage / `→` / space advances one step, `P` opens the
  presenter window, `N` toggles the notes overlay. List themes with
  `scaffold.sh --list-themes`; default is `midnight-press`.