| name | 16-evolve |
| description | Orchestrator for feature and new_service sessions: adds product capabilities, scope/API/arch changes, breaking refactors, new dependencies, and multi-doc spec updates. Uses Cursor Plan mode as the default orchestrator for intake, Fn allocation, impact, and routing (Phase 0–1), then Agent mode to run routed child stages; 04/07 keep their own Plan→Agent batch loops. Requires active_session (00-context) with type feature or new_service. Every change must cite the project doc corpus. Use after 00-context for structured change on an existing app — not for surgical bugs (14-hotfix) or greenfield (pipeline).
|
16 — Evolve (Features & Large Changes)
Take an existing service from change request (including multiple new features in one
cycle) through updated specs, verified plans, implementation, and redeploy — reusing stages
00–15 in delta mode.
Protocol: protocol-card.md — corpus-first, Lean/Standard/Full, batched state.
Detail: reference.md · pipeline-preamble.md
Sessions: sessions-reference.md — requires feature or new_service active_session.
Routing: docs/skill-routing.md (active project) — when to use evolve vs hotfix vs pipeline.
Plan ↔ Agent: plan-mode-loop.md — Plan mode is the default
orchestrator for Phase 0–1 (scope → Fn → routing); Agent runs child stages; 04/07 Plan
separately for execution batches.
State agent: project .cursor/agents/workflow-state-manager.md if present; else edit workflow-state.yaml per workflow-state-reference.md — mandatory read/update.
Corpus: Open docs/CORPUS.md (active project) rows for touched features only — not the
entire minimal corpus on every cycle. Domain/guides opt-in. See Doc corpus citations below
(and always-apply rule doc-corpus-citations — canonical:
packages/agent-tooling/docs/conventions/doc-corpus-citations.md).
Connectivity: Browser-facing changes → applicable connectivity-gates.md
rows (at minimum 01/04 delta, 07, 12–13 with H4–H5 when UI ships).
User is the source of truth. Interview before editing specs or code. Every ambiguous,
uncertain, or contradictory finding uses AskQuestion — never guess.
Doc corpus citations (mandatory)
Every change, claim, and reference in an evolve cycle must cite the doc corpus.
| Form | When |
|---|
[Corpus: <id>] | docs/CORPUS.md exists and lists the row |
[path §section] | No corpus id yet — still cite the standing doc |
[Corpus: WAIVED — <topic>; reason: …; decided: EV-NNN|date] | Coverage missing and user chose proceed |
Missing coverage (CORPUS.md absent, no row, or no authoritative section):
- Interview via AskQuestion — recommend add doc/row now; always offer waive-and-proceed and re-scope.
- Proceed only with an explicit waiver citation (table above) if the user chooses waive.
- Log the waiver under
docs/decisions/evolve-decisions.md §Cycle {id}.
- Do not invent normative docs silently; draft only after the user picks add-now.
Pass citation obligations to child stages in evolve context (corpus_cites / waiver ids). Checkpoint
digests and impact/routing plans must list cites (or waivers) for each Fn and artifact edit.
When to use
Default for existing apps: if the work adds capability, changes contracts, or touches multiple
specs — use 16-evolve, not 14-hotfix or ad-hoc 07-build.
| Situation | Use |
|---|
| Add feature(s) — "add X, Y, Z", new Fn, user-visible capability | 16-evolve |
| Large change — multi-service, breaking API, major refactor | 16-evolve |
| General change — scope, acceptance criteria, config surface | 16-evolve (cycle_type: general) |
| Scope/API/arch change (may or may not add Fn) | 16-evolve |
| Change scope, API, config, or acceptance criteria | 16-evolve |
| Architectural or dependency change affecting multiple docs | 16-evolve |
| Bug fix, regression, small patch on production | 14-hotfix |
| Greenfield service from scratch | pipeline |
| Modal ops / health investigation only | 15-service-health |
| Lessons learned / improve skills 00–19 | 17-retrospective |
Stages 00–15 may receive a feature or large-change request during an active session with
type feature or new_service and an active evolve cycle. If no session exists, workflow-state-manager
blocks and recommends 00-context — then 16-evolve for net-new feature work.
Prerequisites
Before starting an evolve cycle:
active_session exists with type feature or new_service (opened by 00-context).routing-plan.md lists required stages; user approved plan.workflow-state.yaml exists with prior pipeline progress (ideally Phase D complete).- Spec documents exist under
docs/ (at minimum feature-list.md, spec.md, test-plan.md).
- Codebase exists with a deployable artifact (or user confirms build-only evolve).
If active_session is null, route to 00-context first.
If prerequisites are missing, ask via AskQuestion: run full pipeline first,
or proceed with a reduced doc set (record waiver via workflow-state-manager).
Plan mode as orchestrator (default)
16-evolve uses Cursor Plan mode as the default orchestrator for cycle design — not a rare
exception. Pattern:
| When | Mode | Purpose |
|---|
| Phase 0–1 start / resume / re-route | Plan | Scope, Fn allocation, impact, Lean/Standard/Full routing, stage order |
| After Plan approval | Agent | Write evolve-plan-card, decisions, invoke child skills |
| Phase checkpoints (A/B/C/D) when replan needed | Plan | Adjust remaining routing / batch before continuing |
| Child 04 / 07 | Their own Plan→Agent | Execution plan + Build Plan Card / milestone batches |
| Child 01–03, 05–06, 08–15 | Agent only | Interviews, audits, tooling, verify, deploy |
Evolve Plan Card
Write/update: docs/sessions/{id}/evolve-plan-card.md (alongside routing-plan.md).
# Evolve Plan Card
> Cycle: EV-NNN | Session: SNNN-slug | Updated: ISO-8601
## Goal
[one sentence]
## Features
- F{n} — [title] — [Corpus: …]
## In / out of scope
- In: …
- Out: …
## Preset + routing
- Preset: Lean | Standard | Full
- Stages (ordered): …
## Next child stage
[NN-name] — delta context summary
## Risks / open decisions
- …
Plan session prompt (evolve)
You are orchestrating an evolve cycle (16-evolve), not implementing code.
Read:
1. docs/sessions/{id}/session-brief.md + routing-plan.md
2. docs/sessions/{id}/evolve-plan-card.md (if present)
3. docs/CORPUS.md rows for touched Fn only (+ feature-list excerpts)
Produce:
1. Concrete Goal, In/Out of scope, Fn list with corpus cites
2. Recommended preset (Lean default on existing apps) + ordered stage list + skip rationale
3. Impacted docs / packages
4. Updated Evolve Plan Card body
5. First child stage to invoke after Agent switch
Do not edit product code or run 07 Task Loop. AskQuestion categories for ambiguities.
When approved → Agent mode continues 16-evolve Phase 1 write + Phase 2 child invocation.
SwitchMode: at Phase 0 start (and when re-routing mid-cycle), SwitchMode → plan with
the prompt above; after user approval → agent to persist the card and execute. Skip Plan
only when the user already approved a complete evolve-plan-card this turn.
Interactive questions (required)
Every user-facing question must use the AskQuestion tool — same protocol as
14-hotfix and considerations.md §7.
If the AskQuestion tool is unavailable, use the markdown numbered-options fallback in
considerations §7 — same option rules; do not invent answers.
| Situation | Pattern |
|---|
| Change / feature intake | 2–4 questions per batch; wait for all answers |
| Single gate or approval | One AskQuestion; first option = recommendation; last = Let me explain / provide more context |
| Impact / stage routing | Present recommended stage list; user confirms or adjusts |
| Ambiguity / contradiction | Category label in prompt: [Decision], [Ambiguity], [Contradiction], [Uncertainty] |
| Missing corpus coverage | AskQuestion: add doc/row now (recommended) / waive-and-proceed / re-scope; record cite or waiver |
| Phase gate failure | List unmet criteria; block until resolved (no silent proceed) |
| Phase checkpoint (A–D, deploy) | Progress digest + AskQuestion before next phase |
| UI in scope | AskQuestion: offer a non-deployed (local) UI preview — see §UI preview |
Do not invent user answers. Prefer the AskQuestion tool; markdown lists are allowed only as the §7 fallback.
UI preview (when the cycle includes UI)
Whenever the evolve cycle adds or changes a browser UI surface, offer a preview via
AskQuestion. Label it clearly as a non-deployed / local instance — not staging or
production (those remain 12/13 / H4–H5).
When to ask (at least once per cycle with UI; re-ask after material UI changes):
| Moment | Ask |
|---|
| Phase 0 intake (UI mentioned) | Optional early look at current local UI to ground scope |
| After Phase C (07/08 done) | Preview the built UI before Verify |
| When 11-verify-impl is routed | Child skill runs its required preview AskQuestion; orchestrator ensures it was offered |
| Phase D / close checkpoint | If user skipped earlier, offer once more before deploy |
prompt: "UI preview (non-deployed): Preview the UI on a local / non-deployed instance?
Not staging or production — local build only."
options:
1. "Yes — open non-deployed preview"
2. "No — continue without preview"
3. "Remind me at 11-verify-impl"
4. "Let me explain / provide more context"
Record accept/decline in the cycle checkpoint digest / evolve summary.
Session management
Orchestrator for feature and new_service sessions. Requires active_session from 00-context.
Writes summary to docs/sessions/{id}/reports/evolve-summary.md. Links evolve_cycles[].session_id.
Per sessions-reference.md §10.
State management
Agent protocol: workflow-state-agent-protocol.md.
Primary state: evolve_cycles[] (not under stages). Schema: reference.md.
On invocation:
- Invoke workflow-state-manager
read_context with skill_id: 16-evolve and user_intent.
- Verify
active_session.type is feature or new_service; else block → 00-context.
- Set
active_session.orchestrator: 16-evolve; link evolve_cycles[].session_id to active_session.id.
- If an evolve cycle is
in_progress, report position; AskQuestion: resume / abandon / start new.
- If none in progress, start Phase 0 — Change / feature intake.
After every substep: agent update on the active cycle (status, current_stage, artifacts, ADRs,
checkpoints, git_history).
Mid-evolve interrupt → 14-hotfix
When live H3 (or other P0 production) fails during an in_progress evolve cycle (often
from 13-deploy-smoke or 15-service-health):
- AskQuestion immediately (do not silently keep building the next milestone):
- Pause evolve and open 14-hotfix (recommended)
- Continue evolve with explicit waiver (record risk)
- Investigate only (stay on 15) then re-AskQuestion
- Let me explain / provide more context
- If pause+14: set
evolve_cycles[].interrupted_by_hotfix: true, interrupt_reason, and
hotfix_ref (BUG/PR when known). Update HANDOFF.md with an Interrupt section
(symptom, tip SHA, next = 14-hotfix).
- Resume 16-evolve only after hotfix close AskQuestion clears the interrupt flag
(or the user explicitly abandons the cycle).
Deploy gates still require tip CI/CD green and honest env_role (staging vs prod when
dual DOKS clusters exist — ADR-034 / EV-044; sole stack = live/prod only when staging
is absent). Promote to main only via PR stage→main after Staging smoke + Staging
gate green — never feature→main. Before that promote PR: release prep (semver bumps
for changed publishable packages + CHANGELOG on stage); after merge: tag deploy
(+ PyPI tags if publishing). See docs/deploy.md §Promote.
Git branch and commit-as-you-go
Each evolve cycle works on evolve/{cycle-id}-{slug}. Record branch via agent on creation.
Commit deltas as you go; agent update appends git_history.commits with stage: "16-evolve".
When complete, create a PR from the evolve branch to stage (not main); promote to
prod via a separate stage→main PR with release bump+tag.
Delta / feature-addition mode
This skill orchestrates delta mode for all child stages. See reference.md
for multi-Fn cycles, intake batches, checkpoints, and routing matrix.
Workflow overview
Plan mode (orchestrator): intake → Fn → impact → routing
│ approve → Agent writes evolve-plan-card + routing-plan
▼
┌──────────────────────────────────────────────────────────┐
│ A: Product 01* → 02* → 03* (Agent) │
├──────────────────────────────────────────────────────────┤
│ B: Technical 04* → 05* → 06* (04: Plan+Agent) │
├──────────────────────────────────────────────────────────┤
│ C: Build 07* ◄── 08* (07: Plan+Agent) │
├──────────────────────────────────────────────────────────┤
│ D: Verify 09* + 10* → 11* → 12* → 13* (Agent) │
└──────────────────────────────────────────────────────────┘
│ (re-enter Plan at checkpoints if re-routing)
▼
Evolve summary + optional 14-hotfix / 15-service-health / 17-retrospective
* = invoke only if routing plan marks stage required
**Checkpoints:** mandatory digest + AskQuestion after phases A, B, C, D, and deploy
Phase 0 — Change / feature intake
Default: enter Plan mode (see §Plan mode as orchestrator) before locking scope.
Use AskQuestion inside Plan or after Agent return for corpus gaps and the proceed gate.
Interview until the change is concrete enough for Fn allocation and impact analysis.
For net-new features, use intake batches in reference.md §Feature intake batches.
For general changes, use:
| Batch | Topics |
|---|
| Intent | What to change, why now, success criteria |
| Scope | In/out of scope, breaking vs compatible, features affected |
| Constraints | Cost, latency, data, deploy target |
Surface immediately via AskQuestion anything ambiguous, uncertain, or contradictory.
Map each in-scope area to a corpus cite (or interview for missing docs / waiver) before the
proceed gate.
Approval gate: AskQuestion — "Proceed to allocate Fn(s) and impact analysis on this scope?"
Record approved scope in docs/decisions/evolve-decisions.md §Cycle {id} — Scope (via committed doc;
agent records cycle metadata). Include Corpus cites / waivers for the approved scope.
Update Evolve Plan Card Goal / In-Out / Features.
Phase 1 — Fn allocation, impact analysis, routing
Stay in or re-enter Plan mode until preset + stage list are approved; then Agent
writes artifacts.
-
Multi-feature default: one cycle, multiple Fn — assign next Fn ids from feature-list.md.
-
List docs to update and routing_plan — reference.md (Stage routing matrix).
-
Presets (AskQuestion; default Lean on existing apps — see protocol-card):
| Preset | Required stages (typical) |
|---|
| Lean | 00 → 16 → 01 → 02 → 10 → 13 |
| Standard | Lean + 04 → 07 → 08 → 09 → 11 → 12 |
| Full | Standard + 03 / 05 / 06 as needed |
-
Present preset + skip rationale via AskQuestion; user confirms or adjusts.
-
Persist evolve-plan-card.md + routing-plan.md; agent update: create evolve cycle with
feature_ids, checkpoints, routing.
-
Checkpoints: mandatory after A/B/C/D/deploy on Standard/Full; on Lean, only on
gate failure or user request (token/step savings — RET-001).
-
If checkpoint requires re-route: Plan again, then Agent continues Phase 2.
Phase 2 — Execute routed stages (delta mode)
Invoke child skills one at a time (except 09+10 parallel). Pass evolve context:
mode: evolve
evolve_cycle_id: EV-NNN
feature_ids: [F19, F20, F21]
scope: <approved Phase 0>
affected_artifacts: [paths]
delta_only: true
corpus_cites: ["[Corpus: id]", "[docs/… §…]"]
corpus_waivers: []
Child skills invoke workflow-state-manager themselves; 16-evolve verifies transition checks
between stages.
Interactive checkpoint
Standard/Full: after phases A, B, C, D, and after 13-deploy-smoke, present digest then
AskQuestion. Template: reference.md §Checkpoint digest.
Lean: skip routine checkpoints; AskQuestion only on gate failure or user request.
For 11-verify-impl (when routed), include per–acceptance-criterion status for each Fn.
Phase gates (blocking)
| Gate | Criteria |
|---|
| A→B | Fn in feature-list; delta specs; 02 pass; 03 if routed |
| B→C | Execution-plan tasks approved; 05 pass; 06 if routed |
| C→D | All Fn tasks done; latest 08 pass |
| Deploy | 09+10 pass; 11+12 user-approved; deploy approved; tip CI/CD green unless waived; env_role honest (staging/prod or sole stack = live/prod); promote to main only via stage after Staging smoke/gate; release prep (semver + CHANGELOG) on stage and post-merge tags recommended |
On failure: list unmet criteria → AskQuestion → fix in place per considerations §2.
Phase 3 — Consistency verification
After 02-verify-plan and 05-verify-tech, run reference.md §Consistency checklist.
Phase 4 — Close evolve cycle
- Write
docs/evolve-report-{cycle-id}.md.
- Agent
update: cycle status: completed, timestamps, artifacts.
- Append CHANGELOG / deploy-report if deployed.
- AskQuestion: done / 15-service-health / 14-hotfix / 17-retrospective.
Fix in place
Same as pipeline — never re-run entire phases for verification failures.
Safe stopping points
- After Phase 0–1 (Fn + routing approved; no code)
- After Phase A (specs + 03 guardrails)
- After Phase B (execution plan approved)
- After Phase C (implemented, not deployed)
- After 11-verify-impl (verified; deploy optional)
Output rules
- One routed stage at a time (except 09+10).
- Delta by default — full regeneration only with user approval.
- Multi-Fn in one cycle unless user splits via AskQuestion.
- Checkpoints — Standard/Full: after A–D and deploy; Lean: on gate failure only.
- Child skills own detail — read child
SKILL.md when invoking; not full reference.md unless needed.
- State via agent — batch start+exit updates per protocol-card; never edit YAML directly.
- Do not
@-attach full skill bodies — name + routing-plan is enough.
- UI preview — when UI is in scope, AskQuestion for a non-deployed preview; never
present staging/production as that preview unless the user explicitly requests it.
- Corpus cites — every change/reference includes
[Corpus: …] / path+§ or an explicit
[Corpus: WAIVED — …] after interview; never silent undocumented invent.
- Plan orchestrates, Agent executes — Phase 0–1 (and re-routes) in Plan mode; persist
Evolve Plan Card in Agent; do not implement feature code while still in Plan.
Additional resources
