contract-driven-delivery 1.7.0 → 1.8.1

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

@@ -0,0 +1,188 @@
+---
+name: cdd-init
+description: Initialize contract-driven delivery for a project. Handles both brand-new projects (no specs/ directory) and brownfield adoption (existing codebase). Run once per project before using /cdd-new.
+---
+
+# cdd-init — Project Initialization
+
+## Overview
+
+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.
+
+**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.
+
+---
+
+## Step 1: Detect project type
+
+Run from the repository root:
+
+```
+cdd-kit detect-stack
+```
+
+Then check whether `specs/` directory already exists in the repo root.
+
+- `specs/` does **NOT** exist → **New Project** → follow Section A
+- `specs/` **already exists** → **Brownfield Adoption** → follow Section B
+
+---
+
+## Section A: New Project
+
+### A1. Initialize scaffold
+
+```
+cdd-kit init
+cdd-kit install-hooks
+```
+
+### A2. Scan project baseline
+
+Invoke `repo-context-scanner` agent. Ask it to report (NOT write):
+- Tech stack and build commands
+- Existing API endpoints (routes, controllers)
+- Existing env variables in use
+- Existing data models or report shapes
+
+The agent returns its findings as text. YOU then write `specs/project-profile.md` from its output.
+
+### A3. Create stub contracts (YOU write these)
+
+Based on the scanner's findings, create stub files in `contracts/`:
+
+| Surface found | File to create |
+|---------------|---------------|
+| API endpoints | `contracts/api.md` |
+| Env variables | `contracts/env.md` |
+| Data/report shapes | `contracts/data.md` (skip if none) |
+
+Each file must have frontmatter:
+```
+---
+schema-version: 0.1.0
+status: draft
+last-changed: <today's date>
+---
+```
+
+Use column formats from `.claude/skills/contract-driven-delivery/references/api-contract-standard.md` and `env-contract-standard.md`.
+
+**0.x contracts are informational only — `cdd-kit gate` does not enforce them until bumped to 1.0.0.**
+
+### A4. Report to user
+
+```
+## cdd-init complete (new project)
+
+Stack detected: <stack>
+Files created:
+- specs/project-profile.md
+- contracts/api.md (draft, v0.1.0)
+- contracts/env.md (draft, v0.1.0)
+Hook installed: .git/hooks/pre-commit
+
+Next step: /cdd-new <describe your first feature or change>
+```
+
+---
+
+## Section B: Brownfield Adoption
+
+### B1. Initialize scaffold (non-destructive)
+
+```
+cdd-kit init
+cdd-kit install-hooks
+```
+
+`cdd-kit init` will not overwrite existing files.
+
+### B2. Scan existing project
+
+Invoke `repo-context-scanner` agent. Ask it to report (NOT write):
+- Tech stack and commands
+- All existing API endpoints with method + path
+- All existing env variables (name, where used, whether secret)
+- Existing data models or shared data shapes
+- Existing tests and CI/CD setup
+- Gaps vs cdd-kit expectations
+
+The agent returns findings as text. YOU write `specs/project-profile.md` from its output.
+
+### B3. Reverse-engineer draft contracts (YOU write these)
+
+Based on the scanner's findings, create or update draft contracts:
+
+**`contracts/api.md`** — list all discovered endpoints:
+```
+---
+schema-version: 0.1.0
+status: draft
+last-changed: <today>
+---
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| ...    | ...  | ...  | ...     | ...      |
+```
+
+**`contracts/env.md`** — list all discovered env variables:
+```
+---
+schema-version: 0.1.0
+status: draft
+last-changed: <today>
+---
+| Name | Required | Default | Secret |
+|------|----------|---------|--------|
+| ...  | ...      | ...     | ...    |
+```
+
+**`contracts/data.md`** — only if significant data shapes exist.
+
+Rules:
+- Document what EXISTS — do not prescribe what should exist
+- Mark uncertain fields with `<!-- verify -->`
+- Do NOT bump above 0.x during init
+- Do NOT delete or overwrite existing `contracts/` files — append sections
+
+### B4. Run gap analysis
+
+Invoke `spec-drift-auditor` agent. Ask it to report (NOT write):
+1. What is already in place (contracts, tests, CI gates)
+2. What is missing and at what priority
+3. Recommended first tracked change to close the highest-risk gap
+
+### B5. Report to user
+
+```
+## cdd-init complete (brownfield adoption)
+
+Stack detected: <stack>
+Contracts reverse-engineered (all at v0.1.0 draft):
+- contracts/api.md — <N> endpoints documented
+- contracts/env.md — <N> variables documented
+Hook installed: .git/hooks/pre-commit
+
+Gap report:
+### Existing (found)
+- ...
+
+### Missing (needs work)
+- ...
+
+### Recommended first tracked change
+- ...
+
+Next step: /cdd-new <describe the gap or feature to address first>
+```
+
+---
+
+## Rules
+
+- Never delete existing files
+- Never bump any contract version above 0.x during init
+- Gate enforcement starts only after contracts reach 1.0.0
+- Scanning agents only report — YOU (main Claude) write all files
+- If `cdd-kit init` fails: `npm install -g contract-driven-delivery@latest`

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

