AGENTS.md · diff
git:20260923.23319ec to git:20261001.5aa7b24
89 added, 81 removed. Audit A to A.
- # Agent operating contract — iterion
+ # iterion — agent instructions
- This file is the **single source** for the cross-agent working methodology on
- iterion. Every **interactive agent session** (Claude Code, Codex, pi, or any
- other harness driven by an operator) follows it. **Automated bot runs**
- (iterion-launched campaign/review/fixer bots executing on this repo) are out
- of scope: they follow their own mission contract and MUST NOT attempt the
- board rituals below — no claiming, no ticket creation; their `.bot` mission
- is their ticket. [CLAUDE.md](CLAUDE.md) is the router — project stance, the
- before-merge contract, build commands — and it routes to the engineering
- reference, which lives one level down in the doctrine tree at
- [docs/agents/](docs/agents/README.md) (architecture, DSL, backends, bot
- authoring, testing, runbooks), read on demand. Read CLAUDE.md before touching
- code, and open the tree page your task names; this file only carries the
- work-tracking contract, so it stays cheap to inject.
+ iterion: build, run and orchestrate agentic AI workflows, written in a DSL —
+ `.bot` files ([`pkg/dsl/workflowfile`](pkg/dsl/workflowfile/workflowfile.go)
+ owns the accepted extension) and `.botz` bundles. Go module
+ `github.com/SocialGouv/iterion`, MIT. This is the one instruction file every
+ session loads — Codex and pi natively, Claude Code through `CLAUDE.md`.
+ Everything else is read on demand from [the tree](docs/agents/README.md): open
+ the page your task names before you start. Automated bot runs follow their
+ `.bot` mission and never claim or open board tickets (**Work tracking** is for
+ interactive sessions).
- ## Work tracking & session methodology — the GitHub board
+ ## Find before you read
- **The [Iterion project board](https://github.com/orgs/SocialGouv/projects/203)
- is the truth for ongoing work.** Every non-trivial task — engine, bots,
- cloud/ops, studio, docs — is a GitHub issue on that board, whatever workspace
- it executes in (this repo, a sibling lab, a prod incident). Statuses:
- Inbox → Planned → In progress → Blocked → Done; fields `Area` and `Mode`
- (planned dev mode: `dogfood` vs `direct`). The iterion **native board** is NOT
- replaced: it stays the bots' operational surface (auto-triage, dispatch);
- the GitHub board is the roadmap/chantier view. An `iterion issue import`
- mirror (GitHub → native, one-way idempotent) can bridge the two when a
- ticket should be dispatched to a bot.
+ - **Exact** — where is X, who implements Y, what breaks if Z changes, A→B,
+ which bot or skill: `iterion map find|neighbours|impact|path`, or the
+ `local_map_*` tools of the iterion MCP server (`engine` in this repo's
+ `.mcp.json`); committed indexes in [`docs/references/`](docs/references/map-packages.md).
+ - **Semantic** — how does X work, which docs explain this code: graphify when
+ `graphify-out/` exists (MCP `query_graph`, CLI `graphify query "<q>"`) —
+ operator-local, so check its commit against HEAD ([graph](docs/agents/graphify.md)).
+ - Then read the few files they name.
- **Every ticket lives under an epic.** The board is organised by **`epic:`
- issues** — one per chantier, carrying its own state of play, its acquis and
- its open sub-issues. A ticket belongs to its epic **twice**: as a **sub-issue**
- (the authority) and through the **`Epic` field** (the projection the views
- need — a board column accepts a single-select, never "Parent issue"). A new
- ticket gets both, and `task board:epics:sync` says so. `epic:` is an
- *objective container*; a multi-page specification is a **`design:`** ticket
- that an epic consumes. Mechanics, views and the one step the API cannot do:
- [docs/board-epics.md](docs/board-epics.md). How proven each surface actually
- is — the repo-side twin of the epics: [docs/state-of-the-art.md](docs/state-of-the-art.md).
+ ## Setup and the gate you owe
- A work session on iterion follows three phases:
+ - Tooling comes from devbox, never the host: `devbox run -- task <name>` (or
+ direnv); `task` lists every command ([development](docs/development.md)).
+ CLI map: [cli-reference](docs/cli-reference.md), [cloud-cli](docs/cloud-cli.md).
+ - `task check` — lint and the free deterministic layer (tests, goldens, studio,
+ pi extension, brand, DSL and map checks) — is owed by every session; CI also
+ runs `race`, `vendor-check` and `mongo-conformance`. The `live` layer costs
+ real LLM money and no CI job runs it: use it only when a real model alone can
+ prove the change, and say which target and what it cost ([proof discipline](docs/agents/testing.md#the-proof-discipline)).
- **Phase A — plan & align (start of session).** Read the board, triage the
- Inbox, make the statuses true, pick or confirm the session's ticket. Start
- from the **🎯 Epics** view rather than the flat Kanban: it says where each
- objective stands, which is what picking work needs. Work discovered
- mid-session becomes a new issue **under an epic**, not a side quest.
+ ## Non-negotiables
- **Claim before work (multi-session rule).** Several agent sessions (Claude
- Code, Codex, others) often run in parallel on iterion. A session *claims*
- its ticket before coding: Status → In progress + a timestamped "claimed"
- comment naming the session. Never touch a ticket already claimed by another
- session without the operator's arbitration. Release the claim at session
- end: Done with evidence, or back to Planned with a state-of-work comment.
+ - **Review loop.** Every change lands through a PR whose `revi/review` gate is
+ green. Run a local adversarial round on the diff before every push: the
+ findings decide the next round, the diff size caps the budget, you fix the
+ findings (by hand or through another round), and commits that ship reviewed
+ work carry `Adversarial-Rounds:` / `Adversarial-Model:` trailers ([the loop](docs/agents/adversarial-review-loop.md),
+ [merge and gate](docs/agents/review-and-merge.md)).
+ - **Do not comment `/billy`** — the fixer is paused on this repo
+ ([why, and the re-arm](docs/agents/review-and-merge.md#billy-is-paused)).
+ - **Never hand-edit `CHANGELOG.md`.** Bump `claw-code-go` only with
+ `scripts/bump-claw.sh`; it is first-party — improve it in its `.works/`
+ worktree when a seam crosses it, then bump.
+ - **`.bot` traps.** A tool node's `command:` runs under `bash -c`; a `script:`
+ with `language: sh` runs `sh`, so keep it POSIX ([pitfalls](docs/workflow_authoring_pitfalls.md#shell-portability-for-tool-nodes)).
+ A literal `{{` in a template is `{{"{{"}}` ([delimiters](docs/dsl.md#literal-template-delimiters)).
+ - **Conventions.** Tests: the standard `testing` package. CLI: Cobra, one file
+ per command in `cmd/iterion/`, output through `Printer` (`pkg/cli/output.go`).
+ Logs: `pkg/log`. Error tracking and tracing: extend `pkg/errtrack`, never a
+ second tracker. Run state lives in `.iterion/`.
+ - **Pay discoveries back.** Time spent finding out how something works lands in
+ the tree: the content in its page, one line in that page's index. A paragraph
+ that would grow this file belongs in the tree.
- **Phase B — dev, mode chosen per ticket.** *Dogfood-first reflex*: before
- implementing by hand, ask "can a catalog bot do this work?" — if yes,
- propose launching it (visible in the operator's studio, actively monitored,
- bilan in `docs/bot-runs/`), and improve the bot on every friction the run
- surfaces. Propose this mode regularly; don't impose it. Otherwise *direct
- dev*: a normal coding session. Either way the existing contracts apply
- (the before-merge review loop, commit scope discipline, bilans).
+ ## Philosophy — [long form](docs/philosophy.md), read it before arguing with a rule
- **Phase C — close with evidence.** The issue closes with a link to the
- PR/commit/bilan that proves the work; board status updated before the
- session ends. A ticket that says In progress with nobody on it is a bug
- in the board — fix it when you see it.
+ 1. **Maximum power, no artificial limit.** A bound with no override is a
+ defect; a load-bearing limit keeps a greppable escape hatch; warn (C1xx)
+ rather than reject; never silently replace an operator's explicit choice.
+ 2. **Modularity — the Nth-variant test.** A new capability implements an
+ existing seam (`NodeExecutor`, `delegate.Backend`, `tracker.Tracker`,
+ `pkg/forge`, `eventbus.Bus`, …); if the next variant would need an engine
+ `if`, build the seam.
+ 3. **Cloud-native.** The same code runs single-process and multi-replica:
+ elected ownership, restart is normal, idempotent reconciliation; new
+ durable state ships its cloud twin in the same change.
+ 4. **Git-native first** — the `.bot` as text, `worktree: auto`, the review
+ scope, the forge gate: never degraded; where git cannot serve, add a
+ parallel mechanism.
+ 5. **Views are additive** — read models over execution and git, never a
+ second source of truth.
- **Before merge, the review loop is required.** A change reaches `main`
- through a PR whose `revi/review` gate is green (admins, and the release
- bot, may bypass), and the gate is not the first reviewer: run a **local
- adversarial round on the diff before pushing** — a subagent whose posture is to break the change, with every
- finding *and every fix it proposes* verified before a line is written.
- The gate closes the loop; a sterile local round only means "time to
- push". A feature is delivered *through* that loop — plan review upstream
- by another model family, a round per slice, a round on the whole diff
- before the push — not reviewed once at the end. Findings are the
- developer's to fix, by hand or through another local round — **`/billy`
- is paused on this repo** (cost, until the team spends its own BYOK key).
- What decides another round is the findings, not a counter: while rounds
- keep returning verified high/critical, keep going. The budget is a
- **ceiling on cost, not a target** (≤ 8 changed files → 5 local rounds,
- 10 if the diff blocks — hook/lint/guard/filter · 9–25 → 20 · > 25 → 50),
- because a local round is paid by your own plan and a gate cycle by the
- shared credential. Every commit **that ships reviewed work** then says
- what the review cost — `Adversarial-Rounds:` and `Adversarial-Model:`
- trailers, `0 (trivial: …)` written explicitly rather than omitted.
- Protocol:
- [docs/agents/adversarial-review-loop.md](docs/agents/adversarial-review-loop.md);
- gate and merge mechanics:
- [docs/agents/review-and-merge.md](docs/agents/review-and-merge.md).
+ **Backend parity:** `claw` ↔ `claude_code` are interchangeable on a node; a
+ capability wired for one is wired, or typed-refused, for the other.
+
+ ## Work tracking — interactive sessions
+
+ The [project board](https://github.com/orgs/SocialGouv/projects/203) is the
+ truth for ongoing work: every non-trivial task is an issue under an `epic:`,
+ as a sub-issue **and** through the `Epic` field ([mechanics](docs/board-epics.md)).
+
+ - **A — plan.** Start from the 🎯 Epics view, triage the Inbox, make statuses
+ true, pick the session's ticket and **claim** it (In progress + a timestamped
+ "claimed" comment naming the session). Never touch a ticket another session
+ claimed without the operator's arbitration. Work found mid-session becomes an
+ issue under an epic.
+ - **B — dev.** First ask whether a catalog bot can do it and propose that
+ ([dogfood](docs/agents/dogfood.md)), never impose it; otherwise code directly.
+ - **C — close.** Link the evidence (PR, commit, bilan), update the status and
+ release the claim: Done, or Planned with a state-of-work comment. An In
+ progress ticket nobody holds is a board bug — fix it.
+
+ ## The tree
+
+ [docs/agents/](docs/agents/README.md) — one line per page, with when to read it.