contract-driven-delivery 2.0.16 → 2.0.18

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

@@ -1,15 +1,15 @@
----
+---
 name: cdd-new
 description: Start a new tracked change. Scaffolds all required artifacts, classifies the change by risk tier, commissions the right agents in order, and runs cdd-kit gate. Args: <change description in natural language>
 ---
 
-# cdd-new — New Change Request
+# cdd-new ??New Change Request
 
 ## Mental model
 
-- `contracts/` = the single source of truth (live — always reflects current system behaviour)
+- `contracts/` = the single source of truth (live ??always reflects current system behaviour)
 - `tests/` = proof the contracts hold (live)
-- `specs/changes/<id>/` = why we decided this back then (passive archive — read only when investigating history, never as input to planning)
+- `specs/changes/<id>/` = why we decided this back then (passive archive ??read only when investigating history, never as input to planning)
 - `CLAUDE.md` = what this project is and how to start work
 
 ## Spec depth rules
@@ -17,20 +17,20 @@ description: Start a new tracked change. Scaffolds all required artifacts, class
 Every artifact under `specs/changes/<id>/` answers **WHAT** and **WHY**, not HOW.
 
 Soft caps (guidance, not gate-enforced):
-- `spec.md` ≤ 200 lines
-- `design.md` ≤ 150 lines
-- `test-plan.md` ≤ 100 lines
-- `ci-gates.md` ≤ 80 lines
+- `spec.md` ??200 lines
+- `design.md` ??150 lines
+- `test-plan.md` ??100 lines
+- `ci-gates.md` ??80 lines
 
 **Forbidden in spec artifacts** (these belong in code/tests, not specs):
-- SQL DDL or migration code → put in migrations/, reference the path
-- ORM model code (SQLAlchemy, Prisma, etc.) → put in source, reference the module
-- Full test function bodies, mock setup, fixture data, expected JSON payloads → put in tests/
+- SQL DDL or migration code ??put in migrations/, reference the path
+- ORM model code (SQLAlchemy, Prisma, etc.) ??put in source, reference the module
+- Full test function bodies, mock setup, fixture data, expected JSON payloads ??put in tests/
 - Runnable code blocks > 10 lines belong in source files, not specs. Pseudocode and mapping tables are fine at any length.
 - Per-test input/output tables with more than 15 rows (data-boundary tests with up to 15 boundary cases are acceptable)
 
 **test-plan.md should contain:**
-- Acceptance criteria → test family mapping (table)
+- Acceptance criteria ??test family mapping (table)
 - Test file paths and test names (one line per test, no implementation detail)
 - Tier assignment per family
 - Out-of-scope list
@@ -70,43 +70,40 @@ Before I start a tracked change, I need to lock down three things:
 
   Affected surface:       <best guess from request, or empty>
   Desired behavior:       <best guess, or empty>
