---
name: codd-evolve
description: |
  Conversationally evolve an existing CoDD project. Use when the user describes a functional change in natural language ("add logout button", "change course model to master + delivery target", "remove daily log step") and you need to update requirements, design docs, lexicon, source code, and tests together while maintaining CoDD coherence. Brownfield modification, NOT greenfield generation, NOT pure bug fix.
---

# CoDD Evolve — Conversational Brownfield Evolution

Take a Lord-style natural-language change request and automatically determine which design docs, lexicon entries, source files, and tests must move together to preserve CoDD coherence. The user expresses intent; this skill figures out scope.

## When to Use

- The user describes a **functional change** to an existing system, not a bug
- Examples of trigger phrases:
  - "Add a logout button to the admin nav"
  - "Change course management — courses should be a shared master with separate delivery targets"
  - "Restructure the learner list to drill down: facility → learner → course → progress"
  - "Remove the daily log append step from the karo completion flow"
  - "受講者管理を施設フィルター起点に変更"
- The user does NOT want to think about *which* design docs, lexicon entries, or source files to touch
- The project is already CoDD-initialized (has `codd/codd.yaml` and at least the design doc layout)

Do NOT use this for:

- Greenfield generation from scratch — use `/codd-init` then `/codd-generate`
- Pure bug fix where requirements and design are correct — use `codd fix` or `codd fix [PHENOMENON]`
- Reverse-engineering an undocumented codebase — use `codd extract` (or `/codd-restore`)
- Single-doc impact analysis only — use `/codd-impact`
- Code-only refactoring with no behavioral change — use `codd propagate`

## What This Does — Role Separation

This skill makes a single contract explicit:

| Layer | Who decides | What |
|-------|-------------|------|
| Intent | **User** | "I want X" in natural language |
| Strategic constraints | **User** | North star, hard prohibitions, breaking-change tolerance |
| Impact scoping | **This skill** | Which design docs, lexicon, source files, tests are affected |
| Doc updates | **This skill + CoDD** | Update requirements + every affected design doc in coherent order |
| Lexicon updates | **This skill** | Detect new terms, ask user before adding, then update lexicon |
| Implementation | **CoDD CLI** | `codd implement` from updated design |
| Verification | **CoDD CLI** | `codd verify` — must reach red 0 |
| Coherence finalization | **CoDD CLI** | `codd propagate` for cross-doc consistency |
| Failure judgment | **You (orchestrator)** | Decide retry vs ask user vs abort |
| Final approval | **User** | Review the PR / diff post-hoc |

The user must never have to choose *which file* to touch.

## Workflow

### Step 1 — Confirm prerequisites

Before starting, verify:

1. Current directory is a CoDD-initialized project (`codd/codd.yaml` exists)
2. Working tree is clean OR uncommitted changes are intentional (warn the user otherwise)
3. `codd verify` currently passes (red 0) — if not, the user should fix existing red first, per `codd fix [PHENOMENON]` prerequisite
4. If `codd verify` returns exit 0 with **silent stdout** (a known mode where build/test phases run but emit no text), fall back to `codd dag verify` for an explicit red-count readout. Use both signals when the baseline is uncertain.
5. If runtime verification_test nodes are unsuitable for the local environment, prefer an explicit config or skip over silent omission: set `verify.verification_timeout.total_seconds` / `per_node_seconds`, or run `codd verify --runtime --runtime-skip verification-test` and preserve the reported SKIP evidence.

If red exists, STOP and surface it. Do not attempt to layer new changes on a red baseline.

### Step 2 — Parse intent and classify

Classify the user's request into one of:

| Type | Marker | Likely affected docs |
|------|--------|---------------------|
| `add_feature` | "add X", "新規追加" | requirements + at least one design doc + lexicon (new terms) + new source + new tests |
| `change_behavior` | "change X to Y", "〜に変更" | requirements + affected design docs + lexicon (term-meaning shift) + modified source + updated tests |
| `change_data_model` | "data model", "schema", "table", "entity" | database_design + api_design + lexicon + migrations + source + tests |
| `change_ux` | "UI", "screen", "navigation", "画面" | ux_design + frontend source + frontend tests |
| `remove_feature` | "remove X", "削除" | requirements (mark removed) + design docs (remove sections) + source (remove) + tests (remove or update) + lexicon (deprecate term) |
| `cross_cutting` | Touches auth/permissions/i18n/tenancy | auth_design + every callsite + tests for every role |

If classification is ambiguous, ask one clarifying question (see Step 3).

#### Drift detection against existing design

After classification, scan the affected design docs for **pre-existing references to the proposed change**. Examples:

- The intent says "add logout button to admin nav," but `ux_design.md` already documents a logout entry in the tenant_admin / learner sidebars (impl never caught up).
- The intent says "add delivery_target table," but `database_design.md` has an Open Question (OQ-DB-NN) that proposes the same structure under a different name.

When such drift is found, classify it:

- **Drift A — broader-than-intent**: design covers more roles/cases than the intent. Either (a) flag to the user and ask whether to keep the narrower intent or align to the design, or (b) treat as a Step 3 gate-5 "ambiguous scope" trigger.
- **Drift B — design proposed, impl absent**: an Open Question or TODO matches the new intent. Reuse the existing terminology and mark the OQ as resolved.
- **Drift C — contradiction**: design says X, intent says not-X. Halt as a Step 3 gate-3 "structural impossibility."

Recording drift in the report prevents silent vocabulary divergence on subsequent evolutions.

### Step 3 — Stop-and-ask gates

Stop and ask the user **only** when one of these triggers fires:

1. **New lexicon term required.** The change introduces a vocabulary not in `project_lexicon.yaml`. Ask: "I'll add `<term>` to the lexicon meaning `<definition>`. OK?"
2. **Breaking change to existing behavior.** Existing users / callers will see different output. Ask: "This changes how `<X>` behaves for existing users. Is breaking change acceptable?"
3. **Coherence is structurally impossible.** Requirements would contradict an existing invariant. Surface the contradiction; do not proceed silently.
4. **Cross-cutting scope explosion.** The change touches more design docs than the user likely realized (rule of thumb: >4 docs). Confirm scope before charging ahead.
5. **Ambiguous role/scope.** "Add logout" — for which role? Or all roles? Ask once.
6. **1:N/N:N data model change -> UI page topology.** When `Step 2 classification == change_data_model` and the change introduces a 1:N or N:N relation that does not yet have an `operation_flow.ui_pattern` declared for the parent/child pair, ask which UI topology should be used: (a) single screen with everything inline, (b) master-detail on the parent's detail page, (c) drilldown to a dedicated child page, or (d) defer to LLM auto-decision, which is discouraged and may trigger a `ui_coherence` warning. Record the answer to `requirements/*.md` operation_flow as a new Operation entry.

#### Pre-approved branch

If the orchestrator (multi-agent system, task YAML, prior conversation, etc.) **already records explicit approval** for one or more of these gates, treat them as immediately confirmed without re-asking. Examples:

- A task YAML that states "lexicon `delivery_target` is pre-approved" → skip gate 1 prompt for that term.
- A task YAML that states "breaking change accepted by stakeholder" → skip gate 2 prompt.
- A handoff that names the role explicitly ("update only the central_admin nav") → skip gate 5 prompt; if drift detection (Step 2) finds the design covers more roles, surface the drift in the report instead of blocking.
- A task YAML that states "ui_pattern for `<child>` is master_detail" → skip gate 6 prompt and record the pre-approved topology source in the report.

Always record in the report which gates were short-circuited and the source of the prior approval. Pre-approval never applies to gate 3 (structural impossibility) — that always halts.

**Do not** ask the user:
- Which file to touch
- Which doc to update
- What order to do things in
- What to name a commit
- Which version to bump

### Step 4 — Execute the coherence chain

