contract-driven-delivery 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/assets/agents/change-classifier.md +2 -2
  2. package/assets/agents/contract-reviewer.md +2 -2
  3. package/assets/agents/dependency-security-reviewer.md +2 -2
  4. package/assets/agents/qa-reviewer.md +2 -2
  5. package/assets/agents/repo-context-scanner.md +2 -2
  6. package/assets/agents/spec-drift-auditor.md +2 -2
  7. package/assets/agents/ui-ux-reviewer.md +2 -2
  8. package/assets/agents/visual-reviewer.md +2 -2
  9. package/assets/skills/cdd-init/SKILL.md +80 -54
  10. package/assets/skills/cdd-new/SKILL.md +246 -42
  11. package/package.json +1 -1
package/assets/agents/change-classifier.md CHANGED
@@ -65,10 +65,10 @@ Use this structure:
65
65
 
66
66
  ## Machine-Verifiable Evidence
67
67
 
68
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
69
- with this exact structure (lines starting with `- ` are required):
68
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/change-classifier.md`.
70
69
 
71
70
  ```
71
+ ## Agent Log
72
72
  # Change Classifier Log
73
73
  - change-id: <id>
74
74
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/contract-reviewer.md CHANGED
@@ -57,10 +57,10 @@ approved / changes-required
57
57
 
58
58
  ## Machine-Verifiable Evidence
59
59
 
60
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
61
- with this exact structure (lines starting with `- ` are required):
60
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/contract-reviewer.md`.
62
61
 
63
62
  ```
63
+ ## Agent Log
64
64
  # Contract Reviewer Log
65
65
  - change-id: <id>
66
66
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/dependency-security-reviewer.md CHANGED
@@ -64,10 +64,10 @@ approved / changes-required / blocked
64
64
 
65
65
  ## Machine-Verifiable Evidence
66
66
 
67
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
68
- with this exact structure (lines starting with `- ` are required):
67
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/dependency-security-reviewer.md`.
69
68
 
70
69
  ```
70
+ ## Agent Log
71
71
  # Dependency Security Reviewer Log
72
72
  - change-id: <id>
73
73
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/qa-reviewer.md CHANGED
@@ -69,10 +69,10 @@ approved / blocked / approved-with-risk
69
69
 
70
70
  ## Machine-Verifiable Evidence
71
71
 
72
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
73
- with this exact structure (lines starting with `- ` are required):
72
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/qa-reviewer.md`.
74
73
 
75
74
  ```
75
+ ## Agent Log
76
76
  # QA Reviewer Log
77
77
  - change-id: <id>
78
78
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/repo-context-scanner.md CHANGED
@@ -81,10 +81,10 @@ frontend / backend / fullstack / monorepo / library / tool
81
81
 
82
82
  ## Machine-Verifiable Evidence
83
83
 
84
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
85
- with this exact structure (lines starting with `- ` are required):
84
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/repo-context-scanner.md`.
86
85
 
87
86
  ```
87
+ ## Agent Log
88
88
  # Repo Context Scanner Log
89
89
  - change-id: <id>
90
90
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/spec-drift-auditor.md CHANGED
@@ -50,10 +50,10 @@ Multi-iteration development creates drift. Find it before it becomes production
50
50
 
51
51
  ## Machine-Verifiable Evidence
52
52
 
53
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
54
- with this exact structure (lines starting with `- ` are required):
53
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/spec-drift-auditor.md`.
55
54
 
56
55
  ```
56
+ ## Agent Log
57
57
  # Spec Drift Auditor Log
58
58
  - change-id: <id>
59
59
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/ui-ux-reviewer.md CHANGED
@@ -51,10 +51,10 @@ approved / changes-required
51
51
 
52
52
  ## Machine-Verifiable Evidence
53
53
 
54
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
55
- with this exact structure (lines starting with `- ` are required):
54
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/ui-ux-reviewer.md`.
56
55
 
57
56
  ```
