Working With LLM Agents

Wavemap uses LLM agents as implementation collaborators, research accelerators, and review aids. They are useful precisely because they can traverse a large monorepo quickly, but speed does not make their working memory durable or their plausible-looking output authoritative. The repository therefore supplies an explicit orientation and verification system that helps an agent recover the same architectural context a human contributor would use.

The operating model is on the loop: a human owns product direction, taste, authority, and final judgment while an agent does bounded research or implementation. Consequential actions such as commits, pull requests, deployment, cloud changes, and external communication retain their existing human gates. An oriented work pass does not create new authority.

The Four Layers

Layer	Repository Artifact	Job
Durable contract	AGENTS.md	Defines collaboration modes, boundaries, conventions, evidence standards, and what done means.
Evidence routing	.agents/work-pass-ledger.md and .agents/sibling-architecture.md	Routes each pass to current docs, source, tests, roadmaps, and sibling comparisons.
Reusable procedure	.agents/skills/govern-work-pass/	Teaches Codex when and how to inspect, prepare, refresh, and close a pass.
Runtime guardrails	.codex/config.toml, hooks, custom agents, and ignored receipts	Detects stale context and blocks recognized writes until the current pass is READY.

Curated developer docs explain these artifacts, but the checked-in contracts and live implementation remain the source of truth. A receipt records what was inspected; it does not turn a prior summary into current evidence.

The Working Loop

1. Discuss: Clarify the outcome, risk, architectural choices, exclusions, and review cadence.
2. Orient: Read repository instructions, recover the active roadmap, route into relevant graduated docs, and inspect representative source and tests.
3. Declare: Record a concrete pass outcome, repository-relative scope, evidence, commit boundaries, and verification ladder.
4. Implement: Work in small boundaries that follow existing ownership and style.
5. Verify: Implementation starts with the cheapest useful signal and expands only when the risk and exact human or repository authority require it; planning and recommendation stop before test/build work.
6. Synchronize: Update the active roadmap as facts change, not after the owner discovers stale state.
7. Close: Reconcile scope, record verification, graduate durable knowledge, and stop at the next human boundary.

Use Work-Pass Governance for commands, receipt states, hooks, caching, and recovery. Use Repository Instructions And Sibling Coherence to understand Wavemap’s AGENTS.md, the Waveguide comparison contract, and read-only subagent roles.

Starting A Consequential Pass

Automatic discovery assumes Wavemap is the Codex project’s primary folder. Waveguide can be added as a secondary folder for sibling inspection, but running Codex from their shared parent directory does not recursively activate Wavemap’s AGENTS.md, skills, project config, or hooks. Files above or beside the primary folder may still be accessed when the session’s filesystem permissions allow it.

Codex discovers the repository-local $govern-work-pass skill from .agents/skills. Ask for it explicitly when starting or resuming a significant pass, or let its description trigger when the request advances a roadmap or follows extended design discussion.

node .agents/skills/govern-work-pass/scripts/work-pass.mjs inspect

The inspection output inventories branch state, required instruction hashes, known roadmaps, and an optional session receipt. It intentionally does not decide which architecture pages or source files are relevant; the agent must make that decision from the pass and the work-pass ledger.

What This System Does Not Promise

• It does not guarantee that a model understood what it read.
• It does not make hooks a complete security boundary or intercept every possible write path.
• It does not confer authority to commit, publish, deploy, merge, or contact external systems.
• It does not make Wavemap and Waveguide identical; it requires evidence and justification where they differ.
• It does not eliminate review. It makes hidden context loss and accidental convention drift easier to detect.

The practical success measure is fewer rounds spent rediscovering established patterns, repairing stale roadmaps, or correcting an implementation that looked reasonable but did not match the repository.