AGENTS.md · diff

git:20260915.be55715 to git:20260922.60b8983

55 added, 95 removed. Audit A to A.

- # Working on Foreman

- These are Foreman's contributor rules. Claude Code reads the same rules from

- `.claude/rules/`; when one changes, change both copies together. The Foundry

- roadmap rule is copied word for word from Foundry's

- `.claude/rules/project-roadmap.md`.

- ## One package for Claude Code and Codex

- `main` is Foreman's package branch: one plugin for Claude Code and Codex. It is

- not documentation-only. Make changes on a topic branch and merge them into

- `main` through a pull request. The separate releases ended with 2.7.0 and

- 3.0.4-codex.1, and their `Claude` and `Codex` branches were deleted on

- 2026-09-15. This repository is Foundry's Foreman submodule.

- Keep one runtime, one `skills/` tree with the five skills, one

- `prompt-template.md`, one README and one CHANGELOG. Claude Code reads

- `.claude-plugin/plugin.json` and `hooks/hooks.json`. Codex reads

- `.codex-plugin/plugin.json`, whose `hooks` field names `hooks/codex-hooks.json`.

- Register each host's events only in its own hook file. Code that behaves

- differently per host asks `scripts/runtime.js` which host is running; handoff

- wording that differs per host is a `host="claude"` or `host="codex"` block in

- `prompt-template.md`. Use each host's actual capabilities and document gaps

- instead of inventing tool APIs or lifecycle events. Inherit the executing model

- unless the user chooses one.

+ # Foreman

- Reviewed increments stay a Codex feature until the owner decides otherwise.

- The shared assembler accepts review rows on both hosts, but Claude Code's

- skills do not offer the protocol, and the documentation says it is not

- available in Claude Code yet.

+ Foreman is one plugin for Claude Code, Codex and Antigravity: a roadmap beside the project's

+ code, grounded handoffs and clear task status. Its hooks, scripts and tests are dependency-free Node.js and run

+ with Node.js 22 or later and Git; there is no install or build step. This repository is

+ Foundry's Foreman submodule and ships from `main`.

- Preserve roadmap format 2 and records written by either host. Keep scripts

- dependency-free Node.js. One version covers both hosts: bump it in both

- `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` in the release

- commit, and a test keeps the two equal. Foundry's catalogs carry no version for

- Foreman; both pin the same `main` commit, and a release only moves their

- `source.sha`.

+ ## Start here

- Run `node --test tests/*.test.js` for runtime changes, and exercise changed

- hooks on Windows as well as Unix. Validate the manifests and edited skills with

- each host's validator when it is available. Do not install the plugin, alter a

- marketplace or start model sessions as a side effect of running tests.

+ - Before changing what Foreman promises or refuses, read [the product scope](docs/knowledge/scope.md); the README's never-list must agree with it.

+ - Before touching reviewed increments, read [incremental acceptance](docs/knowledge/incremental-acceptance.md); the protocol is Codex-only.

+ - Before editing a handoff block, read `prompt-template.md`; `check-prompt.js` and `craft-handoff.js` read its canonical blocks at run time.

+ - Before a release, read [the changelog](docs/knowledge/changelog.md) and [CONTRIBUTING.md](CONTRIBUTING.md).

- ## One roadmap for Foundry development

+ ## Rules that outrank everything

- Development of this Foundry collection uses the parent Foundry ROADMAP.jsonl.

- Do not create or maintain a separate project roadmap inside foreman, hush,

- razor or their platform worktrees. Run roadmap commands from Foundry and ensure

- any host project-directory override points at that same root. Plugin tests and

- source commands can still run from their own checkout.

+ - One package on `main` serves the three hosts: one runtime, one `skills/` tree with the five skills, one `prompt-template.md`, one README and one changelog. Develop on a topic branch and merge through a pull request.

+ - Register Claude Code events only in `hooks/hooks.json`, Codex events only in `hooks/codex-hooks.json` and Antigravity events only in the root `hooks.json`, which runs `hooks/antigravity-hook.js`. Host-specific code asks `scripts/runtime.js` which host is running; host-specific handoff wording is a `host="claude"` or `host="codex"` block in `prompt-template.md`, and an Antigravity handoff takes the Codex form.

