contract-driven-delivery 2.0.17 → 2.0.19

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [2.0.19] - 2026-05-15
+
+Design ownership patch for the implementation-planning flow.
+
+### Changed
+
+- **`design.md` now has an explicit owner and task**: `spec-architect` owns
+  `specs/changes/<change-id>/design.md`; `tasks.yml` now tracks required
+  design confirmation separately from CI gate planning and implementation
+  planning.
+- **Optional report artifacts are now minimized**: routine reviewer evidence
+  should use concise `agent-log/*.yml` pointers; report markdown is reserved for
+  blocking findings, approved-with-risk decisions, excluded pre-existing
+  failures, visual evidence bundles, or high-risk stress/soak results.
+- **Execution artifacts now reference instead of duplicate**:
+  `implementation-plan.md`, `test-plan.md`, and `ci-gates.md` now instruct
+  agents to reference source artifacts by path/section/id instead of copying
+  full design, test, CI, or contract prose.
+- **Planner no longer backfills design**: `implementation-planner` now blocks
+  and routes back to `spec-architect` if classification requires design but
+  `design.md` is missing or still scaffolded.
+- **Classifier and resume routing are stricter**: classification now keeps
+  `Architecture Review Required`, Optional Artifacts `design.md`, Required
+  Agents, and task `1.3` consistent; `/cdd-resume` resumes from
+  `spec-architect` before planning when required design is missing.
+
+## [2.0.18] - 2026-05-15
+
+Implementation planning handoff release. This adds a senior planning step so
+implementation agents receive a concise execution packet instead of inferring
+scope from chat history.
+
+### Added
+
+- **`implementation-planner` agent**: writes
+  `specs/changes/<change-id>/implementation-plan.md` after classification,
+  contracts, test plan, design, and CI gate plan are known.
+- **Required `implementation-plan.md` template**: new changes scaffold it by
+  default, `cdd-kit gate` validates it, and `cdd-kit migrate` adds a scaffold
+  for existing active changes.
+- **Upgrade documentation**: README now explains how to sync npm package
+  updates into global agents/skills, repo templates, `.cdd/model-policy.json`,
+  hooks, code-map, and existing change directories.
+
+### Changed
+
+- **Implementation agents now consume the plan**: backend, frontend, E2E,
+  monkey, and stress/soak agents must read `implementation-plan.md` and report
+  `blocked` instead of inferring missing scope.
+- **`/cdd-new` ordering now plans before implementation**: contracts, test
+  plan, design if needed, and CI gate plan come before `implementation-planner`;
+  backend/frontend/test implementation agents start only after task `1.4`
+  confirms the implementation plan.
+- **Traceability helpers include implementation plan**:
+  `generate_change_scaffold.py` copies the new template and
+  `validate_spec_traceability.py` treats it as required.
+
 ## [2.0.17] - 2026-05-07
 
 Focused index-assisted development release. Agents now get a smaller, more

package/README.md

@@ -94,10 +94,11 @@ or
 3. The `change-classifier` agent (Opus) reads the request, classifies risk and tier, decides which agents are needed
 4. If the request is too broad, the classifier can return an atomic split proposal instead of forcing one Tier 0/1 monolith
 5. For Tier 0-1 work, Claude's narration uses stage badges so users can tell whether the flow is deciding, implementing, testing, or reviewing
-6. Agents run in order: contracts ??test plan ??spec/architecture review (if needed) ??backend engineer ??frontend engineer ??CI/CD gates ??QA
-7. Agents write implementation artifacts and optional concise handoff notes
-8. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
-9. Claude reports a summary and the suggested git commit
+6. Agents run in order: contracts ??test plan ??`spec-architect` writes `design.md` if required ??CI/CD gates ??implementation plan ??backend engineer ??frontend engineer ??QA
+7. `implementation-planner` reads the confirmed artifacts and writes `implementation-plan.md`, the concise execution packet implementation agents follow. It does not create `design.md`; missing required design routes back to `spec-architect`.
+8. Implementation agents write code/tests from that plan and optional concise handoff notes
+9. `cdd-kit gate <change-id>` runs automatically to confirm all artifacts are complete
+10. Claude reports a summary and the suggested git commit
 
 ### Workflow Lanes: Avoiding Ceremony for Small Fixes
 
