From 10c4ae8d84c1f02f189ed6c300c6640ed4c94179 Mon Sep 17 00:00:00 2001 From: jjbrunton Date: Sat, 29 Aug 2026 21:58:13 +0100 Subject: [PATCH] docs(agents): require isolated implementation --- AGENTS.md | 13 +++++++++++-- docs/agents/routing.md | 21 +++++++++++++++++++++ 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index baab081..42ad059 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,10 +17,17 @@ MCP service in one npm/Turborepo workspace. 5. Read `apps/mobile/DESIGN.md` before mobile UI work. 6. Keep shared package exports type-only and route them through `src/index.ts`. 7. Do not commit secrets, generated evidence, local logs, or runtime state. -8. Scope work to the task. Route bounded implementation through the project +8. Implement in a task-specific git worktree created from current `staging`, + not in the shared `staging` checkout. After the work is verified, merge the + completed task branch back into local `staging`. +9. Before merging, identify every deployed app or service the change can affect + 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. Scope work to the task. Route bounded implementation through the project `implementation` agent when delegation is useful; the primary agent retains acceptance, review, and final verification. Do not delegate trivial edits. -9. Use high-effort reviewers only for the risk triggers in +11. Use high-effort reviewers only for the risk triggers in `docs/agents/routing.md`. ## Repository map @@ -39,6 +46,8 @@ MCP service in one npm/Turborepo workspace. ## Workflows +- Implementation: create a task worktree from current `staging`; merge verified + work back to local `staging` when complete. - Bootstrap: `npm ci` - Full local stack: `scripts/dev-local.sh up` - Fast checks: `npm run verify:fast` diff --git a/docs/agents/routing.md b/docs/agents/routing.md index dac7d0b..6778361 100644 --- a/docs/agents/routing.md +++ b/docs/agents/routing.md @@ -5,6 +5,27 @@ final answer. Use one implementation agent when a bounded handoff will keep nois execution out of the primary context. Do not pay the coordination cost for a trivial one-file edit. Add other agents only for separable work or a risk trigger. +## Implementation and integration + +Implementation starts in a dedicated task worktree created from the current +`staging` branch. Keep the shared `staging` checkout clean and use it only as the +integration target. Complete the scoped change, review its diff, and run the +required verification in the task worktree. Merge the task branch back into local +`staging` only after that evidence passes; an unverified or partially complete +branch does not belong in `staging`. Pushing or deploying `staging` remains a +separate operation subject to the applicable release and production-safety rules. + +Before implementation, map the change to every deployed consumer it can affect, +including supported mobile builds, web and admin clients, the API and worker, and +internal MCP integrations. Preserve their current interfaces, configuration, +authentication and data expectations. Verification must cover the affected +contracts and cross-application path, not only the edited package. If the change +can alter live production, first establish the actual deployed versions, +configuration, dependencies, interfaces, and behavior; after deployment, +independently verify the affected end-to-end behavior. A local test, repository +state, or successful deployment record is not proof that deployed apps remain +functional. + ## Cost ladder Project Codex defaults live in `.codex/config.toml`; task profiles live in