Once intent is confirmed, execute in this order (each step's output feeds the next):

```
1. Update requirements/*.md
   - Append new requirement / modify existing / mark deprecated
   - Preserve frontmatter, traceability IDs, and Bloom levels

2. Update affected design/*.md docs (in dependency order)
   - Determine order via codd's existing CEG (depends_on graph)
   - Update each doc body to reflect the new requirement
   - Preserve frontmatter exactly

3. Update project_lexicon.yaml if needed
   - Only after user confirmed in Step 3
   - Keep alphabetical / grouped order if existing convention

4. Run codd implement to (re)generate source from updated design
   - For incremental change, codd implement updates only affected modules
   - For pure data model changes, also generate migration files if applicable
   - **Generated-code impact check**: if the project keeps codd-generated output under `src/generated/**` (or equivalent), classify whether the change requires regenerating those modules or whether it stays in the hand-edited area (handlers, UI, tests). Record the decision in the report so future evolutions know whether `src/generated/**` was intentionally untouched.
   - **Prerequisite (cmd_345 K-3)**: if any design doc declares `operation_flow`, ensure `codd.yaml` has `ai_commands.impl_step_derive` set. Without it, `operation_flow_hint()` is silently skipped and declared UI patterns will not influence generation. Verify with `grep impl_step_derive codd/codd.yaml`; CoDD also emits a `WARNING` on stderr when this gap is detected.

5. Update tests
   - Tests for new requirements MUST be added (no silent skip)
   - Tests for removed requirements MUST be removed
   - Tests for changed behavior MUST be updated

6. Run codd verify
   - MUST reach red 0
   - If red persists, see Step 5 (failure handling)

7. Run codd propagate
   - Final cross-doc consistency pass
   - Catches any drift between source-as-implemented and design-as-written

8. Runtime smoke verification (MANDATORY — not optional)
   - Run `codd verify --runtime` from the project root and paste or link the generated runtime smoke report.
   - `codd verify --runtime` automatically checks:
     a. Local DB up via `codd.yaml runtime_smoke.db_check.command`
     b. Dev server up via `runtime_smoke.dev_server.url`
     c. Smoke connectivity via `runtime_smoke.smoke_connectivity[]`
     d. Real-browser E2E via `runtime_smoke.e2e.command`
     e. Opt-in CRUD flow reflection via `runtime.crud_flow_targets[]`
   - For every visible or `operation_flow` command/control/action that mutates
     state or emits a business result, add or reuse a CRUD flow target, an
     `action-outcome` target, or an equivalent E2E proving: trigger → server
     acceptance/mutation → re-fetch or observable outcome → visible reflection,
     persistence, emitted event, expected output, or absence as appropriate. A
     green GET smoke alone is not enough for mutating actions.
   - All results are written with raw logs to `reports/runtime_smoke_{{timestamp}}.md` unless the project config overrides the path.
   - Self-reported runtime smoke is not acceptable evidence. If `--runtime-skip <category>` is used, including `--runtime-skip verification-test` or `--runtime-skip crud-flow`, the report must show the skipped category explicitly and it must never be described as passed.
   - If `codd verify --runtime` fails: the change is NOT done. Either fix forward or revert. Reporting done with the server down is a critical violation of CoDD coherence.
```

Never reorder these steps. Doc updates always precede source updates — that is the CoDD coherence invariant. **Step 8 is the actual completion gate** — Steps 1-7 produce coherent artifacts, Step 8 proves the user can actually use them.

### Step 5 — Failure handling

If `codd verify` red persists after Step 4:

1. First retry: run `codd fix` once to let CoDD self-repair common issues
2. Second attempt: surface the failing test output, classify the cause
   - Test outdated → update test
   - Design contradicts requirement → ask user
   - Implementation cannot match design → ask user whether design is wrong or impl approach is wrong
3. Do not loop more than 3 times. After 3 failed attempts, STOP and report to user with concrete diagnostics

#### Local database unavailable

`change_data_model` work often needs a migration command (e.g. `prisma migrate dev`) that requires a running local database. If the DB cannot be reached:

1. Do **not** apply the migration to any non-local target (e.g. staging, production VPS).
2. Author the migration **by hand** under the project's migrations directory (Prisma example: `prisma/migrations/<timestamp>_<slug>/migration.sql`). Mirror the conventions of existing files in that directory (column order, index naming, foreign-key style).
3. Validate the schema declaration alone — `prisma validate` (or the framework's equivalent) — to confirm the model file parses and matches expectations.
4. Note in the report that the migration is **generated but unapplied**, and call out what the user must run locally once the DB is back (`prisma migrate deploy` for hand-authored migrations).
5. Treat this as an acceptable verification path only when `codd dag verify` and `codd propagate` also pass; it is **not** a substitute for full `codd verify` when build/test phases are reachable.

### Step 6 — Report

Generate a concise summary for the user:

```
Updated:
- requirements/foo.md (added: ログアウト機能)
- design/auth_design.md (added: NextAuth signOut handler)
- design/ux_design.md (added: 中央管理者ナビ Logout ボタン)
- src/components/AdminNav.tsx (added)
- src/app/api/auth/signout/route.ts (new)
- tests/e2e/logout.spec.ts (new)

Lexicon: no changes
Verify: red 0 ✅
Propagate: 0 drift ✅
Runtime smoke (Step 8):
  - `codd verify --runtime`: ✅
  - report: reports/runtime_smoke_20260517_210000.md
Done: ✅ (user can open the app and use the new feature)
```

If any Step 8 check is ❌, the change is NOT done. Either fix forward or revert; never report done with the runtime broken.

Suggest a commit message and offer to commit. Do not auto-commit unless the user confirms.

## CoDD Commands This Skill Orchestrates

| Command | When invoked | Why |
|---------|-------------|-----|
| `codd verify` (entry guard) | Step 1 | Confirm clean baseline |
| `codd impact` | Step 2 | Determine which design docs are downstream of the proposed change |
| `codd implement` | Step 4 (step 4) | Generate source from updated design |
| `codd verify` | Step 4 (step 6) | Confirm coherence after change |
| `codd fix` | Step 5 (retry) | Self-heal common verify failures |
| `codd propagate` | Step 4 (step 7) | Catch final source-design drift |

## Examples

### Example 1 — Feature addition (clear scope)

User: "Add a logout button to the admin nav."

Skill:
1. Classify → `add_feature`, scope = auth + ux (single role: admin)
2. No new lexicon, no breaking change → no Step 3 questions
3. Execute chain → requirements + auth_design + ux_design + impl + tests + verify + propagate
4. Report → "Added logout for central_admin role. 6 files touched, verify ✅"

### Example 2 — Data model change (asks once)

User: "Course management should be a shared master with separate delivery targets."

Skill:
1. Classify → `change_data_model`, scope = database + api + lexicon + migrations + ux
2. Step 3 trigger: new term `delivery_target` (`配信先`) not in lexicon → ASK
   - "I'll add `delivery_target` to the lexicon as 'a tenant/facility to which a course is distributed; many-to-one with course'. OK? Also, this changes the existing 1-course-1-tenant structure — migration required. Breaking change for existing course records is acceptable?"
3. After user confirms → execute chain including migration generation
4. Report

### Example 3 — Reject as bug-fix territory

User: "The login page sometimes times out on slow networks."

Skill:
- This is a bug, not a functional change. Decline politely:
  - "This sounds like a bug. Use `codd fix \"login times out on slow networks\"` instead — `codd-evolve` is for intentional design changes."

### Example 4 — Reject as greenfield

User: "Start a new SaaS project for restaurant reservations."

Skill:
- This is greenfield. Decline:
  - "For new projects, use `codd init` then `codd plan` followed by `codd generate`. `codd-evolve` is for evolving existing CoDD projects."

## Absolute Constraints

These are non-negotiable. Violating any of them defeats the purpose of CoDD:

1. **Never edit source without a corresponding design doc update.** If the change requires source modification, requirements and design must already reflect it.
2. **Never silently introduce a new lexicon term.** Always ask the user first.
3. **Never proceed past a red `codd verify`.** Either retry (max 3) or stop and ask.
4. **Never reorder the chain.** Requirements → design → lexicon → source → tests → verify → propagate → runtime smoke. No shortcuts.
5. **Never bypass user approval for breaking changes.** "Breaking" means: existing API contract changes, existing data semantics change, existing user-visible behavior changes.
6. **Never skip tests for new requirements.** A new functional requirement without a corresponding new test is incoherent.
7. **Never commit without user approval.** Stage and propose, but do not commit autonomously.
8. **Never declare done without runtime smoke verification (Step 8).** `codd verify` green is necessary but not sufficient. Run `codd verify --runtime` and keep the generated raw-log report. Reporting done while DB/dev server is down — or while a regression like migration conflict blocks startup — is a critical violation. Either bring the runtime up and prove it, or do not declare done.

## Guardrails

- Use the `codd` command, not `python -m codd.cli`
- Run from the project root (where `codd/codd.yaml` lives)
- Each invocation should handle one logical change. If the user bundles multiple unrelated changes ("add logout and also restructure the course list"), split into separate runs
- Preserve all frontmatter exactly — only modify doc bodies and append/remove sections as needed
- When updating docs, do not gratuitously reformat unchanged sections — minimal diff is a feature
- If the user is on a project where `codd verify` has never passed, do not start by attempting to evolve; recommend `codd extract` + `codd fix` to establish a green baseline first

## Troubleshooting

- "I don't know which design doc is affected"
  - Read every doc under `docs/design/` and `docs/requirements/` and classify by frontmatter `modules` / topic
  - Use `codd impact` to compute downstream effects from any candidate doc
  - If still uncertain, ask the user one targeted question (not a list of 5)
- "Lexicon term is borderline new vs existing"
  - Treat as new. Always ask. The cost of asking is low; the cost of silent vocabulary drift is high
- "Verify keeps failing after retries"
  - Stop. Report which test, which file, which line. Let the user decide whether the design or the impl is wrong
- "User keeps adding requirements mid-execution"
  - Politely defer: "I'll finish this change first (estimated N minutes), then handle the next one"

## Output Format

When reporting back to the user, always include:

1. **Intent classification** — what kind of change you understood
2. **Files touched** — grouped by docs / source / tests
3. **Lexicon delta** — new / changed / deprecated terms (or "no changes")
4. **Verify status** — red 0 ✅ or red >0 with concrete failures
5. **Suggested commit message** — single line, conventional commits format
6. **Next action** — what you recommend the user do (review, commit, request more changes)
7. **Scope decisions** — sub-scopes you intentionally excluded and the reason (e.g. "did not touch `Module.tenant_id` because it would require redesigning RLS isolation policies, out of scope for this evolution"). Required for `change_data_model` and `cross_cutting` types; optional but recommended for others. Pre-approval short-circuits from Step 3 should be listed here as well.

## Why This Skill Exists

CoDD's value is **coherence**: requirements, design, lexicon, source, and tests move together so no document lies about the system. The CLI form (`codd plan`, `codd implement`, `codd verify`) makes this explicit and reproducible — ideal for greenfield projects and CI automation.

But the CLI form has a cost in Brownfield modification: the user must remember which command to run, in which order, with what arguments. Each `codd fix "PHENOMENON"` invocation is a context switch.

`codd-evolve` removes that cost by accepting natural language ("add logout button") and orchestrating the CLI chain underneath. The user expresses intent; coherence is preserved automatically. The CLI remains the engine; this skill is the conversational front.

This is not a replacement for the CLI. Both are first-class:

- **CLI** for Greenfield, CI, automation, education, and third-party orchestrators
- **Skill** for Brownfield, conversational modification, daily evolution within Claude Code

Use the right tool for the right phase.