@@ -0,0 +1,162 @@
+---
+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
+
+## Input
+
+The skill argument is the user's change description in natural language (e.g., "add JWT authentication to the API" or "redesign the dashboard homepage").
+
+If no description is provided, ask the user: "Please describe the change you want to make."
+
+---
+
+## Step 1: Generate change-id and scaffold
+
+Derive a `change-id` from the description:
+- kebab-case, max 5 words
+- examples: `add-jwt-auth`, `redesign-dashboard-home`, `fix-order-export-timeout`
+
+Check that `specs/changes/<change-id>/` does not already exist. If it does, append `-2` (or next available suffix).
+
+Run the scaffold generator:
+
+```
+python .claude/skills/contract-driven-delivery/scripts/generate_change_scaffold.py <change-id>
+```
+
+If the script is unavailable, manually create `specs/changes/<change-id>/` and copy these template files:
+
+| Source | Destination |
+|--------|-------------|
+| `.claude/skills/contract-driven-delivery/templates/change-request.md` | `specs/changes/<change-id>/change-request.md` |
+| `.claude/skills/contract-driven-delivery/templates/change-classification.md` | `specs/changes/<change-id>/change-classification.md` |
+| `.claude/skills/contract-driven-delivery/templates/test-plan.md` | `specs/changes/<change-id>/test-plan.md` |
+| `.claude/skills/contract-driven-delivery/templates/ci-gates.md` | `specs/changes/<change-id>/ci-gates.md` |
+| `.claude/skills/contract-driven-delivery/templates/tasks.md` | `specs/changes/<change-id>/tasks.md` |
+
+Fill in `change-request.md`:
+- `## Original Request` → the user's exact description
+- `## Business / User Goal` → infer from context
+- `## Requested Delivery Date / Priority` → "as soon as possible" if not specified
+
+---
+
+## Step 2: Classify the change
+
+Invoke `change-classifier` agent with:
+- The user's change description
+- The project profile at `specs/project-profile.md` (if it exists)
+- The existing contracts in `contracts/` (if any)
+
+The classifier must write a complete `specs/changes/<change-id>/change-classification.md` including:
+- Risk tier (Tier 0–5, or low / medium / high / critical)
+- Affected surfaces (API, UI, env, data, CI)
+- List of required agents
+
+Wait for `change-classification.md` to be written before continuing.
+
+---
+
+## Step 3: Read the tier and commission agents
+
+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.
+
+### Tier 4–5 (low risk: docs, prompts, config-only, no behavior change)
+
+1. `contract-reviewer` — confirm no contracts are touched or all touched ones are already updated
+2. `qa-reviewer` — confirm release readiness
+
+### Tier 2–3 (normal: feature, enhancement, bug fix with behavior change)
+
+1. `contract-reviewer` — update or create contracts in `contracts/` before any implementation starts
+2. `test-strategist` — author `specs/changes/<change-id>/test-plan.md`
+3. `spec-architect` — only if the classifier flagged an architectural boundary or cross-module impact
+4. `backend-engineer` — if the change touches server, API, data, or business logic
+5. `frontend-engineer` — if the change touches UI, components, or client-side behavior
+6. `ui-ux-reviewer` — if any UI change (run alongside or after frontend-engineer)
+7. `visual-reviewer` — if any UI change (run after ui-ux-reviewer)
+8. `dependency-security-reviewer` — if the change touches lockfiles, package manifests, or DB migrations
+9. `ci-cd-gatekeeper` — update `specs/changes/<change-id>/ci-gates.md`
+10. `qa-reviewer` — release readiness decision
+
+### Tier 0–1 (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`:
+
+- `e2e-resilience-engineer` — E2E, failure-injection, data-boundary tests
+- `monkey-test-engineer` — adversarial input, fuzz, rapid-UI-action tests
+- `stress-soak-engineer` — load, soak, and long-running stability tests
+
+**Agent commission rules**:
+- Skip an agent only if the classifier explicitly marks its surface as "not affected"
+- 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 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`
+
+---
+
+## Step 4: Run the gate
+
+After all required agents have completed:
+
+```
+cdd-kit gate <change-id>
+```
+
+**If gate passes**: proceed to Step 5.
+
+**If gate fails**:
+1. Read the gate error output carefully
+2. Identify which artifact is missing, stub, or invalid
+3. Re-invoke the specific agent responsible for that artifact with the exact fix required
+4. Re-run `cdd-kit gate <change-id>`
+5. Repeat until gate passes (max 3 iterations; if still failing after 3, report to user)
+
+---
+
+## Step 5: Report to user
+
+Output a final summary:
+
+```
+## /cdd-new complete
+
+Change ID: <change-id>
+Risk tier: <tier>
+Agents invoked: <list in order>
+Gate: PASSED
+
+All artifacts written to: specs/changes/<change-id>/
+
+Next step:
+  git add specs/changes/<change-id>/
+  git add <any implementation files changed>
+  git commit -m "feat(<change-id>): <one-line description>"
+```
+
+If gate did not pass after 3 iterations:
+
+```
+## /cdd-new — gate blocked
+
+Change ID: <change-id>
+Gate failed after 3 attempts.
+
+Blocking items:
+- <item 1>
+- <item 2>
+
+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 skip `ci-gates.md` for any implementation change
+- Every agent must write its `agent-log/<name>.md` — the gate will reject changes missing it
+- `qa-reviewer` always runs last and makes the release-readiness decision

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 
 // src/commands/init.ts
 import { join as join4 } from "path";
