contract-driven-delivery 2.0.17 → 2.0.18

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [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/architecture review (if needed) ??CI/CD gates ??implementation plan ??backend engineer ??frontend engineer ??QA
+7. `implementation-planner` writes `implementation-plan.md`, the concise execution packet implementation agents follow
+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 implementation artifacts directly.
 
 This split is deliberate:
 
@@ -130,6 +131,7 @@ This split is deliberate:
 **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 +273,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 this release, run `cdd-kit refresh --yes` so the new
+`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 that plan before resuming 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 +348,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 +385,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 +463,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
 
@@ -583,8 +655,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 +670,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 +687,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)
 
@@ -274,3 +274,4 @@ 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.
+- 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/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

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,121 @@
+---
+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`
+
+## 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.
+
+## 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.
+- 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`.
+
+## 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 |
+
+## 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.
+- 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:

package/assets/agents/stress-soak-engineer.md

@@ -9,6 +9,8 @@ You are the stress and soak engineer.
 
 Use realistic load profiles rather than arbitrary request loops.
 
+Before editing tests or load profiles, 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 workload/threshold scope needed for your work, report `blocked` instead of inferring requirements from chat history.
+
 ## Design dimensions
 
 - user concurrency

package/assets/cdd/model-policy.json

@@ -4,6 +4,7 @@
   "schema-version": "0.2.0",
   "roles": {
     "change-classifier": "opus",
+    "implementation-planner": "opus",
     "spec-architect": "opus",
     "qa-reviewer": "opus",
     "contract-reviewer": "sonnet",

package/assets/skills/cdd-new/SKILL.md

@@ -92,7 +92,7 @@ inevitable re-classification when the agents discover the ambiguity.
 | Agent type | Who writes artifact files | Who writes optional handoff notes | Who updates tasks.yml |
 |------------|--------------------------|----------------------------------|----------------------|
 | Read-only agents (no Edit tool): `change-classifier`, `contract-reviewer`, `qa-reviewer`, `visual-reviewer`, `dependency-security-reviewer`, `ui-ux-reviewer` | YOU (main Claude) | YOU, only when useful | YOU (main Claude) |
-| Write-capable agents (have Edit): `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, `spec-architect` | The agent itself | The agent itself, only when useful | YOU (main Claude) |
+| Write-capable agents (have Edit): `implementation-planner`, `backend-engineer`, `frontend-engineer`, `e2e-resilience-engineer`, `monkey-test-engineer`, `stress-soak-engineer`, `ci-cd-gatekeeper`, `test-strategist`, `spec-architect` | The agent itself | The agent itself, only when useful | YOU (main Claude) |
 
 **Rule**: After EVERY agent completes (whether it writes itself or you write for it), YOU must update the relevant `tasks.yml` task `status:` from `pending` to `done`.
 
@@ -118,7 +118,7 @@ Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` ??it is
 
 If the classifier marks an artifact as `no` or leaves it blank, **do not create the file** ??even if a review agent could contribute to it.
 
-The 6 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`, and `context-manifest.md`.
+The 7 always-required artifacts are: `change-request.md`, `change-classification.md`, `implementation-plan.md`, `test-plan.md`, `ci-gates.md`, `tasks.yml`, and `context-manifest.md`.
 
 ## Step 1: Generate change-id, scaffold, and scan context
 
@@ -158,6 +158,7 @@ the kit and is bundled into every install.
 |---|---|---|
 | `change-request.md` | `specs/templates/change-request.md` | Fill the `## Original Request` section with the user's exact description before invoking the classifier; leave the rest blank |
 | `change-classification.md` | `specs/templates/change-classification.md` | Replace blank template with classifier output (Step 2) |
+| `implementation-plan.md` | `specs/templates/implementation-plan.md` | `implementation-planner` writes this directly after contracts, tests, design, and CI gate plan are known |
 | `test-plan.md` | `specs/templates/test-plan.md` | `test-strategist` writes this directly |
 | `ci-gates.md` | `specs/templates/ci-gates.md` | `ci-cd-gatekeeper` writes this directly |
 | `tasks.yml` | `specs/templates/tasks.yml` | Tick checkboxes as agents complete; backfill `tier:` frontmatter from classifier (Step 2.4) |
@@ -283,6 +284,7 @@ the user; do not put them inside the prompt sent to the agent.
 |---|---|---|
 | Decision | `change-classifier` | ? `[classifier]` |
 | Decision | `spec-architect` | ? `[architect]` |
+| Decision | `implementation-planner` | ? `[plan]` |
 | Implementation | `backend-engineer` | ? `[backend]` |
 | Implementation | `frontend-engineer` | ? `[frontend]` |
 | Implementation | `ci-cd-gatekeeper` | ? `[ci-cd]` |
@@ -349,32 +351,37 @@ prompt; the agent's behavior is defined by the agent prompt files in
 3. **`spec-architect`** (write-capable) ??only if `change-classification.md` contains `Architecture Review Required: yes`.
    - YOU tick: `1.3` (if it produced a gate plan)
 
-4. **`backend-engineer`** (write-capable) ??if the change touches server, API, data, or business logic. Writes implementation directly; may write an optional handoff note.
+4. **`ci-cd-gatekeeper`** (write-capable) ??writes `specs/changes/<change-id>/ci-gates.md` directly before implementation planning.
+   - YOU tick: `1.3`, `4.4`, applicable items in section 6
+
+5. **`implementation-planner`** (write-capable) ??writes `specs/changes/<change-id>/implementation-plan.md` directly after classification, contracts, test plan, design, and CI gate plan are available.
+   - This is the handoff packet for implementation agents. It should contain execution scope, non-goals, required changes, file-level plan, contract updates, test execution plan, and constraints.
+   - If it reports `blocked`, halt and surface the missing decision/context to the user.
+   - YOU tick: `1.4`
+
+6. **`backend-engineer`** (write-capable) ??if the change touches server, API, data, or business logic. Writes implementation directly; may write an optional handoff note.
    - YOU tick: `4.1` and/or `4.3` based on scope
    - Note: `tasks.yml` items 3.1??.2 (unit/contract/integration tests) are written by `backend-engineer` and/or `frontend-engineer` in TDD fashion ??failing tests first, implementation second. Items 3.3??.5 are written by dedicated test engineers (Tier 0?? only or when classifier explicitly requires them).
 
-5. **`frontend-engineer`** (write-capable) ??if the change touches UI, components, or client-side behavior. Writes implementation directly; may write an optional handoff note.
+7. **`frontend-engineer`** (write-capable) ??if the change touches UI, components, or client-side behavior. Writes implementation directly; may write an optional handoff note.
    - YOU tick: `4.2`
 
-6. **`dependency-security-reviewer`** (read-only) ??if the change touches lockfiles, package manifests, or DB migrations.
+8. **`dependency-security-reviewer`** (read-only) ??if the change touches lockfiles, package manifests, or DB migrations.
    - **Only invoke if** `change-classification.md` lists lockfiles, package manifests, or DB migrations as affected.
    - Optional handoff note: `agent-log/dependency-security-reviewer.yml`
    - YOU tick: applicable security-related items
 
-7. **`ui-ux-reviewer`** (read-only) ??if any UI change (run alongside or after frontend-engineer).
+9. **`ui-ux-reviewer`** (read-only) ??if any UI change (run alongside or after frontend-engineer).
    - **Only invoke if** classifier marks UI/CSS as affected.
    - Optional handoff note: `agent-log/ui-ux-reviewer.yml`
    - YOU tick: `5.1`
 
-8. **`visual-reviewer`** (read-only) ??if any UI change (run after ui-ux-reviewer).
+10. **`visual-reviewer`** (read-only) ??if any UI change (run after ui-ux-reviewer).
    - **Only invoke if** classifier marks UI/CSS as affected.
    - Optional handoff note: `agent-log/visual-reviewer.yml`
    - YOU tick: `5.2`
 
-9. **`ci-cd-gatekeeper`** (write-capable) ??writes `specs/changes/<change-id>/ci-gates.md` directly.
-   - YOU tick: `1.3`, `4.4`, applicable items in section 6
-
-10. **`qa-reviewer`** (read-only) ??release readiness decision (always last).
+11. **`qa-reviewer`** (read-only) ??release readiness decision (always last).
     - Optional handoff note: `agent-log/qa-reviewer.yml`
     - YOU tick: `5.4`
 
@@ -511,6 +518,7 @@ Please review the above items and re-run: cdd-kit gate <change-id>
 ## Rules
 
 - Never start implementation (backend/frontend-engineer) before `contract-reviewer` has completed for Tier 0?? changes
+- Never start implementation (backend/frontend-engineer or dedicated test engineers) before `implementation-plan.md` exists and `tasks.yml` item `1.4` is done
 - Never skip `test-plan.md` for Tier 0?? changes
 - Never skip `ci-gates.md` for any implementation change
 - Agent logs are optional; do not create them just to satisfy a gate.

package/assets/skills/cdd-resume/SKILL.md

@@ -42,6 +42,7 @@ Read only these state files first:
 - `specs/changes/<change-id>/context-manifest.md` if present
 - `specs/changes/<change-id>/agent-log/*.yml`
 - `specs/changes/<change-id>/change-classification.md`
+- `specs/changes/<change-id>/implementation-plan.md` if present
 
 Do not run broad repository search during resume. Do not read `src/`, `tests/`, or `contracts/` unless the current `context-manifest.md` authorizes that path or an approved expansion lists it.
 
@@ -54,6 +55,8 @@ Read `specs/changes/<change-id>/agent-log/` to list which agents have already ru
 
 Read `specs/changes/<change-id>/change-classification.md` to recall the tier and required agents.
 
+Read `specs/changes/<change-id>/implementation-plan.md` if it exists. If implementation tasks are still pending and the plan is missing or still a scaffold, resume from `implementation-planner` before invoking backend/frontend/test implementation agents.
+
 Read `specs/changes/<change-id>/context-manifest.md`:
 - Identify allowed paths and approved expansions.
 - Identify pending Context Expansion Requests.
@@ -76,6 +79,7 @@ Completed agents: <list from agent-log/>
 Pending tasks: <list of status: pending items>
 Pending context expansions: <none | list request ids and paths>
 Allowed context: <short summary from context-manifest.md>
+Implementation plan: <ready | missing | scaffold | blocked>
 
 Next agent to run: <agent-name> (based on tier flow and what's missing)
 ```
@@ -110,5 +114,6 @@ Continue until all required agents are done, then run `cdd-kit gate <change-id>`
 - Never start from Step 1 of `/cdd-new` — only resume from the next pending agent
 - Never use broad search to reconstruct state; resume from `tasks.yml`, `context-manifest.md`, and `agent-log/`
 - Never continue past pending Context Expansion Requests
+- Never resume backend/frontend/test implementation agents before `implementation-plan.md` is ready
 - If tasks.yml has `status: abandoned`, report to user and stop
 - If tasks.yml has `status: gate-blocked`, go directly to gate retry (max 3)

package/assets/skills/contract-driven-delivery/SKILL.md

@@ -21,7 +21,7 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
    - Invoke repo-context-scanner to capture project profile and standardization gaps.
 3. Select required artifacts.
    - Use templates in `templates/`.
-   - Do not force every artifact for tiny changes, but do require `change-classification.md`, `test-plan.md`, and `ci-gates.md` for implementation changes.
+   - Do not force every artifact for tiny changes, but do require `change-classification.md`, `implementation-plan.md`, `test-plan.md`, and `ci-gates.md` for implementation changes.
 4. Update contracts before or alongside implementation. Invoke contract-reviewer to validate API/CSS/env/data/business/CI-CD contracts before or alongside implementation.
    - API: `references/api-contract-standard.md`
    - CSS/UI: `references/css-contract-standard.md`
@@ -39,8 +39,14 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
    - `stress-soak-engineer` implements load, soak, and long-running stability tests.
    - Invoke the relevant test engineer(s) before or alongside implementation based on the risk tier.
    - Each engineer must read the matching standard before authoring tests: e2e-resilience-engineer → references/e2e-standard.md, monkey-test-engineer → references/monkey-operation-standard.md, stress-soak-engineer → references/stress-soak-standard.md.
-6. Implement through the right role.
+6. Produce the implementation plan.
+   - Invoke `implementation-planner` after classification, contracts, test-plan, design (if any), and CI gate plan are known.
+   - `implementation-plan.md` is the execution packet for implementation agents: scope, non-goals, file-level plan, contract updates, tests, acceptance criteria, and constraints.
+   - Keep the plan concise. It should not duplicate the full investigation history or user discussion.
+   - If the planner reports missing decisions or context, stop before implementation and resolve that gap.
+7. Implement through the right role.
    - Backend/frontend work must follow contracts and tests.
+   - Backend/frontend/test implementation agents must read `implementation-plan.md` and should report `blocked` instead of inferring missing requirements from chat history.
    - Before invoking an agent with known concrete read paths, run
      `cdd-kit context check <change-id> --path <paths...>` and expand the
      manifest before the agent reads legitimate missing paths.
@@ -50,12 +56,12 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
    - Invoke ui-ux-reviewer for interaction, copy, accessibility, and information hierarchy review whenever UI changes.
    - Invoke visual-reviewer for layout, responsive, CSS contract, and screenshot diff review whenever UI changes.
    - If implementation reveals an unexpected boundary or architectural constraint, halt and re-invoke `spec-architect` before continuing.
-7. Run quality gates.
+8. Run quality gates.
    - Use `references/qa-gates.md`.
    - CI/CD gate plan is mandatory.
    - `qa-reviewer` decides release readiness; Tier 1 gates must be green; Tier 3+ gates must be green or explicitly deferred with a recorded promotion policy.
    - Invoke ci-cd-gatekeeper to design and enforce the gate plan.
-8. Archive and audit drift.
+9. Archive and audit drift.
    - Use `references/spec-drift-policy.md`.
    - General agents record evidence and findings only; durable learning
      promotion happens only during `/cdd-close` Step 3.
@@ -76,6 +82,7 @@ Use this skill to turn software requests into traceable, testable, CI/CD-gated c
 - classification
 - current behavior if modifying existing feature
 - proposal/spec/design as needed
+- implementation-plan
 - contracts
 - test-plan
 - ci-gates
@@ -129,4 +136,5 @@ Run scripts with Python 3 from the repository root.
 
 - `tasks.yml`: structured YAML, validated by `src/schemas/tasks.schema.ts`.
 - `agent-log/<agent>.yml`: optional structured handoff note per `references/agent-log-protocol.md`.
+- `implementation-plan.md`: required execution handoff for implementation agents.
 - All other change artifacts remain markdown prose.

package/assets/skills/contract-driven-delivery/references/workflow-router.md

@@ -6,8 +6,8 @@ Classify every request before implementation. A request may have more than one t
 
 | Change type | Required path |
 |---|---|
-| new-feature | proposal, spec, design, contracts, test-plan, ci-gates, tasks |
-| feature-enhancement | current-behavior, diff spec, regression scope, contracts, test-plan, ci-gates |
+| new-feature | proposal, spec, design, contracts, test-plan, ci-gates, implementation-plan, tasks |
+| feature-enhancement | current-behavior, diff spec, regression scope, contracts, test-plan, ci-gates, implementation-plan |
 | business-logic-change | current rule, new rule, decision table, examples, edge cases, regression tests |
 | bug-fix | reproduction, root cause, failing test, fix, regression test, QA evidence |
 | regression-fix | broken prior behavior, regression source, failing test, rollback or forward fix |
@@ -28,6 +28,7 @@ Do not create heavyweight artifacts when a tiny change does not need them. Howev
 - which contracts are affected
 - which tests prove it
 - which CI/CD gates must run
+- what execution packet implementation agents should follow
 
 ## Iteration rule
 

package/assets/skills/contract-driven-delivery/scripts/generate_change_scaffold.py

@@ -17,6 +17,7 @@ def main():
     mapping={
         'change-request.md':'change-request.md',
         'change-classification.md':'change-classification.md',
+        'implementation-plan.md':'implementation-plan.md',
         'current-behavior.md':'current-behavior.md',
         'proposal.md':'proposal.md',
         'spec.md':'spec.md',

package/assets/skills/contract-driven-delivery/scripts/validate_spec_traceability.py

@@ -2,7 +2,7 @@
 """Coarse traceability check for a change folder."""
 from pathlib import Path
 import argparse, sys
-REQUIRED=['change-classification.md','test-plan.md','ci-gates.md','tasks.yml']
+REQUIRED=['change-classification.md','implementation-plan.md','test-plan.md','ci-gates.md','tasks.yml']
 def check_change_dir(d):
     """Check one change directory. Returns list of error strings (empty = pass)."""
     errors=[]

package/assets/skills/contract-driven-delivery/templates/change-classification.md

@@ -18,7 +18,7 @@
 - reason: (fill only if yes)
 
 ## Required Artifacts
-Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.yml
+Always required: 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)
 | artifact | create? | reason |

package/assets/skills/contract-driven-delivery/templates/implementation-plan.md

@@ -0,0 +1,56 @@
+---
+change-id: <id>
+schema-version: 0.1.0
+last-changed: <date>
+---
+
+# 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 |  |  |  |
+
+## 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 |
+|---|---|---|
+| AC-1 |  |  |
+
+## Handoff Constraints
+
+- Implementation agents must not infer missing requirements from chat history.
+- 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
+
+- 

package/assets/skills/contract-driven-delivery/templates/tasks.yml

@@ -12,6 +12,7 @@ tasks:
   - { id: "1.1", section: Preparation, title: "Confirm classification and required artifacts", status: pending }
   - { id: "1.2", section: Preparation, title: "Confirm contracts to update", status: pending }
   - { id: "1.3", section: Preparation, title: "Confirm CI/CD gate plan", status: pending }
+  - { id: "1.4", section: Preparation, title: "Confirm implementation plan", status: pending }
   - { id: "2.1", section: "Contract Updates", title: "API contract", status: pending }
   - { id: "2.2", section: "Contract Updates", title: "CSS/UI contract", status: pending }
   - { id: "2.3", section: "Contract Updates", title: "Env contract", status: pending }

package/assets/specs-templates/change-classification.md

@@ -18,7 +18,7 @@
 - reason: (fill only if yes)
 
 ## Required Artifacts
-Always required: change-request.md, change-classification.md, test-plan.md, ci-gates.md, tasks.yml
+Always required: 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)
 | artifact | create? | reason |

package/assets/specs-templates/implementation-plan.md

@@ -0,0 +1,56 @@
+---
+change-id: <id>
+schema-version: 0.1.0
+last-changed: <date>
+---
+
+# 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 |  |  |  |
+
+## 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 |
+|---|---|---|
+| AC-1 |  |  |
+
+## Handoff Constraints
+
+- Implementation agents must not infer missing requirements from chat history.
+- 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
+
+- 

package/assets/specs-templates/tasks.yml

@@ -12,6 +12,7 @@ tasks:
   - { id: "1.1", section: Preparation, title: "Confirm classification and required artifacts", status: pending }
   - { id: "1.2", section: Preparation, title: "Confirm contracts to update", status: pending }
   - { id: "1.3", section: Preparation, title: "Confirm CI/CD gate plan", status: pending }
+  - { id: "1.4", section: Preparation, title: "Confirm implementation plan", status: pending }
   - { id: "2.1", section: "Contract Updates", title: "API contract", status: pending }
   - { id: "2.2", section: "Contract Updates", title: "CSS/UI contract", status: pending }
   - { id: "2.3", section: "Contract Updates", title: "Env contract", status: pending }

package/dist/cli/index.js

@@ -7756,6 +7756,20 @@ function migrateAgentLogs(changeDir, changed, pendingWrites, pendingDeletes) {
     changed.push(`agent-log/${f} -> agent-log/${yamlName}`);
   }
 }
+function ensureImplementationPlanScaffold(changeId, changeDir, changed, warnings, pendingWrites) {
+  const planPath = join13(changeDir, "implementation-plan.md");
+  if (existsSync12(planPath))
+    return;
+  const templatePath = join13(ASSET.specsTemplates, "implementation-plan.md");
+  if (!existsSync12(templatePath)) {
+    warnings.push("implementation-plan.md template not found; run cdd-kit upgrade --yes after updating cdd-kit");
+    return;
+  }
+  const template = readFileSync11(templatePath, "utf8").replace(/<change-id>/g, changeId).replace(/<id>/g, changeId);
+  pendingWrites.push({ path: planPath, content: template });
+  changed.push("implementation-plan.md: added scaffold");
+  warnings.push("implementation-plan.md scaffold added; fill it before implementation agents continue");
+}
 function migrateOne(changeId, changeDir, enableContextGovernance) {
   const changed = [];
   const warnings = [];
@@ -7793,6 +7807,7 @@ function migrateOne(changeId, changeDir, enableContextGovernance) {
     }
   }
   migrateTasksFile(changeId, changeDir, enableContextGovernance, detectedTier, changed, warnings, pending, deletes);
+  ensureImplementationPlanScaffold(changeId, changeDir, changed, warnings, pending);
   migrateAgentLogs(changeDir, changed, pending, deletes);
   const manifestPath = join13(changeDir, "context-manifest.md");
   if (!existsSync12(manifestPath)) {
@@ -7946,6 +7961,7 @@ var init_migrate = __esm({
   "src/commands/migrate.ts"() {
     "use strict";
     init_logger();
+    init_paths();
   }
 });
 
@@ -11668,6 +11684,7 @@ async function ensureFreshContextIndexes(cwd) {
 var REQUIRED_TEMPLATES = [
   "change-request.md",
   "change-classification.md",
+  "implementation-plan.md",
   "test-plan.md",
   "ci-gates.md",
   "tasks.yml",
@@ -11917,6 +11934,7 @@ var TASKS_STATUS_ENUM = /* @__PURE__ */ new Set([
 var REQUIRED_FILES = [
   "change-request.md",
   "change-classification.md",
+  "implementation-plan.md",
   "test-plan.md",
   "ci-gates.md",
   "tasks.yml",
@@ -11925,6 +11943,7 @@ var REQUIRED_FILES = [
 var TIER_PATTERN = /\b(tier\s*[0-5]|low|medium|high|critical)\b/i;
 var MIN_CHARS = {
   "change-classification.md": 200,
+  "implementation-plan.md": 200,
   "test-plan.md": 200,
   "ci-gates.md": 150,
   "change-request.md": 100,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.0.17",
+  "version": "2.0.18",
   "description": "Contract-driven delivery kit for AI coding agents with deterministic context indexes, manifest-backed read-scope governance, and orchestrated contracts-first delivery.",
   "keywords": [
     "contract-driven",