-  Success criterion:      <empty — please fill>
+  Success criterion:      <empty ??please fill>
 
 Could you confirm or fill in the missing pieces?
 ```
 
 Only proceed to Step 1 once all three are answered or the user explicitly says
 "proceed without success criterion". Record the user's clarifications verbatim
-in `change-request.md` § Original Request.
+in `change-request.md` 禮 Original Request.
 
 The cost of this step: 1 short message round-trip. The cost of skipping it:
-one full classifier+contract-reviewer cycle, often 5-10× more tokens, plus an
+one full classifier+contract-reviewer cycle, often 5-10? more tokens, plus an
 inevitable re-classification when the agents discover the ambiguity.
 
 ---
 
 ## Write Responsibilities
 
-**This distinction is critical — follow it for every step:**
+**This distinction is critical ??follow it for every step:**
 
-| Agent type | Who writes artifact files | Who writes agent-log | 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 (main Claude) | 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 | YOU (main Claude) |
+| 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): `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`.
 
 **Agent-log pointer rule**: When you or an agent writes `artifacts[].pointer`,
-follow `references/agent-log-protocol.md` exactly. If the text before the first
-`:` contains `/`, `cdd-kit gate` treats that text as a repo-relative file path
-and verifies that the file exists. Therefore each pointer may name only one
-file, file pointers must not include parenthetical notes on the path, and
-slash-containing labels such as `I/O:` or `WARNING/OVERDUE:` must not be used as
-pointer prefixes. Put extra explanation in `notes` or a separate non-path
-artifact pointer instead.
+follow `references/agent-log-protocol.md`. If the text before the first `:` contains `/`, treat it as one repo-relative file path, and one pointer names one file only. File pointers must not
+include parenthetical notes on the path, and slash-containing labels such as
+`I/O:` or `WARNING/OVERDUE:` must not be used as pointer prefixes. Put extra
+explanation in `notes` or a separate non-path artifact pointer instead.
 
 **Durable learning rule**: During `/cdd-new`, agents record evidence and
-findings in artifacts and `agent-log/*.yml` only. Do not promote durable lessons
+findings in artifacts and optional handoff notes only. Do not promote durable lessons
 while the change is still active. Durable learning promotion happens only during
 `/cdd-close` Step 3, where main Claude cross-checks evidence and writes approved
 rules to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`).
@@ -117,11 +114,11 @@ rules to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`).
 
 Only create optional artifacts (`current-behavior.md`, `proposal.md`, `spec.md`, `design.md`, `qa-report.md`, `regression-report.md`) when the classifier's `change-classification.md` explicitly marks them as `yes`.
 
-Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` — it is not part of the classifier's opt-in surface.
+Note: `archive.md` is created during `/cdd-close`, not during `/cdd-new` ??it is not part of the classifier's opt-in surface.
 
-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.
+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
 
@@ -153,7 +150,7 @@ cdd-kit context-scan
 Do not use broad search or ad hoc reads to classify the change before `context-scan` has completed.
 
 The generated scaffold contains the artifacts listed in the table below. **All
-templates are written from disk by `cdd-kit new` — do not paste template bodies
+templates are written from disk by `cdd-kit new` ??do not paste template bodies
 into this prompt.** The on-disk source of truth lives in `specs/templates/` of
 the kit and is bundled into every install.
 
@@ -161,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) |
@@ -190,7 +188,7 @@ The classifier must include a `## Context Manifest Draft` section with:
 - required tests
 - any context expansion requests that must be approved before implementation
 
-**change-classifier is read-only** — it will return its output as text.
+**change-classifier is read-only** ??it will return its output as text.
 
 ### If the classifier returns `## Atomic Split Proposal`
 
@@ -204,31 +202,31 @@ NOT proceed with the rest of `/cdd-new`. Instead:
    - For each row in the proposal table, run `cdd-kit new <change-id>` with
      the listed `--depends-on`.
    - Then say: "I created N change directories. Want me to run `/cdd-new`
-     against the first one now?" — wait for confirmation; do not auto-loop.
+     against the first one now?" ??wait for confirmation; do not auto-loop.
 4. If user picks "force monolithic":
    - Re-invoke change-classifier with `force-monolithic` appended to the
      change-request and proceed with whatever Tier the classifier returns.
 5. Delete the partially-scaffolded change directory you created in Step 1
    if the user picked "separate" and the originally-derived change-id is
-   not in the proposal — it would otherwise sit empty and confuse `cdd-kit
+   not in the proposal ??it would otherwise sit empty and confuse `cdd-kit
    list`.
 
 ### Classifier output lint (B8): refuse stub responses
 
 Before writing any files, verify the classifier response contains:
 
-- `## Tier` followed by `- N` where N is a single digit 0-5 (NOT `0 / 1 / 2 / 3 / 4 / 5` — that is the unfilled placeholder).
+- `## Tier` followed by `- N` where N is a single digit 0-5 (NOT `0 / 1 / 2 / 3 / 4 / 5` ??that is the unfilled placeholder).
 - `## Required Agents` with at least one agent name.
-- `## Inferred Acceptance Criteria` with at least one filled `AC-1: …` line.
+- `## Inferred Acceptance Criteria` with at least one filled `AC-1: ?圳 line.
 
-If any of these are missing or still hold the literal placeholder text, STOP. Re-prompt the classifier with the missing pieces named explicitly. Do NOT write classification.md — gate will reject it as a stub anyway and you will have wasted the round-trip.
+If any of these are missing or still hold the literal placeholder text, STOP. Re-prompt the classifier with the missing pieces named explicitly. Do NOT write classification.md ??gate will reject it as a stub anyway and you will have wasted the round-trip.
 
 ### When the classifier output passes lint
 
-1. **YOU write** `specs/changes/<change-id>/change-classification.md` — replace the blank template with the classifier's classification output.
-2. **YOU write** `specs/changes/<change-id>/agent-log/change-classifier.yml` — copy the Agent Log block from the classifier's response.
+1. **YOU write** `specs/changes/<change-id>/change-classification.md` ??replace the blank template with the classifier's classification output.
+2. Optional: write `specs/changes/<change-id>/agent-log/change-classifier.yml` only if the classifier returned useful handoff evidence.
 3. **YOU update** `specs/changes/<change-id>/context-manifest.md` from the classifier's `## Context Manifest Draft`.
-4. **YOU update** `tasks.yml` frontmatter: set `tier: <N>` to the classifier's tier digit. This is now the authoritative source for `cdd-kit gate` tier-based agent enforcement (the classification.md `## Tier` section is fallback only).
+4. **YOU update** `tasks.yml` frontmatter: set `tier: <N>` to the classifier's tier digit. This is now the authoritative source for quality-gate tier checks (the classification.md `## Tier` section is fallback only).
 5. **YOU tick** `tasks.yml` item `1.1`.
 
 Wait until these five writes are done before continuing.
@@ -241,11 +239,11 @@ Wait until these five writes are done before continuing.
 
 Read `change-classification.md` to determine the tier. Then invoke agents **in the exact order below**.
 
-**For each read-only agent**: wait for its text response → YOU write its artifact file(s) → YOU write its agent-log → YOU tick relevant tasks.yml item(s).
+**For each read-only agent**: wait for its text response ??YOU write its artifact file(s) ??YOU write an optional handoff note when useful ??YOU tick relevant tasks.yml item(s).
 
-**For each write-capable agent**: wait for it to confirm completion → YOU tick relevant tasks.yml item(s).
+**For each write-capable agent**: wait for it to confirm completion ??YOU tick relevant tasks.yml item(s).
 
-If any agent sets `status: blocked` in its log, halt immediately and report the agent's `next-action` to the user — do not proceed to subsequent agents.
+If any agent reports `blocked`, halt immediately and surface its concrete next action to the user ??do not proceed to subsequent agents.
 
 **When invoking any agent, always begin the prompt with:**
 ```
@@ -263,14 +261,13 @@ cdd-kit context check <change-id> --path <repo-relative path> [more paths...]
 
 If the check fails and the paths are legitimate work scope, update
 `context-manifest.md` `## Allowed Paths` or approve a Context Expansion Request
-before the agent reads them. This catches common late gate failures such as UI
-components/stores/views or CI workflow files missing from the manifest.
+before the agent reads them. This keeps read scope explicit before broad source
+access, especially for UI components/stores/views or CI workflow files.
 
 After every agent returns, complete the closeout before starting the next
 agent:
-- confirm its `agent-log/<agent>.yml` exists or write it for read-only agents
-- confirm the log has a completed status (`complete`, `done`, or `approved`) or
-  halt on `blocked`
+- confirm required artifacts exist; optional handoff notes are not gate inputs
+- if the agent reports `blocked`, halt and surface its concrete next action
 - tick the owned `tasks.yml` items immediately
 - record incidental/pre-existing findings in the appropriate report instead of
   silently fixing unrelated scope
@@ -285,30 +282,31 @@ the user; do not put them inside the prompt sent to the agent.
 
 | Stage | Agent | Badge |
 |---|---|---|
-| Decision | `change-classifier` | 🟣 `[classifier]` |
-| Decision | `spec-architect` | 🟣 `[architect]` |
-| Implementation | `backend-engineer` | 🔵 `[backend]` |
-| Implementation | `frontend-engineer` | 🔵 `[frontend]` |
-| Implementation | `ci-cd-gatekeeper` | 🔵 `[ci-cd]` |
-| Implementation | `test-strategist` | 🟡 `[test-plan]` |
-| Heavy testing (Tier 0–1 only) | `e2e-resilience-engineer` | 🟠 `[e2e]` |
-| Heavy testing (Tier 0–1 only) | `monkey-test-engineer` | 🟠 `[monkey]` |
-| Heavy testing (Tier 0–1 only) | `stress-soak-engineer` | 🟠 `[stress]` |
-| Review | `contract-reviewer` | 🟢 `[contracts]` |
-| Review | `qa-reviewer` | 🟢 `[qa]` |
-| Review | `ui-ux-reviewer` | 🟢 `[ui-ux]` |
-| Review | `visual-reviewer` | 🟢 `[visual]` |
-| Review | `dependency-security-reviewer` | 🟢 `[deps-sec]` |
-| Audit | `spec-drift-auditor` | ⚫ `[drift]` |
-| Audit | `repo-context-scanner` | ⚫ `[repo-scan]` |
+| 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]` |
+| Implementation | `test-strategist` | ? `[test-plan]` |
+| Heavy testing (Tier 0?? only) | `e2e-resilience-engineer` | ?? `[e2e]` |
+| Heavy testing (Tier 0?? only) | `monkey-test-engineer` | ?? `[monkey]` |
+| Heavy testing (Tier 0?? only) | `stress-soak-engineer` | ?? `[stress]` |
+| Review | `contract-reviewer` | ? `[contracts]` |
+| Review | `qa-reviewer` | ? `[qa]` |
+| Review | `ui-ux-reviewer` | ? `[ui-ux]` |
+| Review | `visual-reviewer` | ? `[visual]` |
+| Review | `dependency-security-reviewer` | ? `[deps-sec]` |
+| Audit | `spec-drift-auditor` | ??`[drift]` |
+| Audit | `repo-context-scanner` | ??`[repo-scan]` |
 
 Color semantics:
-- 🟣 purple: deciding what we will do (heavy model, `opus`)
-- 🔵 blue: writing code (`sonnet` implementation)
-- 🟡 yellow: planning tests (`sonnet`)
-- 🟠 orange: heavy testing — only appears for Tier 0–1, signals high-risk scope
-- 🟢 green: reviewing what was done (no code writes; just verdicts)
-- ⚫ neutral: audits and scans (read-only background work)
+- ? purple: deciding what we will do (heavy model, `opus`)
+- ? blue: writing code (`sonnet` implementation)
+- ? yellow: planning tests (`sonnet`)
+- ?? orange: heavy testing ??only appears for Tier 0??, signals high-risk scope
+- ? green: reviewing what was done (no code writes; just verdicts)
+- ??neutral: audits and scans (read-only background work)
 
 Format: emoji is followed by a single space, then the bracket-tag, then the
 human-readable narration.
@@ -316,11 +314,10 @@ human-readable narration.
 Examples:
 
 ```
-🟣 [classifier] Reading the request and project map…
-🟢 [contracts] Confirming the API contract is unchanged. (read-only)
-🔵 [backend] Implementing the JWT issuance endpoint and writing failing
+? [classifier] Reading the request and project map??? [contracts] Confirming the API contract is unchanged. (read-only)
+? [backend] Implementing the JWT issuance endpoint and writing failing
             tests first per TDD policy.
-🟠 [stress] Tier 1 high-risk change — running soak test for 30 min.
+?? [stress] Tier 1 high-risk change ??running soak test for 30 min.
 ```
 
 These badges are pure narration. They MUST NOT be sent inside the agent's
@@ -329,73 +326,78 @@ prompt; the agent's behavior is defined by the agent prompt files in
 
 ---
 
-### Tier 4–5 (low risk: docs, prompts, config-only, no behavior change)
+### Tier 4?? (low risk: docs, prompts, config-only, no behavior change)
 
-1. **`contract-reviewer`** (read-only) — confirm no contracts are touched or all touched ones are already updated.
-   - YOU write: `agent-log/contract-reviewer.yml`
+1. **`contract-reviewer`** (read-only) ??confirm no contracts are touched or all touched ones are already updated.
+   - Optional handoff note: `agent-log/contract-reviewer.yml`
    - YOU tick: `1.2`, applicable items in section 2
 
-2. **`qa-reviewer`** (read-only) — confirm release readiness.
-   - YOU write: `agent-log/qa-reviewer.yml`
+2. **`qa-reviewer`** (read-only) ??confirm release readiness.
+   - Optional handoff note: `agent-log/qa-reviewer.yml`
    - YOU tick: `5.4`
 
 ---
 
-### Tier 2–3 (normal: feature, enhancement, bug fix with behavior change)
+### Tier 2?? (normal: feature, enhancement, bug fix with behavior change)
 
-1. **`contract-reviewer`** (read-only) — update or create contracts in `contracts/` before any implementation starts.
-   - YOU write: `agent-log/contract-reviewer.yml`
+1. **`contract-reviewer`** (read-only) ??update or create contracts in `contracts/` before any implementation starts.
+   - Optional handoff note: `agent-log/contract-reviewer.yml`
    - YOU tick: `1.2`, applicable items in section 2
 
-2. **`test-strategist`** (write-capable) — writes `specs/changes/<change-id>/test-plan.md` directly.
+2. **`test-strategist`** (write-capable) ??writes `specs/changes/<change-id>/test-plan.md` directly.
    - YOU tick: applicable items in section 3 based on what test families were planned
-   - Provide the classifier's `## Inferred Acceptance Criteria` list to test-strategist. These become the `criterion id` column in the Acceptance Criteria → Test Mapping table.
+   - Provide the classifier's `## Inferred Acceptance Criteria` list to test-strategist. These become the `criterion id` column in the Acceptance Criteria ??Test Mapping table.
 
-3. **`spec-architect`** (write-capable) — only if `change-classification.md` contains `Architecture Review Required: yes`.
+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 and its own agent-log.
+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–3.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–3.5 are written by dedicated test engineers (Tier 0–1 only or when classifier explicitly requires them).
+   - 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 and its own agent-log.
+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.
-   - YOU write: `agent-log/dependency-security-reviewer.yml`
+   - 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.
-   - YOU write: `agent-log/ui-ux-reviewer.yml`
+   - 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.
-   - YOU write: `agent-log/visual-reviewer.yml`
+   - 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).
-    - YOU write: `agent-log/qa-reviewer.yml`
+11. **`qa-reviewer`** (read-only) ??release readiness decision (always last).
+    - Optional handoff note: `agent-log/qa-reviewer.yml`
     - YOU tick: `5.4`
 
 ---
 
-### Tier 0–1 (high risk: production data, concurrency, queues, large queries, auth, payments, exports)
+### Tier 0?? (high risk: production data, concurrency, queues, large queries, auth, payments, exports)
 
-All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backend-engineer` and before `dependency-security-reviewer`:
+All agents from Tier 2??, plus insert these after `frontend-engineer` / `backend-engineer` and before `dependency-security-reviewer`:
 
-- **`e2e-resilience-engineer`** (write-capable) — E2E, failure-injection, data-boundary tests. Writes its own agent-log.
+- **`e2e-resilience-engineer`** (write-capable) ??E2E, failure-injection, data-boundary tests. May write an optional handoff note.
   - YOU tick: `3.3`
 
-- **`monkey-test-engineer`** (write-capable) — adversarial input, fuzz, rapid-UI-action tests. Writes its own agent-log.
+- **`monkey-test-engineer`** (write-capable) ??adversarial input, fuzz, rapid-UI-action tests. May write an optional handoff note.
   - YOU tick: `3.4`
 
-- **`stress-soak-engineer`** (write-capable) — load, soak, and long-running stability tests. Writes its own agent-log.
+- **`stress-soak-engineer`** (write-capable) ??load, soak, and long-running stability tests. May write an optional handoff note.
   - YOU tick: `3.5`
 
 ---
@@ -428,20 +430,18 @@ cdd-kit gate <change-id>
 - YOU tick: `tasks.yml` item `6.1`
 - Proceed to Step 5.
 
-**If gate fails — structured fix-back routing**:
+**If gate fails ??structured fix-back routing**:
 
 Capture gate's full stderr verbatim. Parse error lines and route each to the
-right owner. The patterns below are exhaustive — every gate error message
+right owner. The patterns below are exhaustive ??every gate error message
 matches one of them.
 
 | Error pattern | Route to | Re-invocation prompt seed |
 |---|---|---|
-| `agent-log/<name>.yml: …` | the named agent | "PREVIOUS GATE FAILURE FOR THIS AGENT: <full error line>. Fix only your `agent-log/<name>.yml`. Re-output your Agent Log block." |
-| `change-classification.md: …` | `change-classifier` | "PREVIOUS CLASSIFICATION FAILED GATE: <error>. Re-emit only the failing section." |
-| `context-manifest.md: …` | `change-classifier` | "PREVIOUS MANIFEST FAILED GATE: <error>. Re-emit `## Context Manifest Draft`." |
-| `tasks.yml: …` (frontmatter / pending) | YOU (main Claude) — direct edit | n/a — fix `tasks.yml` yourself. Don't re-invoke an agent for a file you own. |
-| `Tier <N> change requires agent-log/<X>.yml` | invoke the missing agent `<X>` | "TIER <N> REQUIRES THIS LOG. Run your full work, not just the log." |
-| `dependency <id>: upstream change is not completed` | n/a — STOP | Tell user: "Upstream change `<id>` must complete before this change can gate. Run `/cdd-new <id>` first or run `cdd-kit archive <id>` if it's already done." |
+| `change-classification.md: ?圳 | `change-classifier` | "PREVIOUS CLASSIFICATION FAILED GATE: <error>. Re-emit only the failing section." |
+| `context-manifest.md: ?圳 | `change-classifier` | "PREVIOUS MANIFEST FAILED GATE: <error>. Re-emit `## Context Manifest Draft`." |
+| `tasks.yml: ?圳 (frontmatter / pending) | YOU (main Claude) ??direct edit | n/a ??fix `tasks.yml` yourself. Don't re-invoke an agent for a file you own. |
+| `dependency <id>: upstream change is not completed` | n/a ??STOP | Tell user: "Upstream change `<id>` must complete before this change can gate. Run `/cdd-new <id>` first or run `cdd-kit archive <id>` if it's already done." |
 | `validators returned non-zero` | `contract-reviewer` | "PREVIOUS CONTRACT VALIDATION FAILED: <last 10 lines of validator stderr>. Reconcile contracts." |
 
 **Re-invocation prompt template** (always use this exact prefix when re-invoking an agent for fix-back):
@@ -457,15 +457,15 @@ FIX TARGET:
 <the specific file or section that needs to change>
 
 REFERENCES:
-- references/agent-log-protocol.md (log format)
+- references/agent-log-protocol.md (optional handoff note format, only if useful)
 - references/<agent-specific-standard>.md (if applicable)
 
 Fix this exact issue without re-doing your prior work. Re-output only the
-section that changed plus your updated Agent Log block.
+section that changed plus any updated handoff note, if useful.
 ```
 
 After re-invoking, re-run `cdd-kit gate <change-id>`. Repeat up to **3 times**. Each
-iteration must be on a strictly smaller error set — if the same error returns
+iteration must be on a strictly smaller error set ??if the same error returns
 twice, halt and surface to user (an agent stuck in a loop is more expensive
 than a human read).
 
@@ -501,7 +501,7 @@ Next step:
 If gate did not pass after 3 iterations:
 
 ```
-## /cdd-new — gate blocked
+## /cdd-new ??gate blocked
 
 Change ID: <change-id>
 Gate failed after 3 attempts.
@@ -517,17 +517,18 @@ 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–3 changes
-- Never skip `test-plan.md` for Tier 0–3 changes
+- 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
-- Every agent must have its `agent-log/<name>.yml` written — YOU write it for read-only agents after receiving their response; write-capable agents write their own
-- Tick the relevant `tasks.yml` checkbox immediately after each agent completes — do not batch
+- Agent logs are optional; do not create them just to satisfy a gate.
+- Tick the relevant `tasks.yml` checkbox immediately after each agent completes ??do not batch
 - `qa-reviewer` always runs last and makes the release-readiness decision
 
 ---
 
 ## After Completion
 
-The `/cdd-new` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks — including questions unrelated to this change, new feature discussions, debugging help, or general conversation — without requiring them to use a specific command. The git commit shown in the report is a suggestion, not a required next step; do not wait for it before resuming normal behavior.
+The `/cdd-new` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks ??including questions unrelated to this change, new feature discussions, debugging help, or general conversation ??without requiring them to use a specific command. The git commit shown in the report is a suggestion, not a required next step; do not wait for it before resuming normal behavior.
 
 When the change is merged and ready to close, run `/cdd-close <change-id>` to promote durable learnings to `contracts/` or project guidance (`CLAUDE.md`/`CODEX.md`) and archive the change directory.

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,23 +39,29 @@ 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.
-   - After each agent finishes, verify its agent-log exists and tick the
-     related `tasks.yml` items before starting the next agent.
+   - After each agent finishes, verify the required artifact files exist and
+     tick the related `tasks.yml` items before starting the next agent.
    - UI changes require UI/UX and visual review.
    - 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
@@ -128,5 +135,6 @@ Run scripts with Python 3 from the repository root.
 ## Output discipline (file formats)
 
 - `tasks.yml`: structured YAML, validated by `src/schemas/tasks.schema.ts`.
-- `agent-log/<agent>.yml`: structured YAML per `references/agent-log-protocol.md`.
+- `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.