57
+ ## Agent Log
58
58
  # UI/UX Reviewer Log
59
59
  - change-id: <id>
60
60
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/agents/visual-reviewer.md CHANGED
@@ -53,10 +53,10 @@ approved / changes-required
53
53
 
54
54
  ## Machine-Verifiable Evidence
55
55
 
56
- After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`
57
- with this exact structure (lines starting with `- ` are required):
56
+ After completing your task, include an **## Agent Log** section at the end of your response with this exact structure (lines starting with `- ` are required). The calling skill will write this block to `specs/changes/<change-id>/agent-log/visual-reviewer.md`.
58
57
 
59
58
  ```
59
+ ## Agent Log
60
60
  # Visual Reviewer Log
61
61
  - change-id: <id>
62
62
  - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
package/assets/skills/cdd-init/SKILL.md CHANGED
@@ -9,11 +9,13 @@ description: Initialize contract-driven delivery for a project. Handles both bra
9
9
 
10
10
  This skill sets up the contract-driven delivery system for a project. It auto-detects whether this is a new project or brownfield adoption and follows the appropriate path.
11
11
 
12
+ **File creation rule**: Scanning agents (repo-context-scanner, spec-drift-auditor) only READ and REPORT — they have no write tools. After receiving their report, YOU (main Claude) create all files using Edit/Write.
13
+
12
14
  ---
13
15
 
14
16
  ## Step 1: Detect project type
15
17
 
16
- Run these commands from the repository root:
18
+ Run from the repository root:
17
19
 
18
20
  ```
19
21
  cdd-kit detect-stack
@@ -32,43 +34,50 @@ Then check whether `specs/` directory already exists in the repo root.
32
34
 
33
35
  ```
34
36
  cdd-kit init
37
+ cdd-kit install-hooks
35
38
  ```
36
39
 
37
- Creates: `specs/`, `contracts/` (if not present), CI template for detected stack.
40
+ ### A2. Scan project baseline
38
41
 
39
- ### A2. Install pre-commit hook
42
+ Invoke `repo-context-scanner` agent. Ask it to report (NOT write):
43
+ - Tech stack and build commands
44
+ - Existing API endpoints (routes, controllers)
45
+ - Existing env variables in use
46
+ - Existing data models or report shapes
40
47
 
41
- ```
42
- cdd-kit install-hooks
43
- ```
44
-
45
- ### A3. Scan project baseline
48
+ The agent returns its findings as text. YOU then write `specs/project-profile.md` from its output.
46
49
 
47
- Invoke `repo-context-scanner` agent to scan the repository and emit an initial project profile. Write output to `specs/project-profile.md`.
50
+ ### A3. Create stub contracts (YOU write these)
48
51
 
49
- ### A4. Create stub contracts
52
+ Based on the scanner's findings, create stub files in `contracts/`:
50
53
 
51
- For each surface the scanner found, create stub files in `contracts/` using frontmatter `version: 0.1.0` and `status: draft`:
54
+ | Surface found | File to create |
55
+ |---------------|---------------|
56
+ | API endpoints | `contracts/api.md` |
57
+ | Env variables | `contracts/env.md` |
58
+ | Data/report shapes | `contracts/data.md` (skip if none) |
52
59
 
53
- | Surface | File |
54
- |---------|------|
55
- | API endpoints found | `contracts/api.md` |
56
- | Env variables found | `contracts/env.md` |
57
- | Data/report shapes found | `contracts/data.md` (skip if none) |
60
+ Each file must have frontmatter:
61
+ ```
62
+ ---
63
+ schema-version: 0.1.0
64
+ status: draft
65
+ last-changed: <today's date>
66
+ ---
67
+ ```
58
68
 
59
- Use the standard table format from `.claude/skills/contract-driven-delivery/references/api-contract-standard.md` and `env-contract-standard.md` as the column schema.
69
+ Use column formats from `.claude/skills/contract-driven-delivery/references/api-contract-standard.md` and `env-contract-standard.md`.
60
70
 
61
- **Note**: 0.x contracts are informational only — `cdd-kit gate` does not enforce them until bumped to 1.0.0.
71
+ **0.x contracts are informational only — `cdd-kit gate` does not enforce them until bumped to 1.0.0.**
62
72
 
63
- ### A5. Report to user
73
+ ### A4. Report to user
64
74
 
65
- Output a summary:
66
75
  ```