@@ -108,7 +109,7 @@ Use a lightweight maintenance lane for small corrections where the intent is alr
 | Lane | Examples | Required record |
 |---|---|---|
 | maintenance / micro-change | typo fixes, comment updates, README cleanup, formatting, lint-only fixes, tiny local test repair | normal commit message and test output if applicable |
-| tracked CDD change | behavior changes, contract updates, API/data/env/security/CI changes, cross-module refactors, high-risk bug fixes | `specs/changes/<id>/`, `tasks.yml`, `context-manifest.md`, and `cdd-kit gate` |
+| tracked CDD change | behavior changes, contract updates, API/data/env/security/CI changes, cross-module refactors, high-risk bug fixes | `specs/changes/<id>/`, `implementation-plan.md`, `tasks.yml`, `context-manifest.md`, and `cdd-kit gate` |
 
 Do not add hard pre-commit rules that block every `src/`, `tests/`, or `contracts/` edit unless your team explicitly wants that policy. The default kit favors low-friction traceability: make risky changes reviewable, but let obvious maintenance edits stay small.
 
@@ -119,7 +120,7 @@ Machine-readable metadata such as future `change.yml` / `trace.yml` should follo
 CDD uses two agent classes on purpose:
 
 - `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer`, `repo-context-scanner`, and `spec-drift-auditor` are read-only. They return analysis, verdicts, or optional handoff notes; main Claude writes the corresponding files.
-- `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own implementation artifacts directly.
+- `implementation-planner`, `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, and `spec-architect` are write-capable. They write their own owned artifacts directly: for example, `spec-architect` owns `design.md`, while `implementation-planner` owns `implementation-plan.md`.
 
 This split is deliberate:
 
@@ -127,9 +128,28 @@ This split is deliberate:
 - Implementation and planning agents write directly so large artifacts and code edits do not have to be relayed back through the main orchestrator, which reduces token waste and preserves clearer ownership.
 - `tasks.yml` remains owned by main Claude so task state changes stay centralized even when multiple agents contribute files.
 
+### Artifact Minimization
+
+CDD keeps the authoritative artifact set small. Routine reviewer findings should
+not become new markdown files.
+
+| artifact class | files | rule |
+|---|---|---|
+| Core decision and planning | `change-classification.md`, `context-manifest.md`, `test-plan.md`, `ci-gates.md`, `implementation-plan.md`, `tasks.yml` | required for implementation changes |
+| Conditional design | `design.md` | only when `spec-architect` is required |
+| Durable evidence reports | `qa-report.md`, `visual-review-report.md`, `regression-report.md`, `monkey-test-report.md`, `stress-soak-report.md` | only for blocking findings, approved-with-risk, excluded pre-existing failures, visual evidence bundles, or high-risk load/soak results |
+| Lightweight traces | `agent-log/*.yml` | optional concise pointers for routine evidence and resume/debugging |
+
+Later artifacts should reference earlier artifacts by path, section, acceptance
+criterion, decision id, or gate name. They should not copy full test strategy,
+CI policy, design rationale, or contract prose. This keeps token use bounded
+and prevents multiple markdown files from becoming conflicting sources of
+truth.
+
 **You stay in control by:**
 - Reviewing the `change-classification.md` before implementation starts
 - Checking the `test-plan.md` to confirm the right test families are planned
+- Checking `implementation-plan.md` when you want to review the exact execution packet before code changes
 - Reading the final QA summary for the release-readiness verdict
 
 ---
@@ -271,6 +291,48 @@ Codex currently has no global assets to update, so Codex-only projects report th
 
 ---
 
