perf(agents): streamline Terra execution

Keep Sol responsible for scope, steering, and final acceptance while assigning one continuous discovery, implementation, testing, and iteration unit to Terra. Route additional reviewers and runtime verification by risk and avoid redundant verification passes.
This commit is contained in:
jjbrunton committed 2026-08-30 17:33:48 +01:00
1 parent 8d9a3f4f1c
commit bdfe8b7171
4 files changed
+69 -37

No files matched your search

+9 -7
View File
@@ -1,12 +1,14 @@
name = "implementation"
description = "Default executor for a bounded Sauci product or harness change after scope and acceptance criteria are known."
description = "Terra executor for one continuous bounded Sauci product or harness change after scope and acceptance criteria are known."
model = "gpt-5.6-terra"
developer_instructions = """
Read the root and nearest scoped AGENTS.md files plus the applicable repository
skill. Implement only the delegated objective and preserve unrelated work. Update
maintained contract documentation and add focused tests when the contract changes.
Run the required focused checks and return changed files, exact results,
assumptions, and blockers. Stop for missing authority or a materially ambiguous
product choice. Do not expand scope or perform external, destructive, production,
release, or provider writes unless the task explicitly authorizes that action.
skill. Own the continuous execution unit: perform scoped discovery,
implementation, focused tests, and iteration in this handoff. Implement only the
delegated objective and preserve unrelated work. Update maintained contract
documentation and add focused tests when the contract changes. Run the required
focused checks and return changed files, exact results, assumptions, and blockers.
Stop for missing authority or a materially ambiguous product choice. Do not expand
scope or perform external, destructive, production, release, or provider writes
unless the task explicitly authorizes that action.
"""
+20 -11
View File
@@ -5,25 +5,34 @@ description: Prove a completed Sauci engineering task works before a PR. Use whe
# Verify Sauci work
Run locally on a non-default branch with the implementation committed.
Run locally on a non-default branch with the implementation committed. Use an
independent verifier for user-facing, cross-boundary, or high-risk runtime
changes. Documentation, mechanical configuration, isolated tests, and low-risk
package-local changes may use focused deterministic checks without a verifier.
1. Start the stack once with `scripts/dev-local.sh up`; reset fixtures first when
the task changes durable state. Web is `http://127.0.0.1:3000`, admin is
`http://127.0.0.1:3001`, and MCP health is `http://127.0.0.1:3002/health`.
2. Give a fresh read-only verifier the acceptance criteria. It drives browser
1. Package-local deterministic checks do not need a running stack. For runtime
verification, reuse a compatible running local stack when available; otherwise
start the documented full stack with `scripts/dev-local.sh up`. Reset fixtures
first when the task changes durable state. Web is `http://127.0.0.1:3000`,
admin is `http://127.0.0.1:3001`, and MCP health is
`http://127.0.0.1:3002/health`.
2. When independent runtime verification is required, give a fresh read-only
verifier the acceptance criteria. It drives browser
surfaces with the repository browser capability, native surfaces with Maestro
or the iOS simulator skill, and APIs with `curl`. Authentication fixtures are
described by `e2e/.auth/fixtures.json` after `dev-local.sh reset`.
3. The verifier writes screenshots, traces, video, or response evidence under
`evidence/` and returns only expected, observed, evidence paths, and
`works|broken`. It never edits code.
4. If broken, fix and use a fresh verifier. Stop after three failed rounds and
report the unresolved evidence.
5. After the task works, run `npm run verify:fast`, affected E2E, and
`npm run verify:full` when local Supabase/Deno are available. Never weaken an
assertion just to pass.
4. If independent verification is broken, fix and use a fresh verifier. Stop
after three failed rounds and report the unresolved evidence.
5. Run focused checks for the affected change. Run affected E2E when the runtime
path requires it. Run `npm run verify:full` when its prerequisites are
available; it already runs `npm run verify:fast`, so do not run both in
sequence. Never weaken an assertion just to pass.
6. Open a PR only after both task verification and regression checks pass. Upload
evidence to the established CI artifact or `pr-evidence` prerelease and embed
the screenshot plus a video/trace link in the PR body.
A green test suite without an independently observed task outcome is incomplete.
A green test suite without an independently observed outcome is incomplete when
independent runtime verification is required.
+10 -7
View File
@@ -25,13 +25,16 @@ MCP service in one npm/Turborepo workspace.
and prove the relevant compatibility contracts still hold. Preserve deployed
interfaces and supported client behavior; repository checks alone do not
prove a live change is safe.
10. Delegate every substantive repository task to at least one project agent so
detailed exploration or execution stays out of the primary context.
"Substantive" includes repository exploration, multi-file reasoning,
implementation, test execution, or contract/risk analysis. Use `repo_scout`
for read-only investigation and `implementation` for bounded changes; use
the additional roles according to `docs/agents/routing.md`. The primary
agent retains scope, acceptance, review, and the final answer. Skip
10. The Sol primary agent owns scope, risk classification, acceptance criteria,
progress steering, final diff and evidence review, and the final answer.
Delegate every substantive repository task to a project agent. Each
substantive implementation must use one Terra `implementation` agent as a
coherent execution unit, normally combining scoped discovery, implementation,
focused tests, and iteration. "Substantive" includes repository exploration,
multi-file reasoning, implementation, test execution, or contract/risk
analysis. Add a `repo_scout`, reviewer, or verifier only for separable work or
the triggers in `docs/agents/routing.md`; do not duplicate the implementation
agent's detailed exploration or checks without a concrete reason. Skip
delegation only for trivial conversation, a single obvious lookup, or a
mechanical one-line edit whose coordination cost exceeds the work.
11. Use high-effort reviewers only for the risk triggers in
+30 -12
View File
@@ -1,12 +1,17 @@
# Agent routing and effort
The primary agent owns scope, acceptance criteria, task decomposition, review,
and the final answer. Every substantive repository task must delegate at least
one bounded unit to the best-fit project agent. Use `repo_scout` for read-only
discovery or analysis and `implementation` for product or harness changes. Add
other agents only for separable work or the risk triggers below. Skip delegation
only for trivial conversation, a single obvious lookup, or a mechanical one-line
edit whose coordination cost exceeds the work.
Sol is the primary agent and owns scope, risk classification, acceptance
criteria, task decomposition, progress steering, final diff and evidence review,
and the final answer. Every substantive repository task must delegate to a
project agent. Each substantive implementation must delegate one coherent
execution unit to the Terra `implementation` agent. That handoff normally
combines scoped discovery, implementation, focused tests, and iteration in one
continuous task. Add a `repo_scout`, reviewer, test writer, or verifier only for
separable work or the triggers below. The primary reviews the returned diff and
evidence, but does not repeat the implementation agent's detailed exploration or
checks without a concrete reason. Skip delegation only for trivial conversation,
a single obvious lookup, or a mechanical one-line edit whose coordination cost
exceeds the work.
## Implementation and integration
@@ -44,10 +49,10 @@ Project Codex defaults live in `.codex/config.toml`; task profiles live in
| Role | Codex model | Default effort | Trigger | Do not use for |
|---|---|---:|---|---|
| `repo_scout` | Luna | low | locate ownership, callers, contracts | editing or design decisions |
| `implementation` | Terra | medium, overridable | bounded product or harness change | broad architecture review |
| `repo_scout` | Luna | low | separable read-only ownership, caller, or contract lookup | editing or design decisions |
| `implementation` | Terra | medium, overridable | one continuous scoped discovery, implementation, test, and iteration unit | broad architecture review |
| `test_writer` | Terra | medium | focused regression or missing contract test | rubber-stamping green output |
| `verifier` | Terra | medium | independently drive implemented behavior | editing implementation |
| `verifier` | Terra | medium | user-facing, cross-boundary, or high-risk runtime behavior | editing implementation or low-risk package-local changes |
| `database_reviewer` | Terra | high | migrations, RLS, function/query boundaries | ordinary UI changes |
| `security_reviewer` | Sol | high | auth, RLS, crypto, secrets, payments, destructive operations | every routine change |
| `architecture_reviewer` | Sol | high | cross-cutting or hard-to-reverse decisions | local refactors |
@@ -71,13 +76,26 @@ the implementation agent into a premium generalist. Add the matching read-only
Sol reviewer and keep implementation on Terra unless the user explicitly asks for
a different model.
## Verification routing
Use a fresh Terra `verifier` after implementation when the change has
user-facing runtime behavior, crosses an application, API, data, authentication,
or provider boundary, or is otherwise high risk. The verifier independently
drives the acceptance criteria and returns evidence only. It is not required for
documentation, mechanical configuration, isolated tests, or low-risk
package-local changes with focused deterministic checks. A verifier may still be
added when independent observation would materially increase confidence.
## Handoff contract
Every delegated task includes the objective, owned files or surface, acceptance
criteria, applicable `AGENTS.md` and skill, allowed side effects, required checks,
and the evidence to return. The agent must report changed files, commands and
results, assumptions, and blockers. The primary agent independently reviews the
diff and decides whether acceptance has been met.
results, assumptions, and blockers. The primary independently reviews the final
diff and evidence and decides whether acceptance has been met. It should steer
the active implementation agent with targeted feedback rather than restart the
same discovery or verification in another agent unless an independent judgment,
separable workstream, or the verification-routing trigger requires it.
Parallel agents are for independent read-heavy work or non-overlapping ownership.
Avoid concurrent edits to the same files, shared database state, fixed local