67
76
  ## cdd-init complete (new project)
68
77
 
69
78
  Stack detected: <stack>
70
79
  Files created:
71
- - specs/ (scaffold)
80
+ - specs/project-profile.md
72
81
  - contracts/api.md (draft, v0.1.0)
73
82
  - contracts/env.md (draft, v0.1.0)
74
83
  Hook installed: .git/hooks/pre-commit
@@ -84,52 +93,68 @@ Next step: /cdd-new <describe your first feature or change>
84
93
 
85
94
  ```
86
95
  cdd-kit init
87
- ```
88
-
89
- Will not overwrite existing files. Creates missing scaffold directories only.
90
-
91
- ### B2. Install pre-commit hook
92
-
93
- ```
94
96
  cdd-kit install-hooks
95
97
  ```
96
98
 
97
- Idempotent — safe to run even if hook already exists.
99
+ `cdd-kit init` will not overwrite existing files.
98
100
 
99
- ### B3. Scan existing project
101
+ ### B2. Scan existing project
100
102
 
101
- Invoke `repo-context-scanner` agent with full scope:
103
+ Invoke `repo-context-scanner` agent. Ask it to report (NOT write):
102
104
  - Tech stack and commands
103
- - Existing contracts (if any)
104
- - Existing tests and CI/CD
105
- - Standardization gaps vs cdd-kit expectations
105
+ - All existing API endpoints with method + path
106
+ - All existing env variables (name, where used, whether secret)
107
+ - Existing data models or shared data shapes
108
+ - Existing tests and CI/CD setup
109
+ - Gaps vs cdd-kit expectations
110
+
111
+ The agent returns findings as text. YOU write `specs/project-profile.md` from its output.
106
112
 
107
- Write output to `specs/project-profile.md`.
113
+ ### B3. Reverse-engineer draft contracts (YOU write these)
108
114
 
109
- ### B4. Reverse-engineer draft contracts
115
+ Based on the scanner's findings, create or update draft contracts:
116
+
117
+ **`contracts/api.md`** — list all discovered endpoints:
118
+ ```
119
+ ---
120
+ schema-version: 0.1.0
121
+ status: draft
122
+ last-changed: <today>
123
+ ---
124
+ | Method | Path | Auth | Request | Response |
125
+ |--------|------|------|---------|----------|
126
+ | ... | ... | ... | ... | ... |
127
+ ```
110
128
 
111
- For each existing surface discovered by the scanner, create or update draft contracts:
129
+ **`contracts/env.md`** — list all discovered env variables:
130
+ ```
131
+ ---
132
+ schema-version: 0.1.0
133
+ status: draft
134
+ last-changed: <today>
135
+ ---
136
+ | Name | Required | Default | Secret |
137
+ |------|----------|---------|--------|
138
+ | ... | ... | ... | ... |
139
+ ```
112
140
 
113
- - **API**: Read existing route definitions → list endpoints in `contracts/api.md` using the standard table format (method, path, auth, request shape, response shape). Set `version: 0.1.0`, `status: draft`.
114
- - **Env**: Read existing `.env.example`, config loaders, or runtime env reads → list variables in `contracts/env.md` (name, required, default, secret). Set `version: 0.1.0`, `status: draft`.
115
- - **Data**: If report shapes, DB schemas, or shared data types exist and are significant → list in `contracts/data.md`. Set `version: 0.1.0`, `status: draft`.
141
+ **`contracts/data.md`** — only if significant data shapes exist.
116
142
 