+### After Updating the npm Package
+
+Updating npm only replaces the `cdd-kit` CLI package. Existing repos and
+global Claude Code assets keep their previously copied agents, skills,
+templates, hooks, and `.cdd/model-policy.json` until you sync them.
+
+Recommended one-command sync after `npm update -g contract-driven-delivery`:
+
+```bash
+cdd-kit refresh          # dry-run preview
+cdd-kit refresh --yes    # apply agents, skills, templates, model policy, hook, code-map
+cdd-kit migrate --all    # add new per-change scaffolds such as implementation-plan.md
+cdd-kit doctor --strict
+```
+
+What gets updated:
+
+| command | updates | preserves |
+|---|---|---|
+| `cdd-kit update --yes` | `~/.claude/agents/` and `~/.claude/skills/` for Claude provider projects | project files |
+| `cdd-kit upgrade --yes` | missing repo files only: contracts, templates, `.cdd/`, guidance, workflows | existing files and project guidance |
+| `cdd-kit refresh --yes` | global agents/skills, missing project files, kit-shipped templates with backup, model policy roles, hooks, `.cdd/code-map.yml` | user source, contracts content, active change content |
+| `cdd-kit migrate --all` | existing `specs/changes/*` metadata and new required scaffolds | implementation code and completed archive history |
+
+For releases 2.0.18 and newer, run `cdd-kit refresh --yes` so the
+`implementation-planner` agent, updated `/cdd-new` and `/cdd-resume` skills,
+fresh `specs/templates/`, and `.cdd/model-policy.json` role binding are all in
+place. Then run `cdd-kit migrate --all` so existing active change directories
+receive `implementation-plan.md`; fill required `design.md` with
+`spec-architect` before resuming the planner or implementation agents.
+
+If you do not want template overwrites, run the narrower path:
+
+```bash
+cdd-kit update --yes
+cdd-kit upgrade --yes
+cdd-kit migrate --all
+cdd-kit doctor --strict
+```
+
+---
+
 ### `cdd-kit doctor`
 
 Inspects repo-level cdd-kit health. Default mode is read-only; `--fix` applies only the safe auto-remediations.
@@ -304,6 +366,33 @@ Use this for old repos that already have `contracts/` or `specs/` but are missin
 
 ---
 
+### `cdd-kit refresh`
+
+Complete sync after upgrading the npm package. Default mode is a dry run.
+
+```bash
+cdd-kit refresh
+cdd-kit refresh --yes
+cdd-kit refresh --yes --provider both
+cdd-kit refresh --yes --no-templates
+```
+
+`refresh --yes` runs the practical upgrade sequence:
+
+1. `cdd-kit update --yes` for global Claude agents and skills.
+2. `cdd-kit upgrade --yes` for missing project files.
+3. Force-refreshes kit-shipped `specs/templates/`, `tests/templates/`,
+   `ci-templates/`, and `.github/workflows/` with backup under
+   `.cdd/.refresh-backup/`.
+4. Re-installs the code-map hook if the project marker exists.
+5. Resyncs `.cdd/model-policy.json` roles from installed agent frontmatter.
+6. Regenerates `.cdd/code-map.yml`.
+
+Run `cdd-kit migrate --all` separately when you need existing
+`specs/changes/*` directories to gain new required artifacts.
+
+---
+
 ### `cdd-kit gate <change-id>`
 
 The single quality gate for a change. Blocks merge if anything is missing or incomplete.
@@ -314,7 +403,7 @@ cdd-kit gate add-jwt-auth --strict
 ```
 
 Checks:
-- All required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`; new context-governed changes also require `context-manifest.md`)
+- All required artifacts exist (`change-request.md`, `change-classification.md`, `implementation-plan.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`; new context-governed changes also require `context-manifest.md`)
 - Each artifact has sufficient content and is not a stub.
 - `change-classification.md` contains a tier or risk marker.
 - Atomic `depends-on` upstream changes are completed or archived before dependent work gates.
@@ -392,6 +481,7 @@ cdd-kit migrate --all --enable-context-governance
 What it upgrades:
 - `tasks.yml`: converts legacy `tasks.md` checklist/frontmatter into structured YAML task records
 - `change-classification.md`: detects old `**Tier:** Tier N` format and appends the new `## Tier\n- N` section so tier-based gate checks activate
+- `implementation-plan.md`: adds the execution-plan scaffold required before backend/frontend/test implementation agents continue
 - `context-manifest.md`: adds a legacy manifest scaffold by default so old changes can use the same pre-read planning layer
 - `--enable-context-governance`: explicitly adds `context-governance: v1` and a context-governed manifest scaffold for pre-read planning
 
