Repository Instructions And Sibling Coherence

AGENTS.md is Wavemap’s root instruction contract for repository-aware agents. It is deliberately broader than a style guide: it records the collaboration mode, authority boundaries, evidence standard, implementation conventions, verification discipline, roadmap synchronization, docs graduation, and the shape of a credible handoff.

Codex reads project instructions when it enters a trusted repository. .codex/config.toml reserves a larger project_doc_max_bytes budget so the complete contract is discoverable, but the file is kept concise by routing detail into ledgers and curated docs. Increasing the byte budget is a safety margin, not permission to turn AGENTS.md into an encyclopedia.

Wavemap’s Contract

The most important Wavemap-specific expectations are:

• Deliberate collaboration is the default. Consequential architecture, public API, dependency, deployment, auth, security, and cross-package choices are discussed before implementation.
• Agentic execution is goal-bounded. An accepted plan can authorize a narrow implementation and commit cadence. The bound comes from the accepted outcome and scope rather than a hard commit count: roughly five commits is a useful reassessment point, while a longer methodical chain can remain coherent. This never erases human gates around pull requests, merges, deployment, cloud state, or external communication.
• Work passes reorient. Long discussion, another roadmap phase, compaction, resume, branch changes, and fuzzy memory trigger evidence recovery before editing.
• The closest implemented analogue is required evidence. Before consequential architecture or roadmap advice, inspect the analogue’s relevant end-to-end layers and name what should be reused, what is a limitation, and why any divergence is intentional. Record a supported no-analogue finding instead of assuming novelty.
• Reference-led propagation has a proof boundary. Reference-led passes declare every quality dimension and checkpoint one bounded representative slice before copying its pattern. Front-end form families additionally declare the mature form architecture so state ownership, validation, accessibility, collection identity, and draft persistence cannot be replaced by an ad hoc parallel implementation.
• Implementation conventions are literal. Types belong in type modules, string sets use named constants and derived unions, object fields are destructured when consumed locally, and ownership follows the live package/app shape.
• Verification is proportional. Planning and recommendation run no verification. Implementation starts targeted; broader or DB-backed suites require an exact, already-authorized command and remain auditable through interruption.
• Roadmaps stay synchronized. Completed work and changed decisions are recorded during the pass.
• Knowledge graduates. Stable explanations move from working notes into the curated docs site.

More-specific AGENTS.md files can refine the contract for a nested directory. An agent must read every applicable file for the path it changes; a child instruction file does not cancel the root human boundaries unless it says so explicitly and is itself authorized repository policy.

The Evidence Ledger

.agents/work-pass-ledger.md turns broad advice into a topic router. A persistence change should lead to schema, migrations, queries, adapters, handlers, route-contract tests, and DB-backed tests where those layers exist. A front-end route change should lead to server routing, guards, hydration, client state, styling, i18n, and integration evidence.

This protects against a common failure mode: an agent reads one plausible file, reproduces its local appearance, and calls the subsystem aligned. Closure words such as complete, swept, matches, parity, and ready are reserved for the declared inventory, not the confidence of the prose.

For a consequential recommendation, the inventory must include the closest implemented analogue across the contract, persistence, server, frontend, and test layers that exist for that behavior. The resulting recommendation distinguishes reusable invariants from compromises that should not become precedent and records every intentional divergence. The receipt lists evidence paths; the active plan or work update carries that reasoning.

When adding a durable architecture or workflow convention:

1. Put the enforceable rule in code, config, or tests where possible.
2. Teach the concept in graduated docs.
3. Add a concise routing or boundary rule to AGENTS.md only when agents must always encounter it.
4. Add topic-specific evidence to the ledger rather than repeating a whole guide in AGENTS.md.
5. Update the skill or hook only when the procedure or runtime state machine changes.

Wavemap And Waveguide

The sibling contract lives at .agents/sibling-architecture.md. Equivalent surfaces should remain coherent, but product needs can justify differences. Each meaningful difference is classified as:

• A shared invariant that should align.
• A product-specific implementation of the same goal.
• An intentional architectural divergence with a documented reason.
• A migration gap between adoption stages.
• Not applicable to one product.
• Unknown until more evidence is gathered.

The generic work-pass skill, hooks, tests, and read-only role definitions are intended to remain byte-identical. The repositories’ AGENTS.md, ledgers, roadmaps, commands, domain code, and teaching docs are intentionally product-specific.

Run the generic comparison from either sibling with an explicit path:

node .agents/skills/govern-work-pass/scripts/work-pass.mjs verify-sibling --sibling <sibling-checkout>

A missing private Waveguide checkout blocks a positive parity claim, not ordinary public Wavemap contribution. Never publish private Waveguide source or local filesystem details as comparison evidence.

Read-Only Custom Agents

.codex/config.toml registers two focused roles:

• architecture-explorer inventories live architecture, source patterns, tests, and unknowns.
• sibling-parity-reviewer compares both repositories and classifies differences.

Both roles run with a read-only sandbox. This is the safe first modular boundary: parallel research can reduce context pressure without allowing a child to mutate shared source. Each child must read its own assigned instructions and report exact paths. The parent’s receipt is not proof of the child’s evidence.

The current hook API can add SubagentStart context, but later tool events do not provide a stable child identity suitable for trustworthy per-child write receipts. For that reason, Wavemap does not yet register a general write-worker role. Adding one should wait for an enforceable identity, scope, review, and commit-ownership design.

Review Checklist For Agent Tooling

• Does AGENTS.md still fit its configured discovery budget and remain an entry contract rather than a duplicate manual?
• Do the ledger links and source routes exist?
• Does the skill frontmatter describe every real trigger without loading unrelated references?
• Do planning/recommendation receipts retain a none verification ceiling, and are broad implementation commands exact records of existing authority rather than agent-selected expansions?
• Are receipt files ignored and free of secrets?
• Can a stale receipt still read the skill, inspect processes, and invoke the repository’s exact refresh script through both relative and absolute paths?
• Do the curated pages match the current receipt location, retention, operating-mode, and commit-cadence behavior?
• Are hooks conservative, Git-root-relative, tested, and reviewed before trust?
• Does sibling work resolve against the target repository’s receipt and stay split into repository-local patches?
• Are custom agents no more privileged than their stated job requires?
• Does generic tooling still match Waveguide, or is a divergence documented?
• Does a reference-led implementation account for all quality dimensions, checkpoint its bounded first slice before propagation, and keep the ordinary standard profile permissive?
• Does a front-end form-family receipt name the established form library and state owner rather than allowing a native form plus parallel draft state to appear complete?
• Do the docs explain the behavior without exposing private evidence?