117
- **Rules for brownfield reverse-engineering**:
118
- - Document what exists — do NOT prescribe what should exist
119
- - Mark all fields you are unsure about with `<!-- verify -->`
120
- - Do NOT bump any contract above 0.x during init
121
- - Do NOT delete or overwrite any existing `contracts/` files — append sections if a file exists
143
+ Rules:
144
+ - Document what EXISTS — do not prescribe what should exist
145
+ - Mark uncertain fields with `<!-- verify -->`
146
+ - Do NOT bump above 0.x during init
147
+ - Do NOT delete or overwrite existing `contracts/` files — append sections
122
148
 
123
- ### B5. Run gap analysis
149
+ ### B4. Run gap analysis
124
150
 
125
- Invoke `spec-drift-auditor` to compare the current state against cdd-kit expectations. Ask it to produce:
151
+ Invoke `spec-drift-auditor` agent. Ask it to report (NOT write):
126
152
  1. What is already in place (contracts, tests, CI gates)
127
153
  2. What is missing and at what priority
128
154
  3. Recommended first tracked change to close the highest-risk gap
129
155
 
130
- ### B6. Report to user
156
+ ### B5. Report to user
131
157
 
132
- Output a summary:
133
158
  ```
134
159
  ## cdd-init complete (brownfield adoption)
135
160
 
@@ -140,13 +165,13 @@ Contracts reverse-engineered (all at v0.1.0 draft):
140
165
  Hook installed: .git/hooks/pre-commit
141
166
 
142
167
  Gap report:
143
- ## Existing (found)
168
+ ### Existing (found)
144
169
  - ...
145
170
 
146
- ## Missing (needs work)
171
+ ### Missing (needs work)
147
172
  - ...
148
173
 
149
- ## Recommended first tracked change
174
+ ### Recommended first tracked change
150
175
  - ...
151
176
 
152
177
  Next step: /cdd-new <describe the gap or feature to address first>
@@ -158,5 +183,6 @@ Next step: /cdd-new <describe the gap or feature to address first>
158
183
 
159
184
  - Never delete existing files
160
185
  - Never bump any contract version above 0.x during init
161
- - Gate enforcement (cdd-kit gate) is only required once contracts reach 1.0.0 — during init, draft contracts are informational
162
- - If `cdd-kit init` fails because the tool is not installed, instruct the user: `npm install -g contract-driven-delivery@latest`
186
+ - Gate enforcement starts only after contracts reach 1.0.0
187
+ - Scanning agents only report — YOU (main Claude) write all files
188
+ - If `cdd-kit init` fails: `npm install -g contract-driven-delivery@latest`
package/assets/skills/cdd-new/SKILL.md CHANGED
@@ -13,6 +13,19 @@ If no description is provided, ask the user: "Please describe the change you wan
13
13
 
14
14
  ---
15
15
 
16
+ ## Write Responsibilities
17
+
18
+ **This distinction is critical — follow it for every step:**
19
+
20
+ | Agent type | Who writes artifact files | Who writes agent-log | Who ticks tasks.md |
21
+ |------------|--------------------------|----------------------|--------------------|
22
+ | 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) |
23
+ | 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) |
24
+
25
+ **Rule**: After EVERY agent completes (whether it writes itself or you write for it), YOU must update the relevant `tasks.md` checkbox(es) from `[ ]` to `[x]`.
26
+
27
+ ---
28
+
16
29
  ## Step 1: Generate change-id and scaffold
17
30
 
18
31
  Derive a `change-id` from the description:
@@ -21,26 +34,162 @@ Derive a `change-id` from the description:
21
34
 
22
35
  Check that `specs/changes/<change-id>/` does not already exist. If it does, append `-2` (or next available suffix).
23
36
 
24
- Run the scaffold generator:
37
+ **Create all scaffold files using Write (do NOT run a Python script; do NOT use Edit on pre-existing files):**
38
+
39
+ Create `specs/changes/<change-id>/change-request.md` with the user's description filled in:
40
+ ```
41
+ # Change Request: <change-id>
42
+
43
+ ## Original Request
44
+ <user's exact description, verbatim>
45
+
46
+ ## Business / User Goal
47
+ <infer from the description>
48
+
49
+ ## Non-goals
50
+
51
+ ## Constraints
52
+
53
+ ## Known Context
54
+
55
+ ## Open Questions
56
+
57
+ ## Requested Delivery Date / Priority
58
+ as soon as possible
59
+ ```
25
60
 
61
+ Create `specs/changes/<change-id>/change-classification.md` with blank template:
62
+ ```
63
+ # Change Classification
64
+
65
+ ## Change Types
66
+ - primary:
67
+ - secondary:
68
+
69
+ ## Risk Level
70
+ - low / medium / high / critical
71
+
72
+ ## Impact Radius
73
+ - isolated / module-level / cross-module / system-wide
74
+
75
+ ## Required Artifacts
76
+ | artifact | required | reason |
77
+ |---|---:|---|
78
+ | current-behavior.md | | |
79
+ | proposal.md | | |
80
+ | spec.md | | |
81
+ | design.md | | |
82
+ | contracts.md | | |
83
+ | test-plan.md | yes | every implementation change requires test planning |
84
+ | ci-gates.md | yes | every implementation change requires CI/CD gate planning |
85
+ | qa-report.md | | |
86
+ | regression-report.md | | |
87
+
88
+ ## Required Contracts
89
+ - API:
90
+ - CSS/UI:
91
+ - Env:
92
+ - Data shape:
93
+ - Business logic:
94
+ - CI/CD:
95
+
96
+ ## Required Test Families
97
+ - unit:
98
+ - contract:
99
+ - integration:
100
+ - E2E:
101
+ - visual:
102
+ - data-boundary:
103
+ - resilience:
104
+ - fuzz/monkey:
105
+ - stress:
106
+ - soak:
107
+
108
+ ## Required Agents
109
+
110
+ ## Assumptions / Clarifications
26
111
  ```
27
- python .claude/skills/contract-driven-delivery/scripts/generate_change_scaffold.py <change-id>
112
+
113
+ Create `specs/changes/<change-id>/test-plan.md` with blank template:
28
114
  ```
