docs(agents): require isolated implementation

This commit is contained in:
jjbrunton committed 2026-08-29 21:58:13 +01:00
1 parent ac4a05d5ed
commit 10c4ae8d84
2 files changed
+32 -2

No files matched your search

+11 -2
View File
@@ -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`
+21
View File
@@ -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