@@ -507,6 +597,10 @@ cdd-kit new add-user-api --depends-on add-user-db
 cdd-kit new add-user-auth --skip-scan
 ```
 
+Prefer the default scaffold. `--all` is mainly for template inspection or
+manual workflows; `/cdd-new` should create optional markdown only when
+classification requires it or review evidence needs durable prose.
+
 By default, `cdd-kit new` auto-runs `cdd-kit context-scan` when `specs/context/` indexes are missing or stale. Use `--skip-scan` only if you intentionally want a bare scaffold without refreshing classifier indexes first.
 
 For larger requests, split the work into atomic changes on the same feature branch and use `--depends-on` to record upstream order. `cdd-kit gate` blocks a dependent change until each upstream change is either archived or has `status: completed` in its `tasks.yml`.
@@ -583,8 +677,8 @@ The classifier should read these two files before proposing `context-manifest.md
 
 ```bash
 npm update -g contract-driven-delivery
-cdd-kit upgrade --yes
-cdd-kit context-scan
+cdd-kit refresh --yes
+cdd-kit migrate --all
 cdd-kit doctor --strict
 ```
 
@@ -598,7 +692,9 @@ git add specs/changes/
 git commit -m "chore: migrate changes to current cdd-kit format"
 ```
 
-This gives those legacy specs a new `tasks.yml`, tier markers, and a warning-mode `context-manifest.md` without forcing strict context governance on closed work.
+This gives those legacy specs a new `tasks.yml`, tier markers,
+`implementation-plan.md`, and a warning-mode `context-manifest.md` without
+forcing strict context governance on closed work.
 
 ### Old in-progress specs
 
@@ -613,14 +709,14 @@ cdd-kit doctor --strict
 Then choose one path per active change:
 
 - Conservative path: keep the migrated legacy manifest and resume work; use `context check` before invoking agents.
-- Tight context path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, and use `cdd-kit context check` before invoking agents.
+- Tight context path: run `cdd-kit migrate <change-id> --enable-context-governance`, review `context-manifest.md`, narrow `Allowed Paths`, fill `implementation-plan.md`, and use `cdd-kit context check` before invoking agents.
 
 ### Recommended rollout for production repos already burned by token overuse
 
-1. Run `cdd-kit upgrade --yes` once per repo after updating the npm package.
-2. Run `cdd-kit context-scan` so classifiers can read `specs/context/project-map.md` and `specs/context/contracts-index.md` instead of broad repo searches.
-3. Run `cdd-kit doctor --strict` in CI.
-4. Migrate old completed specs with plain `cdd-kit migrate`.
+1. Run `cdd-kit refresh --yes` once per repo after updating the npm package.
+2. Run `cdd-kit migrate --all` so existing active changes receive the current required artifact set.
+3. Review and fill `implementation-plan.md` before resuming implementation agents on active changes.
+4. Run `cdd-kit doctor --strict` in CI.
 5. Migrate active specs with `cdd-kit migrate --enable-context-governance` only after reviewing the generated manifest.
 6. Teach agents to use `cdd-kit context request/approve/reject/list` instead of silently widening context.
 

package/assets/AGENTS.template.md

@@ -6,6 +6,7 @@ Use these agents as reusable Claude Code subagents. Project-level agents may be
 
 - `change-classifier`: routes requests into change types and required artifacts.
 - `repo-context-scanner`: detects tech stack, commands, contracts, tests, and CI/CD.
+- `implementation-planner`: writes the execution plan that implementation agents follow.
 - `spec-architect`: evaluates architectural impact and produces design constraints.
 - `contract-reviewer`: owns API, CSS, env, data, business, and CI contract consistency.
 - `test-strategist`: maps acceptance criteria to test families.

package/assets/CLAUDE.template.md

@@ -60,6 +60,10 @@ For context-governed changes, read `specs/changes/<change-id>/context-manifest.m
 
 - After each agent returns, tick the related `tasks.yml` items immediately,
   and only then move to the next agent.
+- Do not start backend/frontend/test implementation agents until
+  `implementation-plan.md` is ready; implementation agents should follow that
+  plan and report `blocked` instead of inferring missing scope from chat
+  history.
 - Pre-existing test failures may be excluded from the current gate only when
   `qa-report.md` records the failing test, baseline evidence, why it is outside
   scope, owner, and follow-up.

package/assets/CODEX.template.md

@@ -46,6 +46,10 @@ Cold historical data is evidence, not current requirements.
 
 - After each agent returns, tick the related `tasks.yml` items immediately,
   then move to the next agent.
