Agent Operating Model

This page is the day-to-day operating model for Codex, Claude, claudeu, codexu, and future backends working on Gormes.

Every substantial pass starts with a repo-local skill and ends with evidence.

Skill Selection

Use gormes-skill-manager when the correct skill is not obvious. Otherwise select the narrowest skill that matches the pass:

Do not load every skill. A good pass normally uses one skill; a complex pass uses at most three.

Planner Pass

A planner pass must:

1. name the lane and subsystem;
2. inspect upstream and current Gormes code;
3. classify gaps as covered, planned, vague, missing, or owned;
4. update docs or progress.json only where needed;
5. preserve health blocks;
6. validate docs/progress;
7. stop with a short next-builder-row list.

Planner passes do not implement runtime feature code.

gormes-planner replaces the deleted cmd/planner-loop command. During a planner-skill pass, do not recreate or invoke loop binaries. Manual repository evidence wins over stale loop assumptions.

Minimum validation:

go run ./cmd/progress validate
go test ./docs -count=1

If progress rows or generated progress docs changed:

go run ./cmd/progress write
go run ./cmd/progress validate
go test ./internal/progress -count=1

Planner output packet:

Planner passes may update generated docs only through go run ./cmd/progress write. They must not edit content between PROGRESS markers by hand.

When a planner pass adds a phase, subphase, or closure row, it must also update the hand-written planning pages that explain why the structure exists: completion-plan.md, lane-roadmap.md, and any subsystem study page that owns the new rows. A phase restructure is not complete until Hugo-generated pages and the human-readable plan tell the same story.

Builder Pass

A builder pass must:

1. select exactly one row unless the user explicitly asks for a batch;
2. restate the contract, write scope, tests, and done signal;
3. write one failing behavior test where feasible;
4. implement the smallest green path;
5. repeat vertically only while scope remains the same row;
6. run row-local commands and focused package gates;
7. update docs/progress evidence when public behavior changed.

Builder passes do not invent backlog. If a row is vague, send it back through gormes-planner.

Builder selection without loop binaries:

1. Read progress.json and the generated Agent Queue.
2. Prefer rows with fixture_ready or validated contracts, no blocked_by, non-umbrella slice_size, explicit write_scope, and test_commands.
3. Prefer Lane 1/2 closure rows unless the user names a row or a dependency requires another lane.
4. Restate the row. If the restatement cannot name behavior, tests, and done signal, stop and run gormes-planner.
5. Build one row only.

Parity Audit Pass

A parity audit pass must compare exact upstream behavior against exact Gormes evidence. It should not be a list of file names.

For each behavior, record:

• upstream path and symbol;
• Gormes package or missing package;
• tests/fixtures;
• progress row coverage;
• classification;
• recommended row if vague or missing.

Interface Design Pass

Use this before implementation when a package boundary is unclear.

Output at least two materially different designs and compare:

• caller simplicity;
• Hermes/Honcho compatibility;
• module depth;
• testability;
• migration cost;
• risk of shallow pass-through abstraction.

The result should either update a row or unblock one builder pass.

Stop Conditions

Stop and report instead of continuing when:

• validation fails for a reason outside the current pass;
• progress row scope is missing or contradictory;
• upstream behavior cannot be verified locally;
• the pass would require runtime code during a planner pass;
• the builder would need to edit outside write_scope;
• live credentials are required for row-local proof.

Evidence Format

Every final report should include:

1. skill used;
2. scope scanned;
3. files changed;
4. validation run;
5. next row or next pass;
6. blockers.

The user should be able to resume from the report without reading the entire conversation.