Change Routing Workflow

Status: Active Last reviewed: 2026-06-28 Scope: Routing table for common TwoMore changes. Use this before editing so docs reduce startup time instead of adding drift.

Start with Current Project State, Current Documentation State, and AGENTS.md. Then use the row that matches the primary artifact. If a change spans multiple rows, split the work or state the cross-row verification explicitly.

Before editing roadmap or release-gated work, open with the slice contract from Execute A Roadmap Slice. The agent must name:

• active slice;
• mode;
• current blocker;
• allowed scope;
• blocked scope;
• acceptance proof;
• verification ladder;
• stop rules.

If those cannot be stated concretely, do source/evidence inventory first rather than implementing.

Routing Table

Change type	Read first	Usually update	Required verification
Docs-only active guidance	AGENTS.md, docs/current-doc-state.md, affected doc; release-process docs also read docs/workflows/release-versioning-and-ota.md and docs/release-evidence.md	affected doc, index links, generated state docs if facts changed; release-process changes record "no OTA/build run" unless app artifacts changed	yarn docs:generate, yarn docs:check, git diff --check
Roadmap or implementation slice change	docs/architecture/roadmap.md, docs/architecture/implementation-plan.md, docs/specifications/app-functionality-map.md, relevant research/spec doc	roadmap status/outcome if sequencing changed, implementation-plan slice status/scope, product/spec/research docs if truth changed, generated state docs	yarn docs:generate, yarn docs:check, git diff --check; yarn check when code changed
New or changed SQL migration	AGENTS.md DATA-13, docs/guides/api-supabase.md, relevant schema docs	migration file, purpose catalog row or PI-EXEMPT, generated state docs	yarn lint:pi-schema, yarn docs:generate, yarn check
Supabase generated type refresh	docs/guides/api-supabase.md, docs/guides/builds-and-deployment.md	packages/app/src/adapters/supabase/generated.types.ts, generated state docs if migration count changed	yarn check:supabase-types when configured, yarn docs:check, yarn check
New feature screen	docs/agent-prompts/add-screen.md, docs/architecture/shared-client-architecture.md, AGENTS.md COMP rules	feature package screen, route shell, i18n keys, screen docs if active	yarn check; add targeted tests when behavior is non-trivial
New query hook	docs/agent-prompts/add-query.md, AGENTS.md DATA-10, freshness posture docs	query hook, query keys/cache helpers, JSDoc freshness contract	yarn check; targeted hook/cache tests when behavior changes
New mutation hook	docs/agent-prompts/add-mutation.md, AGENTS.md DATA-2/DATA-11/DATA-12	mutation hook, optimistic patches/cache writes, queue executor if offline-capable	yarn check; targeted mutation tests
New ESLint rule	packages/eslint-plugin/README.md, AGENTS.md, relevant rule docs	rule implementation, tests, rule doc, AGENTS enforcement if graduated, generated state docs	rule test, yarn docs:generate, yarn docs:check, yarn check
Ratchet baseline change	docs/adr/0006-eslint-ratchet-zero-waivers-policy.md, eslint.ratchet.config.mjs	ratchet config, generated state docs, any active docs naming counts	yarn metrics, yarn docs:generate, yarn docs:check, yarn lint:strict
Mobile build or OTA work	docs/workflows/release-versioning-and-ota.md, docs/release-evidence.md, docs/guides/builds-and-deployment.md, docs/device-setup.md, docs/production-readiness.md	docs/release-evidence.md with source commit, upstream-sync status, runtime, EAS artifact ID, smoke result, and rollback pointer; build/deployment docs only when workflow changes; generated state docs if app version/runtime changed	release decision gate; node scripts/guard-ota-release.mjs <target> for OTA; git status --short, git fetch --prune, and git log --oneline @{u}..HEAD empty for builds; yarn preflight when building; relevant EAS command; yarn docs:check; pre-production OTA target is yarn ota:preview only
Web route change	README.md, apps/web/README.md, docs/architecture/shared-client-architecture.md	route docs, generated state docs	yarn docs:generate, yarn docs:check, web build when route behavior changed
Launch blocker update	docs/pre-launch-checklist.md, docs/production-readiness.md, docs/current-project-state.md	checklist/readiness ledger; generated state docs only if repo facts changed	yarn docs:check, source evidence for blocker state
External credential/vendor work	docs/guides/credentials.md, relevant vendor guide, docs/pre-launch-checklist.md	credential docs, readiness ledger, never secret values	yarn docs:check; runtime/vendor smoke when credentials are used

Deferral Rule

If the work discovers stale historical material or useful adjacent improvements outside the active slice, do not expand the slice automatically. Record it as a follow-up unless it would mislead the current implementation path or directly blocks the named acceptance proof.

For R1 closure work, the default answer to adjacent improvements is "defer." Only work that removes one current yarn report:r1-release-readiness blocker, or proves that blocker is owner/vendor/deployment-controlled, stays in scope.

Generated State Rule

Do not manually edit generated state pages. If a routed change affects counts or repo facts, run:

yarn docs:generate
yarn docs:check

yarn check includes docs:check, so stale generated docs or known stale active-doc references block normal completion.

Multi-Agent Coordination

Use parallel agents only when the slices have distinct primary artifacts and non-overlapping write paths. The main agent owns integration, final docs state, and the verification ladder.

For multi-agent work, one agent must remain the integration owner. Subagents return evidence and proposed patches; they do not broaden the active slice or accept product/release status independently.

Before delegation, give each agent:

• the matching routing-table row;
• allowed paths and blocked paths;
• the source docs to read first;
• the exact verification command it can run locally;
• the evidence shape expected back: files touched, current-state facts checked, commands run, failures, and deferrals.

Subagents should not manually edit generated state pages. If their slice changes repo facts, they report that fact and the main agent runs yarn docs:generate once after integration. This prevents generated-doc churn and keeps one final source of truth.

Pause and re-split if two agents need the same file, an agent discovers a new AGENTS.md rule is needed, or a route row no longer covers the work. Treat that as a plan change, not an incidental edit.

Research Basis

This workflow follows four current operating assumptions:

• OpenAI Codex AGENTS.md guidance: Codex loads AGENTS.md before work and stops adding project instruction files at the configured byte budget, so AGENTS.md stays compact and yarn lint:agents-md enforces a local size guard.
• Write the Docs: docs-as-code: documentation lives in Git and should move through the same review/CI lifecycle as code; generated state docs and docs:lint-stale are this repo's drift layer.
• GitHub protected-branch status checks: required status checks are the reliable merge barrier, so docs drift checks run in CI and pre-push rather than relying on agent memory.
• Expo EAS Update deployment guidance: channels and runtime versions are the deployment control plane, so release work now routes through the release-versioning workflow before OTA or builds.
• Anthropic context-engineering guidance: multi-agent work is most useful when deep exploration stays isolated and returns distilled evidence to one integration owner.