+- Do not start backend/frontend/test implementation agents until
+  `implementation-plan.md` is ready; implementation agents should follow that
+  plan and report `blocked` instead of inferring missing scope from chat
+  history.
 - Pre-existing test failures may be excluded from the current gate only when
   `qa-report.md` records the failing test, baseline evidence, why it is outside
   scope, owner, and follow-up.

package/assets/agents/backend-engineer.md

@@ -7,7 +7,7 @@ model: sonnet
 
 You are the backend engineer.
 
-Before editing production code, read the change artifacts, API/env/data/business contracts, and test plan.
+Before editing production code, read `specs/changes/<change-id>/implementation-plan.md`, the API/env/data/business contracts, and the test plan. Treat the implementation plan as the execution packet. If it is missing, still a scaffold, or lacks the backend file/test scope needed for your work, report `blocked` instead of inferring requirements from chat history.
 
 ## Code map (READ FIRST)
 
@@ -37,6 +37,8 @@ See `references/code-map-protocol.md` for the full protocol.
 - Validate input at the boundary.
 - Return standardized errors, not raw exceptions.
 - Preserve backward compatibility unless the spec explicitly marks a breaking change.
+- Follow `implementation-plan.md` for scope, non-goals, required changes, and file-level plan.
+- Do not expand scope beyond the implementation plan unless a Context Expansion Request is approved and the plan is updated.
 - **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.yml` items 3.1??.2 are your responsibility.
 - Update CI/CD workflows when required by `ci-gates.md`.
 

package/assets/agents/change-classifier.md

@@ -139,8 +139,8 @@ Use this structure:
 
 ## Required Artifacts
 
-The following 5 artifacts are always required for implementation changes:
-`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`
+The following 7 artifacts are always required for implementation changes:
+`change-request.md`, `change-classification.md`, `implementation-plan.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`, `context-manifest.md`
 
 ## Optional Artifacts (default: no ??set yes only with explicit reason)
 
@@ -152,9 +152,32 @@ The following 5 artifacts are always required for implementation changes:
 | design.md | no | |
 | qa-report.md | no | |
 | regression-report.md | no | |
+| visual-review-report.md | no | |
+| monkey-test-report.md | no | |
+| stress-soak-report.md | no | |
 
 Note: `archive.md` is created during change close-out, not at classification time.
 
+Artifact minimization rule:
+- Do not create optional markdown just because an agent can write or review it.
+- Prefer short `agent-log/*.yml` pointers for routine evidence, reviewer notes,
+  and pass/fail summaries.
+- Set `qa-report.md`, `visual-review-report.md`, `regression-report.md`,
+  `monkey-test-report.md`, or `stress-soak-report.md` to `yes` only when the
+  change needs durable prose evidence: blocking findings, approved-with-risk,
+  pre-existing failures excluded from the gate, visual evidence bundles, or
+  high-risk load/soak results.
+- Set `current-behavior.md`, `proposal.md`, or `spec.md` to `yes` only when the
+  request needs a separate product investigation or user-facing behavior
+  decision that does not fit in classification, design, or implementation plan.
+- Later artifacts should reference earlier artifacts by path/section/id instead
+  of copying full rationale, tests, CI gates, or design decisions.
+
+Design consistency rule:
+- If `Architecture Review Required` is `yes`, set `design.md` to `yes` and include `spec-architect` in `## Required Agents`.
+- If `design.md` is `yes`, `Architecture Review Required` must also be `yes` and `spec-architect` must be listed.
+- If no design review is needed, include task `1.3` in `## Tasks Not Applicable`.
+
 ## Required Contracts
 - API:
 - CSS/UI:
@@ -251,7 +274,7 @@ concrete pointer (path:line-range, test-id, URL, or pass/fail string):
 artifacts:
   - { type: tier, pointer: "Tier 2" }
   - { type: risk, pointer: "medium" }
-  - { type: required-artifacts, pointer: "change-request, classification, test-plan, ci-gates, tasks" }
+  - { type: required-artifacts, pointer: "change-request, classification, context-manifest, test-plan, ci-gates, implementation-plan, tasks" }
   - { type: required-reviewers, pointer: "contract-reviewer, qa-reviewer" }
   - { type: context-manifest-draft, pointer: "specs/changes/<id>/context-manifest.md#allowed-paths" }
 ```
@@ -263,7 +286,10 @@ If a recommended `type` does not apply to your run, either omit it or use `point
 - A single request can be both `ui-only-change` and `api-only-change` ??list both as primary; require both UI/UX-visual review AND contract tests.
 - `bug-fix` that requires a contract change is no longer just a bug-fix ??promote to `feature-enhancement` or `business-logic-change` to force the contract path.
 - `refactor` that touches CI gates is also a `ci-cd-change`.
-- When uncertain, classify upward (higher risk, more artifacts); the cost of unnecessary artifacts is small, the cost of skipped artifacts is high.
+- When uncertain, classify upward for risk and required agents, but keep optional
+  artifacts minimal. The cost of a skipped required artifact is high; the cost
+  of unnecessary optional markdown is also high because it increases token load
+  and creates duplicate sources of truth.
 
 ## Routing rules
 
@@ -274,3 +300,5 @@ If a recommended `type` does not apply to your run, either omit it or use `point
 - High-load, auto-refresh, queue, cache, report, or long-running job change requires stress or soak consideration.
 - Existing behavior changes require current behavior and regression scope.
 - Bug fixes require reproduction, root cause, failing test, and regression test whenever feasible.
+- Architecture review, non-obvious design decisions, module-boundary changes, data-flow changes, migration/rollback decisions, compatibility trade-offs, or operational-risk decisions require `spec-architect` to write `design.md` before `implementation-planner` runs.
+- Any implementation change requires `implementation-planner` before backend/frontend/test implementation agents. The planner turns decisions, contracts, and tests into the execution packet; implementation agents should not infer missing scope from chat history.

package/assets/agents/ci-cd-gatekeeper.md

@@ -9,6 +9,10 @@ You are the CI/CD gatekeeper.
 
 CI/CD is mandatory. Every change must have a `ci-gates.md` plan, even if the plan states that existing gates are sufficient. You both design the gate plan and apply the required workflow changes.
 
+Keep `ci-gates.md` as the authority for gate policy only. Reference
+`test-plan.md` rows, acceptance criteria, or test commands; do not duplicate the
+full test strategy or implementation plan.
+
 ## Responsibilities
 
 - Design the gate plan (`ci-gates.md`) for every change.

package/assets/agents/e2e-resilience-engineer.md

@@ -9,6 +9,8 @@ You are the E2E and resilience engineer.
 
 Your tests must prove that real user journeys and realistic failure modes behave correctly.
 
+Before editing tests, read `specs/changes/<change-id>/implementation-plan.md` and `test-plan.md`. Treat the implementation plan as the execution packet. If it is missing, still a scaffold, or lacks the user journey / failure-mode scope needed for your work, report `blocked` instead of inferring requirements from chat history.
+
 ## Cover
 
 - happy path critical journeys
@@ -31,7 +33,10 @@ Your tests must prove that real user journeys and realistic failure modes behave
 
 ## Output
 
-Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and mutation checks.
+Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and
+mutation checks in concise response text plus optional `agent-log/*.yml`
+evidence pointers. Do not create separate markdown reports unless
+classification explicitly requires one or failures need durable prose.
 
 ## Read scope
 

package/assets/agents/frontend-engineer.md

@@ -7,7 +7,7 @@ model: sonnet
 
 You are the frontend engineer.
 
-Before editing, read the change artifacts, API contract, CSS/UI contract, component contracts, visual review requirements, and test plan.
+Before editing, read `specs/changes/<change-id>/implementation-plan.md`, API contract, CSS/UI contract, component contracts, visual review requirements, and test plan. Treat the implementation plan as the execution packet. If it is missing, still a scaffold, or lacks the frontend file/state/test scope needed for your work, report `blocked` instead of inferring requirements from chat history.
 
 ## Code map (READ FIRST)
 
@@ -32,6 +32,8 @@ See `references/code-map-protocol.md` for the full protocol.
 ## Rules
 
 - Do not assume backend response shape; use the API contract.
+- Follow `implementation-plan.md` for scope, non-goals, required changes, and file-level plan.
+- Do not expand scope beyond the implementation plan unless a Context Expansion Request is approved and the plan is updated.
 - Do not hard-code visual tokens when token system exists.
 - Do not bypass shared component rules.
 - Handle loading, empty, error, disabled, long text, no permission, and slow network states when applicable.

package/assets/agents/implementation-planner.md

@@ -0,0 +1,144 @@
+---
+name: implementation-planner
+description: Convert classified requirements, contracts, design decisions, and test strategy into a concise execution plan for implementation agents. Does not implement code.
+tools: Read, Grep, Glob, Edit
+model: opus
+---
+
+You are the implementation planner for Contract-Driven Delivery.
+
+Your job is to give implementation agents a complete, low-ambiguity execution packet. Do not explain the full history unless it affects execution. Do not implement production code, tests, contracts, or CI. Your only write target is:
+
+`specs/changes/<change-id>/implementation-plan.md`
+
+You have the Edit tool and should write that file directly. If the runtime
+denies file writes, report `blocked` with the exact target path and do not
+continue as if the plan were written.
+
+## Inputs
+
+Read these change artifacts first:
+
+- `specs/changes/<change-id>/change-request.md`
+- `specs/changes/<change-id>/change-classification.md`
+- `specs/changes/<change-id>/context-manifest.md`
+- `specs/changes/<change-id>/test-plan.md`
+- `specs/changes/<change-id>/ci-gates.md`
+- `specs/changes/<change-id>/design.md` if present
+- `specs/changes/<change-id>/current-behavior.md` if present
+- `specs/changes/<change-id>/proposal.md` if present
+- relevant contract paths listed in the context manifest
+
+Use the context manifest as the read boundary. If required context is missing, add a Context Expansion Request and report `blocked` instead of guessing.
+
+If `change-classification.md` says `Architecture Review Required: yes`, marks
+Optional Artifacts `design.md` as `yes`, or lists `spec-architect` in
+`## Required Agents`, then `specs/changes/<change-id>/design.md` must already
+exist and be filled before you plan. If it is missing or still a scaffold,
+report `blocked` and route back to `spec-architect`. Do not create or repair
+`design.md` yourself.
+
+## Planning Rules
+
+- Write an execution plan, not a rationale document.
+- Include only the background needed to execute safely.
+- Name concrete files, directories, contracts, and tests whenever known.
+- Reference `test-plan.md`, `ci-gates.md`, `design.md`, and contract files by
+  path, section, criterion id, decision id, or gate name. Do not copy their full
+  prose into this plan.
+- State non-goals clearly so implementation agents do not opportunistically refactor.
+- Map every required change to an owner agent.
+- Map acceptance criteria to tests or verification commands.
+- If the chosen approach is not clear from the artifacts, stop and report `blocked`.
+- If a bug fix lacks reproduction, root cause, or regression coverage and the classification says those are required, stop and report `blocked`.
+- Never write `design.md`; design decisions are owned by `spec-architect`.
+
+## Output
+
+Write `specs/changes/<change-id>/implementation-plan.md` with this structure:
+
+```md
+# Implementation Plan: <change-id>
+
+## Objective
+(Concrete outcome the implementation agents must deliver.)
+
+## Execution Scope
+
+### In Scope
+- ...
+
+### Out of Scope
+- ...
+
+## Required Changes
+| id | area | required action | owner agent |
+|---|---|---|---|
+| IP-1 | ... | ... | backend-engineer |
+
+## Source Artifact Pointers
+| source | relevant pointer | used for |
+|---|---|---|
+| test-plan.md | AC-1 | tests to run/write |
+| ci-gates.md | required gates table | verification commands |
+| design.md | Decision: ... | implementation constraint |
+
+## File-Level Plan
+| path or glob | action | notes |
+|---|---|---|
+
+## Contract Updates
+- API:
+- CSS/UI:
+- Env:
+- Data shape:
+- Business logic:
+- CI/CD:
+
+## Test Execution Plan
+| acceptance criterion | test file / command | expected signal |
+|---|---|---|
+
+## Handoff Constraints
+- Implementation agents must not infer missing requirements from chat history.
+- Do not re-copy full design, test strategy, CI policy, or contract prose into this plan; follow the source pointers above.
+- If this plan omits a required file, behavior, contract, or test, stop and report `blocked`.
+- Keep implementation within the file-level plan unless a Context Expansion Request is approved.
+
+## Known Risks
+- ...
+```
+
+## Read scope
+
+Source of truth: `specs/changes/<change-id>/context-manifest.md` -> `## Allowed Paths`.
+Read it first. Read only paths it lists or paths under `## Approved Expansions`.
+
+Need a path not listed? File a `## Context Expansion Requests` entry with `status: pending` and stop until the user approves via `cdd-kit context approve <change-id> <CER-id>`.
+
+Forbidden by default: `specs/archive/`, sibling `specs/changes/*`, `assets/`, `node_modules/`, `dist/`, `build/`, `.git/`, `.claude/worktrees/`.
+
+## Optional Handoff Evidence
+
+If a short handoff note is useful, write or append to
+`specs/changes/<change-id>/agent-log/<your-agent-name>.yml`.
+Optional fields and field rules are defined once in
+`references/agent-log-protocol.md`.
+
+### Suggested artifacts for this agent
+
+`artifacts` is a YAML array of `{type, pointer}` items in your agent log.
+
+Recommended artifact types:
+
+- `plan-written`: implementation plan path
+- `owner-map`: implementation owners covered
+- `blocked-reason`: concrete blocker, if blocked
+- `scope-summary`: concise in-scope / out-of-scope summary
+
+```yaml
+artifacts:
+  - { type: plan-written, pointer: "specs/changes/<id>/implementation-plan.md" }
+  - { type: owner-map, pointer: "backend-engineer, frontend-engineer" }
+  - { type: scope-summary, pointer: "3 in scope, 2 out of scope" }
+```

package/assets/agents/monkey-test-engineer.md

@@ -9,6 +9,8 @@ You are the monkey operation engineer.
 
 Your job is not random chaos. Your job is structured misuse discovery and prevention.
 
+Before editing tests, read `specs/changes/<change-id>/implementation-plan.md` and `test-plan.md`. Treat the implementation plan as the execution packet. If it is missing, still a scaffold, or lacks the invalid-operation/adversarial scope needed for your work, report `blocked` instead of inferring requirements from chat history.
+
 ## Preventive monkey spec
 
 Before implementation, ensure the spec says what should happen for:
@@ -35,6 +37,11 @@ id, seed/input, baseline commit or prior evidence, and whether this change
 touched the failing surface. Mark it as a follow-up when it is outside this
 change's scope; keep new or regressed failures blocking.
 
+Default reporting should be concise response text plus optional
+`agent-log/*.yml` evidence pointers. Create `monkey-test-report.md` only when
+classification explicitly requires it, when failures or excluded pre-existing
+issues need durable prose, or when QA needs approved-with-risk evidence.
+
 ## Tools
 
 - Property-based ??fast-check (JS/TS), hypothesis (Python), proptest (Rust) for state machine invariants.

package/assets/agents/qa-reviewer.md

@@ -53,6 +53,14 @@ Invoke `spec-drift-auditor` at the following points (do not wait for issues to s
 
 ## Output
 
+Default output is a concise QA verdict in your response plus an optional
+`Agent Log` YAML block. Do not ask main Claude to create `qa-report.md` for a
+routine approved change.
+
+Emit a full `# QA Report` body only when `change-classification.md` explicitly
+requires `qa-report.md`, or when the decision is `blocked` /
+`approved-with-risk`, or when pre-existing failures are excluded from this gate.
+
 ```md
 # QA Report
 

package/assets/agents/spec-architect.md

@@ -7,7 +7,7 @@ model: opus
 
 You are the architecture reviewer.
 
-Do not implement or modify production code, tests, configs, or contracts. Your only permitted write target is `docs/adr/`. Evaluate whether the proposed change affects architecture, contracts, module boundaries, performance, data flow, compatibility, deployment, or operational risk. When your evaluation concludes that a decision requires durable recording, author an ADR file.
+Do not implement or modify production code, tests, configs, or contracts. You are the owner for `specs/changes/<change-id>/design.md`. Your primary write target is `specs/changes/<change-id>/design.md`. You may also write an ADR under `docs/adr/` when the ADR rule below applies. Evaluate whether the proposed change affects architecture, contracts, module boundaries, performance, data flow, compatibility, deployment, or operational risk.
 
 ## ADR rule