115
+ # Test Plan: <change-id>
116
+
117
+ ## Scope
29
118
 
30
- If the script is unavailable, manually create `specs/changes/<change-id>/` and copy these template files:
119
+ ## Unit Tests
31
120
 
32
- | Source | Destination |
33
- |--------|-------------|
34
- | `.claude/skills/contract-driven-delivery/templates/change-request.md` | `specs/changes/<change-id>/change-request.md` |
35
- | `.claude/skills/contract-driven-delivery/templates/change-classification.md` | `specs/changes/<change-id>/change-classification.md` |
36
- | `.claude/skills/contract-driven-delivery/templates/test-plan.md` | `specs/changes/<change-id>/test-plan.md` |
37
- | `.claude/skills/contract-driven-delivery/templates/ci-gates.md` | `specs/changes/<change-id>/ci-gates.md` |
38
- | `.claude/skills/contract-driven-delivery/templates/tasks.md` | `specs/changes/<change-id>/tasks.md` |
121
+ ## Contract Tests
39
122
 
40
- Fill in `change-request.md`:
41
- - `## Original Request` → the user's exact description
42
- - `## Business / User Goal` → infer from context
43
- - `## Requested Delivery Date / Priority` → "as soon as possible" if not specified
123
+ ## Integration Tests
124
+
125
+ ## E2E Tests
126
+
127
+ ## Resilience / Data-Boundary Tests
128
+
129
+ ## Stress / Soak Tests
130
+
131
+ ## Out of Scope
132
+ ```
133
+
134
+ Create `specs/changes/<change-id>/ci-gates.md` with blank template:
135
+ ```
136
+ # CI Gates: <change-id>
137
+
138
+ ## Required Gates (block merge if failing)
139
+
140
+ ## Informational Gates (report only)
141
+
142
+ ## Nightly / Weekly / Manual Gates
143
+
144
+ ## Promotion Policy
145
+ ```
146
+
147
+ Create `specs/changes/<change-id>/tasks.md` with ALL checkboxes unchecked:
148
+ ```
149
+ # Tasks: <change-id>
150
+
151
+ ## 1. Preparation
152
+ - [ ] 1.1 Confirm classification and required artifacts
153
+ - [ ] 1.2 Confirm contracts to update
154
+ - [ ] 1.3 Confirm CI/CD gate plan
155
+
156
+ ## 2. Contract Updates
157
+ - [ ] 2.1 API contract
158
+ - [ ] 2.2 CSS/UI contract
159
+ - [ ] 2.3 Env contract
160
+ - [ ] 2.4 Data shape contract
161
+ - [ ] 2.5 Business logic contract
162
+ - [ ] 2.6 CI/CD contract
163
+
164
+ ## 3. Tests First
165
+ - [ ] 3.1 Unit/contract tests
166
+ - [ ] 3.2 Integration tests
167
+ - [ ] 3.3 E2E/resilience tests
168
+ - [ ] 3.4 Data-boundary/monkey tests
169
+ - [ ] 3.5 Stress/soak tests if required
170
+
171
+ ## 4. Implementation
172
+ - [ ] 4.1 Backend
173
+ - [ ] 4.2 Frontend
174
+ - [ ] 4.3 Env/deploy
175
+ - [ ] 4.4 CI/CD workflows
176
+
177
+ ## 5. Review
178
+ - [ ] 5.1 UI/UX review
179
+ - [ ] 5.2 Visual review
180
+ - [ ] 5.3 Contract review
181
+ - [ ] 5.4 QA review
182
+
183
+ ## 6. Verification
184
+ - [ ] 6.1 Local gates
185
+ - [ ] 6.2 PR required gates
186
+ - [ ] 6.3 Informational gates
187
+ - [ ] 6.4 Nightly/weekly/manual gates if required
188
+
189
+ ## 7. Archive
190
+ - [ ] 7.1 Archive change
191
+ - [ ] 7.2 Promote durable learnings to contracts or CLAUDE.md
192
+ ```
44
193
 
45
194
  ---
46
195
 
@@ -51,61 +200,112 @@ Invoke `change-classifier` agent with:
51
200
  - The project profile at `specs/project-profile.md` (if it exists)
52
201
  - The existing contracts in `contracts/` (if any)
53
202
 
54
- The classifier must write a complete `specs/changes/<change-id>/change-classification.md` including:
55
- - Risk tier (Tier 0–5, or low / medium / high / critical)
56
- - Affected surfaces (API, UI, env, data, CI)
57
- - List of required agents
203
+ **change-classifier is read-only** — it will return its output as text. After it responds:
58
204
 
59
- Wait for `change-classification.md` to be written before continuing.
205
+ 1. **YOU write** `specs/changes/<change-id>/change-classification.md` — replace the blank template with the classifier's classification output.
206
+ 2. **YOU write** `specs/changes/<change-id>/agent-log/change-classifier.md` — copy the Agent Log block from the classifier's response.
207
+ 3. **YOU tick** `tasks.md` item `1.1`.
208
+
209
+ Wait until these three writes are done before continuing.
60
210
 
61
211
  ---
62
212
 
63
213
  ## Step 3: Read the tier and commission agents
64
214
 
65
- Read `change-classification.md` to determine the tier. Then invoke agents **in the exact order below**, waiting for each to complete its `specs/changes/<change-id>/agent-log/<agent-name>.md` before proceeding.
215
+ Read `change-classification.md` to determine the tier. Then invoke agents **in the exact order below**.
216
+
217
+ **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.md item(s).
218
+
219
+ **For each write-capable agent**: wait for it to confirm completion → YOU tick relevant tasks.md item(s).
220
+
221
+ 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.
222
+
223
+ ---
66
224
 
67
225
  ### Tier 4–5 (low risk: docs, prompts, config-only, no behavior change)
68
226
 
69
- 1. `contract-reviewer` — confirm no contracts are touched or all touched ones are already updated
70
- 2. `qa-reviewer` — confirm release readiness
227
+ 1. **`contract-reviewer`** (read-only) — confirm no contracts are touched or all touched ones are already updated.
228
+ - YOU write: `agent-log/contract-reviewer.md`
229
+ - YOU tick: `1.2`, applicable items in section 2
230
+
231
+ 2. **`qa-reviewer`** (read-only) — confirm release readiness.
232
+ - YOU write: `agent-log/qa-reviewer.md`
233
+ - YOU tick: `5.4`
234
+
235
+ ---
71
236
 
72
237
  ### Tier 2–3 (normal: feature, enhancement, bug fix with behavior change)
73
238
 
74
- 1. `contract-reviewer` — update or create contracts in `contracts/` before any implementation starts
75
- 2. `test-strategist` — author `specs/changes/<change-id>/test-plan.md`
76
- 3. `spec-architect` — only if the classifier flagged an architectural boundary or cross-module impact
77
- 4. `backend-engineer` — if the change touches server, API, data, or business logic
78
- 5. `frontend-engineer` — if the change touches UI, components, or client-side behavior
79
- 6. `ui-ux-reviewer` — if any UI change (run alongside or after frontend-engineer)
80
- 7. `visual-reviewer` — if any UI change (run after ui-ux-reviewer)
81
- 8. `dependency-security-reviewer` — if the change touches lockfiles, package manifests, or DB migrations
82
- 9. `ci-cd-gatekeeper` — update `specs/changes/<change-id>/ci-gates.md`
83
- 10. `qa-reviewer` — release readiness decision
239
+ 1. **`contract-reviewer`** (read-only) — update or create contracts in `contracts/` before any implementation starts.
240
+ - YOU write: `agent-log/contract-reviewer.md`
241
+ - YOU tick: `1.2`, applicable items in section 2
242
+
243
+ 2. **`test-strategist`** (write-capable) — writes `specs/changes/<change-id>/test-plan.md` directly.
244
+ - YOU tick: applicable items in section 3 based on what test families were planned
245
+
246
+ 3. **`spec-architect`** (write-capable) — only if the classifier flagged an architectural boundary or cross-module impact.
247
+ - YOU tick: `1.3` (if it produced a gate plan)
248
+
249
+ 4. **`backend-engineer`** (write-capable) — if the change touches server, API, data, or business logic. Writes implementation and its own agent-log.
250
+ - YOU tick: `4.1` and/or `4.3` based on scope
251
+
252
+ 5. **`frontend-engineer`** (write-capable) — if the change touches UI, components, or client-side behavior. Writes implementation and its own agent-log.
253
+ - YOU tick: `4.2`
254
+
255
+ 6. **`dependency-security-reviewer`** (read-only) — if the change touches lockfiles, package manifests, or DB migrations.
256
+ - YOU write: `agent-log/dependency-security-reviewer.md`
257
+ - YOU tick: applicable security-related items
258
+
259
+ 7. **`ui-ux-reviewer`** (read-only) — if any UI change (run alongside or after frontend-engineer).
260
+ - YOU write: `agent-log/ui-ux-reviewer.md`
261
+ - YOU tick: `5.1`
262
+
263
+ 8. **`visual-reviewer`** (read-only) — if any UI change (run after ui-ux-reviewer).
264
+ - YOU write: `agent-log/visual-reviewer.md`
265
+ - YOU tick: `5.2`
266
+
267
+ 9. **`ci-cd-gatekeeper`** (write-capable) — writes `specs/changes/<change-id>/ci-gates.md` directly.
268
+ - YOU tick: `1.3`, `4.4`, applicable items in section 6
269
+
270
+ 10. **`qa-reviewer`** (read-only) — release readiness decision (always last).
271
+ - YOU write: `agent-log/qa-reviewer.md`
272
+ - YOU tick: `5.4`
273
+
274
+ ---
84
275
 
85
276
  ### Tier 0–1 (high risk: production data, concurrency, queues, large queries, auth, payments, exports)
86
277
 
87
- All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backend-engineer`:
278
+ All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backend-engineer` and before `dependency-security-reviewer`:
279
+
280
+ - **`e2e-resilience-engineer`** (write-capable) — E2E, failure-injection, data-boundary tests. Writes its own agent-log.
281
+ - YOU tick: `3.3`
282
+
283
+ - **`monkey-test-engineer`** (write-capable) — adversarial input, fuzz, rapid-UI-action tests. Writes its own agent-log.
284
+ - YOU tick: `3.4`
88
285
 
89
- - `e2e-resilience-engineer` — E2E, failure-injection, data-boundary tests
90
- - `monkey-test-engineer` — adversarial input, fuzz, rapid-UI-action tests
91
- - `stress-soak-engineer` — load, soak, and long-running stability tests
286
+ - **`stress-soak-engineer`** (write-capable) — load, soak, and long-running stability tests. Writes its own agent-log.
287
+ - YOU tick: `3.5`
92
288
 
93
- **Agent commission rules**:
289
+ ---
290
+
291
+ **Agent commission rules:**
94
292
  - Skip an agent only if the classifier explicitly marks its surface as "not affected"
95
- - 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
96
- - If the change is UI-only with no backend, skip `backend-engineer`; if backend-only with no UI, skip `frontend-engineer`, `ui-ux-reviewer`, `visual-reviewer`
293
+ - If backend-only with no UI: skip `frontend-engineer`, `ui-ux-reviewer`, `visual-reviewer`
294
+ - If UI-only with no backend: skip `backend-engineer`
97
295
 
98
296
  ---
99
297
 
100
298
  ## Step 4: Run the gate
101
299
 
102
- After all required agents have completed:
300
+ After all required agents have completed and all tasks.md items for their sections are ticked:
103
301
 
104
302
  ```
