contract-driven-delivery 1.8.0 → 1.8.1

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 (2) hide show
  1. package/assets/skills/cdd-init/SKILL.md +80 -54
  2. package/package.json +1 -1
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "contract-driven-delivery",
3
- "version": "1.8.0",
3
+ "version": "1.8.1",
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",