-import { rmSync, readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3 } from "fs";
+import { rmSync, readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
 
 // src/utils/paths.ts
 import { join, dirname } from "path";
@@ -20,7 +20,8 @@ var AGENTS_HOME = join(CLAUDE_HOME, "agents");
 var SKILLS_HOME = join(CLAUDE_HOME, "skills");
 var ASSET = {
   agents: join(ASSETS_DIR, "agents"),
-  skill: join(ASSETS_DIR, "skill"),
+  skills: join(ASSETS_DIR, "skills"),
+  skill: join(ASSETS_DIR, "skills", "contract-driven-delivery"),
   contracts: join(ASSETS_DIR, "contracts"),
   specsTemplates: join(ASSETS_DIR, "specs-templates"),
   testsTemplates: join(ASSETS_DIR, "tests-templates"),
@@ -283,11 +284,16 @@ async function init(opts) {
       const { count: agentCount, created: agentCreated } = copyDirTracked(ASSET.agents, AGENTS_HOME, { overwrite: true });
       track(agentCreated);
       log.ok(`${agentCount} agent file(s) installed.`);
-      const skillDest = join4(SKILLS_HOME, "contract-driven-delivery");
-      log.info(`Installing skill  \u2192 ${skillDest}`);
-      const { count: skillCount, created: skillCreated } = copyDirTracked(ASSET.skill, skillDest, { overwrite: true });
-      track(skillCreated);
-      log.ok(`${skillCount} skill file(s) installed.`);
+      const skillDirs = readdirSync2(ASSET.skills, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+      let totalSkillFiles = 0;
+      for (const skillName of skillDirs) {
+        const skillDest = join4(SKILLS_HOME, skillName);
+        log.info(`Installing skill  \u2192 ${skillDest}`);
+        const { count, created } = copyDirTracked(join4(ASSET.skills, skillName), skillDest, { overwrite: true });
+        track(created);
+        totalSkillFiles += count;
+      }
+      log.ok(`${totalSkillFiles} skill file(s) installed (${skillDirs.length} skills).`);
       log.blank();
     }
     if (!opts.globalOnly) {
@@ -384,7 +390,7 @@ async function init(opts) {
 
 // src/commands/update.ts
 import { join as join5 } from "path";
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync as readdirSync2, copyFileSync as copyFileSync2, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync as readdirSync3, copyFileSync as copyFileSync2, readFileSync as readFileSync3 } from "fs";
 import { createHash } from "crypto";
 import { homedir as homedir2 } from "os";
 function fileHash(filePath) {
@@ -396,7 +402,7 @@ function diffDir(src, dest) {
   if (!existsSync4(src))
     return entries;
   function walk(currentSrc, currentDest) {
-    const items = readdirSync2(currentSrc, { withFileTypes: true });
+    const items = readdirSync3(currentSrc, { withFileTypes: true });
     for (const item of items) {
       const srcPath = join5(currentSrc, item.name);
       const destPath = join5(currentDest, item.name);
@@ -432,7 +438,7 @@ function backupDir(dir, backupDest) {
     return;
   mkdirSync2(backupDest, { recursive: true });
   function walk(src, dst) {
-    const items = readdirSync2(src, { withFileTypes: true });
+    const items = readdirSync3(src, { withFileTypes: true });
     for (const item of items) {
       const s = join5(src, item.name);
       const d = join5(dst, item.name);
@@ -499,7 +505,7 @@ async function update(opts) {
 
 // src/commands/new-change.ts
 import { join as join6 } from "path";
-import { existsSync as existsSync5, readdirSync as readdirSync3 } from "fs";
+import { existsSync as existsSync5, readdirSync as readdirSync4 } from "fs";
 var REQUIRED_TEMPLATES = [
   "change-request.md",
   "change-classification.md",
@@ -509,7 +515,7 @@ var REQUIRED_TEMPLATES = [
 ];
 function listOptional() {
   try {
-    const all = readdirSync3(ASSET.specsTemplates).filter((f) => f.endsWith(".md"));
+    const all = readdirSync4(ASSET.specsTemplates).filter((f) => f.endsWith(".md"));
     return all.filter((f) => !REQUIRED_TEMPLATES.includes(f));
   } catch {
     return [];
@@ -641,7 +647,7 @@ async function validate(opts) {
 }
 
 // src/commands/gate.ts
-import { existsSync as existsSync7, readFileSync as readFileSync4, readdirSync as readdirSync4 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync4, readdirSync as readdirSync5 } from "fs";
 import { join as join8 } from "path";
 import { spawnSync as spawnSync2 } from "child_process";
 var REQUIRED_FILES = [
@@ -685,7 +691,7 @@ async function gate(changeId) {
   }
   const agentLogDir = join8(changeDir, "agent-log");
   if (existsSync7(agentLogDir)) {
-    const logFiles = readdirSync4(agentLogDir).filter((f) => f.endsWith(".md"));
+    const logFiles = readdirSync5(agentLogDir).filter((f) => f.endsWith(".md"));
     for (const f of logFiles) {
       const content = readFileSync4(join8(agentLogDir, f), "utf8");
       const statusMatch = content.match(/^\s*-\s*status:\s*(complete|needs-review|blocked)\s*$/m);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Contract-driven delivery kit CLI — spec-first, test-first AI-assisted delivery for brownfield systems",
   "keywords": [
     "contract-driven",