Adoption roadmap: from one change to a closed loop

The adoption roadmap moves one repository from ad hoc prompting to a governed AI-native SDLC in five evidence-based waves. Each wave adds only the controls needed by the next one: artifact handoffs, session feedback, review gates, isolated parallel work, and finally production signals that create the next intent.

Do not automate all six stages at once. A weak manual loop becomes a faster weak loop. Start with one representative change, preserve the artifacts and metrics, and advance only when the exit evidence is visible in Git, CI, pull requests, or incident records.

Before the first wave

Choose a repository that has:

• a maintainer who can accept intent.md, spec.md, and plan.md;
• local typecheck, lint, test, and build commands;
• branch protection and a named production approver;
• no requirement to give the agent production credentials;
• enough recurring work to compare at least five similar changes.

Record the baseline: lead time, first-pass CI success, review cycles, escaped defects, and change-failure rate. The goal is not maximum agent activity. It is faster completed work without worse quality or control.

The five waves

Wave	Add	Human gate	Exit evidence
0. Baseline	One repository, one change type, current metrics	Maintainer selects scope and risk tier	Five comparable historical changes and their outcomes
1. Artifact first	intent.md → spec.md → plan.md; Plan mode; session feedback loop	Product owner accepts intent/spec; engineer accepts plan	Three changes preserve the chain and run checks before review
2. Review first	Ranked agent review, protected tests, branch protection, production approval	Code owner merges; release owner approves production	Agent review runs on every pilot PR and cannot bypass required checks
3. Safe parallelism	One worktree per task, scoped credentials, reusable skills, deterministic hooks	Engineer assigns scope and reconciles results	Two concurrent tasks complete without file, port, state, or cloud collisions
4. Bounded automation	Non-interactive checks, scheduled scans, machine-readable outputs, evals for harness changes	Owner approves new automation and policy changes	Jobs fail closed, emit evidence, and cannot mutate production
5. Closed loop	A deterministic production signal creates a triage record and next intent.md	Service owner decides severity and route; normal merge/release gates remain	A synthetic breach reaches triage with evidence and no direct production mutation

Run wave 1 on a real change

1. Capture the problem and desired outcome in intent.md. Exclude implementation details.

2. Produce spec.md from accepted intent. Apply security, UX, data, and compliance policies while the spec is drafted.

3. Enter the tool’s Plan mode, inspect the repository, and save the accepted plan.md.

4. Implement one bounded milestone in an isolated checkout.

5. Run the actual repository checks before reporting completion. Preserve command output and visual evidence with the PR.

6. Compare the result with the baseline and record rework, review time, and any escaped defect.

Use the same steering prompt in Claude Code, Cursor, or Codex:

Read the accepted intent.md and spec.md plus the repository instructions.
In read-only planning mode, propose one implementation milestone with exact files,
risks, test-first proof, rollback, and commands to run. Stop for approval.
After approval, implement only that milestone in an isolated checkout.
Do not weaken tests or cross the production gate. Report literal command results.

Decide whether to advance

Advance only when the current wave is boring and repeatable:

• the expected artifact appears without a reminder;
• the named person knows exactly what they approve;
• failures stop the workflow instead of becoming warnings;
• evidence is attached where the next reviewer works;
• the lagging quality metric is stable or improving.

Do not skip from Plan mode to autonomous production

Parallel agents multiply review and operational load. Scheduled remediation multiplies authority. Neither is a maturity shortcut; each depends on the artifact chain, executable proof, identity separation, and a release gate the agent cannot satisfy.

Adoption failure modes

The pilot uses only trivial tasks. Choose repetitive but production-relevant work with real tests and a real reviewer. Typo fixes do not exercise the lifecycle.

Artifacts become paperwork. Each file must be read by the next stage and linked from the PR. Delete fields that no decision or agent consumes.

Throughput rises while change failures rise. Stop adding concurrency. Improve the specification, feedback loop, evals, and review signal before increasing autonomy.

The tool becomes the process. Keep accepted artifacts and gates portable. A team must be able to switch Claude Code, Cursor, or Codex without redesigning its controls.

Continue the rollout

Artifact chain Create the portable handoffs used in waves 1–5.

Governance and autonomy Assign risk tiers, identities, permissions, and human gates.

Metrics Measure speed and quality together at every wave.

Tool map Implement the same rollout in Claude Code, Cursor, or Codex.