mirror of
https://github.com/jjbrunton/Sauci.git
synced 2026-10-31 10:19:43 +00:00
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:
1 parent
8d9a3f4f1c
commit
bdfe8b7171
4 files changed
+69
-37
No files matched your search
@@ -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.
|
||||
"""
|
||||
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user