+ - The three manifests, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json` and `plugin.json`, carry the same version, bumped together in the release commit; a test fails when they differ. Foundry's catalogs carry no version for Foreman and only move `source.sha`.

- Version Foundry's root ROADMAP.jsonl and its .foreman/config.json,

- .foreman/notes.jsonl and .foreman/archive.jsonl when present. These preserve

- planning, shared settings, lessons and archived task history in a fresh clone.

- Trial logs, session markers, locks and temporary execution state remain local.

- Do not publish an entire .foreman directory by removing its exclusions.

+ ## Commands

- This governs maintenance of the collection, not the unrelated user projects

- where a plugin is installed. Test fixtures and archival backups are not active

- project roadmaps. Do not change the plugin's general project-resolution behavior

- to force all installations to use a particular Foundry checkout.

+ | Command | Purpose | Cost |

+ | --- | --- | --- |

+ | `node --test tests/*.test.js` | The suite, three hosts | Local temporary repositories; exercise changed hooks on Windows as well as Unix |

+ | `node scripts/git-hooks/check-readme-nav.js README.md` | Every README nav anchor resolves | Local |

+ | `claude plugin validate .` | Claude Code package shape | Local |

+ | `agy plugin validate .` | Antigravity package shape | Local; needs the Antigravity CLI |

+ | `node scripts/build-windows-launchers.js` | Codex Windows hook commands are current; `--write` regenerates them | Local |

+ | `git config core.hooksPath scripts/git-hooks` | One-time: the pre-commit hook runs the suite and the nav check | Local |

- Before importing work, compare identities, dependencies and history. Keep

- existing Foundry IDs; preserve free source IDs and remap collisions with an

- explicit provenance map. Preserve dates, notes and acceptance state. Related

- work on another platform does not establish completion of an existing task.

+ Codex validators live in the Codex installation, not here. Tests never install the plugin,

+ alter a marketplace or start model sessions.

- The former Foreman-local IDs 294–300 map to Foundry 302–308. ID 301 is unchanged;

- read its current status from the root roadmap. Historical notes retain their original local

- IDs, interpreted through docs/shared/validation/roadmap-reconciliation-2026-09-08.md.

+ ## Where things live

- ## Benchmark ownership in Foundry

+ | Path | Content |

+ | --- | --- |

+ | `skills/` | The five skills, one text for every host: `foreman`, `roadmap`, `init`, `survey`, `craft-prompt` |

+ | `hooks/` | Hook scripts and the Claude Code and Codex registrations; `antigravity-hook.js` translates Antigravity's events and runs the shared hooks as children; `lib.js` resolves project and host; `windows-launcher.ps1` is the source of the Codex Windows command |

+ | `scripts/` | Dependency-free CLIs such as `roadmap.js`, `craft-handoff.js`, `check-prompt.js`, `safe-commit.js` and `ledger.js`; `health/` holds the metrics tools |

+ | `tests/` | The `node:test` suite for the three hosts |

+ | `prompt-template.md` | The one handoff template, read at run time |

+ | `HOW-IT-WORKS.md`, `settings.md`, `roadmap-schema.md`, `ledger.md`, `TRIALS.md`, `CODEX.md`, `CODEX-PROMPTING.md` | Reference pages the skills, scripts and tests load or cite; they stay at the root |

+ | `docs/knowledge/` | The product scope, the incremental-acceptance contract and the changelog |

+ | `.claude-plugin/`, `.codex-plugin/`, `plugin.json`, `hooks.json` | Host manifests with the same version; the Codex manifest names `hooks/codex-hooks.json`, and the root manifest and `hooks.json` are what Antigravity reads |

- Keep benchmark runners, datasets, measurement tests and experiments in the

- parent Foundry `benchmarks/<plugin>/` directory. Do not add a benchmark tree to

- the installable plugin or recreate the old `.benchmarks/` directory.

+ ## Conventions

- Plugin `tests/` contains functional tests of the product. Tests of a benchmark

- runner, scorer or evidence schema belong beside that harness in Foundry.

- Preserve existing test coverage when moving a harness.

+ The README serves every host. Its shared sections read the same for everyone; host differences

+ sit in the How to ask table, one Get started subsection per host, the Differences between hosts

+ table and one results table per host under The numbers. A feature one host lacks is named as not

+ available there, never described with the other host's behavior. Keep benchmark questions and

+ columns identical across the host tables; each table carries its own `foundry:evidence`

+ declaration, model, source and date. Never present a Claude Code result as a Codex result, never

+ treat unit tests as a performance run, and show `Not measured` where evidence is absent.

- Use `.scratch/` for local maintenance output, migration backups and temporary

- validation dependencies. Research narratives belong in `docs/<plugin>/`.

- Keep model names, revisions and historical results attached to their actual

- experiments. Organization work does not authorize paid runs or global installs.

+ Reviewed increments stay a Codex feature until the owner decides otherwise: the assembler

+ accepts review rows on both hosts, but Claude Code's skills do not offer the protocol.

- ## One README for both hosts

+ Preserve roadmap format 2 and records written by either host. Keep scripts dependency-free.

+ Benchmark runners, datasets and experiments are not part of the package; `tests/` holds

+ functional tests only.

- Foreman has one README, on `main`, for Claude Code and Codex users alike. Its

- shared product sections — What is this?, Why you'd want it, How it works, What

- you can do and Good to know — stay outside host-specific parts and read the

- same for everyone. Host differences have fixed places: the How to ask table,

- one Get started subsection per host, the Differences between hosts table and

- one results table per host under The numbers. A feature one host lacks is named

- as not available there, never described with the other host's behavior.

+ `CLAUDE.md` imports this file; keep shared contributor facts here.

- Keep benchmark questions, metrics and table columns identical in both host

- tables. Each table carries its own `foundry:evidence` declaration and its own

- model and setup rows, values and limits. Identify the actual host, model,

- source and date. Preserve losses and measurement limits. Never turn a Claude

- Code result into a Codex result by moving it or renaming a model, and never

- treat unit tests as a comparative performance run. Show `Not measured` when

- equivalent evidence is absent. Research and extensive methodology belong in

- Foundry's central documentation; product usage and plugin decisions belong

- with the plugin.

+ ## Pitfalls

- The short never-list under Good to know must agree with `docs/adr/SCOPE.md`.

- Before considering a README change ready, check navigation with

- `node scripts/git-hooks/check-readme-nav.js` and review the source of every

- claim; a passing check verifies anchors, not measurements. Do not run paid

- benchmarks, install plugins, publish or create commits merely to fill an

- evidence gap.

+ - **Claude Code substitutes `${CLAUDE_PLUGIN_ROOT}` in skill text; Codex does not.** Skills carry a relative link beside each such path.

+ - **A passing nav check verifies anchors, not measurements.** Review the source of every README claim; never run paid benchmarks, install plugins or publish to fill an evidence gap.

+ - **A prompt copied out of one host carries that host's script paths.** Craft it again in the other.

+ - **Antigravity's PostToolUse answer is always `{}`.** What a commit or a file touch has to say waits in a temp queue and reaches the model at its next call, through PreInvocation; nothing arrives at the moment of the command.