105
303
  cdd-kit gate <change-id>
106
304
  ```
107
305
 
108
- **If gate passes**: proceed to Step 5.
306
+ **If gate passes**:
307
+ - YOU tick: `tasks.md` item `6.1`
308
+ - Proceed to Step 5.
109
309
 
110
310
  **If gate fails**:
111
311
  1. Read the gate error output carefully
@@ -128,6 +328,9 @@ Risk tier: <tier>
128
328
  Agents invoked: <list in order>
129
329
  Gate: PASSED
130
330
 
331
+ Tasks completed:
332
+ - [x] all applicable items checked in specs/changes/<change-id>/tasks.md
333
+
131
334
  All artifacts written to: specs/changes/<change-id>/
132
335
 
133
336
  Next step:
@@ -158,5 +361,6 @@ Please review the above items and re-run: cdd-kit gate <change-id>
158
361
  - Never start implementation (backend/frontend-engineer) before `contract-reviewer` has completed for Tier 0–3 changes
159
362
  - Never skip `test-plan.md` for Tier 0–3 changes
160
363
  - Never skip `ci-gates.md` for any implementation change
161
- - Every agent must write its `agent-log/<name>.md` — the gate will reject changes missing it
364
+ - Every agent must have its `agent-log/<name>.md` written — YOU write it for read-only agents after receiving their response; write-capable agents write their own
365
+ - Tick the relevant `tasks.md` checkbox immediately after each agent completes — do not batch
162
366
  - `qa-reviewer` always runs last and makes the release-readiness decision
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "contract-driven-delivery",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "Contract-driven delivery kit CLI — spec-first, test-first AI-assisted delivery for brownfield systems",
5
5
  "keywords": [
6
6
  "contract-driven",