contract-driven-delivery 1.9.0 → 1.10.0

package/assets/CLAUDE.template.md

@@ -1,215 +1,26 @@
 # CLAUDE.md
 
-This repository follows the Contract-Driven Delivery workflow.
-
-## First response rule
-
-Before implementing any request, classify the change type and determine which contracts, tests, CI/CD gates, and review agents are required.
-
-Do not start production code changes until the required artifacts are created or explicitly judged unnecessary with rationale.
-
-## Change types
-
-Classify every request as one or more of:
-
-- `new-feature`
-- `feature-enhancement`
-- `business-logic-change`
-- `bug-fix`
-- `regression-fix`
-- `ui-only-change`
-- `api-only-change`
-- `env-change`
-- `data-contract-change`
-- `performance-change`
-- `refactor`
-- `ci-cd-change`
-- `test-hardening-change`
-
-## Stack-aware CI
-
-`cdd-kit init` auto-detects the project tech stack and patches the fast-gate step in `ci/github-actions/contract-driven-gates.yml` with stack-specific commands. Supported stacks:
-
-- **Python**: conda (default/preferred), poetry, uv, pip
-- **JavaScript**: pnpm, bun, yarn, npm
-- **Go**: go
-- **Rust**: rust
-
-For Conda projects, the generated CI uses `conda-incubator/setup-miniconda@v3` with `shell: bash -el {0}` (required for Conda env activation in GitHub Actions). If `cdd-kit init` could not detect a stack, fill in the placeholder step manually.
-
-Run `cdd-kit detect-stack` at any time to see what the detector found.
-
-## Required context discovery
-
-Inspect the repository before planning:
-
-- package manager and lockfiles (environment.yml for Conda, pyproject.toml for poetry/uv, etc.)
-- frontend framework and build tool
-- backend framework and app entrypoints
-- routing/controllers/API layers
-- API contract and inventory files
-- CSS/design token/component contract files
-- env files, `.env.example`, deployment configs, secret handling
-- test frameworks and existing test folders
-- CI/CD workflows and required checks
-- data/report schemas and column contracts
-- worker, queue, cache, database, storage, and external service boundaries
-
-Write or update a project profile when working in an unfamiliar repo.
-
-## Required artifact path
-
-For a meaningful change, use or create:
-
-```text
-specs/changes/<change-id>/
-├── change-request.md
-├── change-classification.md
-├── current-behavior.md
-├── proposal.md
-├── spec.md
-├── design.md
-├── contracts.md
-├── test-plan.md
-├── ci-gates.md
-├── tasks.md
-├── qa-report.md
-├── regression-report.md
-└── archive.md
-```
-
-## Contract versioning
-
-Contracts use semver via frontmatter; bump schema-version + add CHANGELOG entry on every contract change. Each contract file contains a YAML frontmatter block with `contract`, `schema-version`, `last-changed`, and `breaking-change-policy`. All changes at 1.0+ must be recorded in `contracts/CHANGELOG.md` using the format `## [<type> <version>] — <date>`. Major version bumps additionally require a `### Removed` or `### Changed (breaking)` section. The `validate_contract_versions.py` script enforces these rules automatically in CI and via `cdd-kit validate --versions`.
-
-## Contract rules
-
-### API
-
-Any API behavior change must update API contract, endpoint inventory, response/error format expectations, frontend service/types, and contract tests.
-
-### CSS/UI
-
-Any visual or component behavior change must update CSS/UI contract, token usage, component states, responsive behavior, and visual review evidence.
-
-### Env
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Any new or changed environment variable must update env contract, `.env.example`, validation rules, runtime scope, deployment documentation, and secret policy.
+## Project overview
 
-### Data/report shape
+<TODO: one-sentence description of what this repo does and who uses it>
 
-Any report, dashboard, export, import, or table-like data change must define required columns, types, nullability, coercion/rejection rules, row limits, empty-state behavior, and malformed-data behavior.
+## Dev commands
 
-### Business logic
+<TODO: fill in install / dev / test / lint / build commands for this project>
 
-Any business rule change must include current rule, new rule, decision table, examples, edge cases, backward compatibility, migration/data impact, and regression tests.
+## Architecture
 
-### CI/CD
+<TODO: describe main modules, service boundaries, and entry points>
 
-Every change must define the required gates. CI/CD is part of delivery, not an afterthought.
+---
 
-## Testing rules
-
-Use the lowest necessary test level, but do not skip production-reality coverage when risk requires it.
-
-Required test families:
-
-- unit tests
-- contract tests
-- integration tests
-- E2E tests
-- visual regression or visual review evidence
-- data-boundary tests
-- resilience tests
-- fuzz or monkey-operation tests
-- stress tests for concurrency/load-sensitive paths
-- soak tests for long-running or auto-refresh/report systems
-
-For bug fixes, write or identify a failing test before fixing whenever feasible.
-
-For resilience or fault tests, include a mutation check where practical: remove or bypass the intended handler and confirm the test fails.
-
-## CI/CD gate policy
-
-Use these tiers:
-
-- Tier 0: local fast gate
-- Tier 1: PR required gate
-- Tier 2: PR informational gate
-- Tier 3: nightly real-infra gate
-- Tier 4: weekly soak/stress gate
-- Tier 5: manual production-like dispatch gate
-
-Long-running or flaky gates may start as informational, but must have promotion criteria and owners.
-
-## Visual review policy
-
-Frontend changes that alter UI output require:
-
-- affected screen list
-- viewport list
-- state list: default, loading, empty, error, disabled, long text, no permission
-- screenshot or video evidence where possible
-- CSS contract check
-- accessibility check for focus, keyboard, labels, and contrast
-
-## Orchestration enforcement
-
-Every change in `specs/changes/<change-id>/` must pass `cdd-kit gate <change-id>` before the implementation is committed. The gate enforces:
-
-1. All 5 required artifacts exist (`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`)
-2. Each artifact has more than 100 meaningful characters (not a stub template)
-3. `change-classification.md` contains a tier marker (`Tier 0`–`Tier 5`) or a risk label (`low`, `medium`, `high`, `critical`)
-4. Agent-log files in `specs/changes/<change-id>/agent-log/` are valid (if present)
-5. All contract validators pass (`cdd-kit validate`)
-
-## Agent-log rules
-
-Each agent writes a machine-verifiable log to `specs/changes/<change-id>/agent-log/<agent-name>.md` after completing its task. The gate validates these logs automatically.
-
-Required log structure:
-
-```
-# <Agent Display Name> Log
-- change-id: <id>
-- timestamp: <ISO 8601>
-- status: complete | needs-review | blocked
-- artifacts:
-  - <evidence-type>: <concrete pointer>
-- next-action: <one line, or "none">
-```
-
-Rules enforced by `cdd-kit gate`:
-- The `status:` line must be present and set to `complete`, `needs-review`, or `blocked`.
-- When `status: blocked`, the `next-action:` line must be a concrete action of at least 10 characters (not "none").
-- Missing or invalid logs cause the gate to fail with a descriptive error.
-- A missing `agent-log/` directory is acceptable (gate passes when no agents have logged yet).
-
-Run `cdd-kit install-hooks` once in each repository to install a pre-commit hook that enforces the gate automatically on every commit touching `specs/changes/`. This prevents the workflow from being silently skipped.
-
-```bash
-cdd-kit gate add-user-auth      # manual check
-cdd-kit install-hooks           # install automatic pre-commit enforcement
-```
-
-## Forbidden practices
-
-- Do not implement before classifying the change.
-- Do not introduce undocumented API endpoints.
-- Do not change response shape without contract and client updates.
-- Do not add undocumented env vars.
-- Do not expose secrets through frontend-public env vars such as `VITE_`, `NEXT_PUBLIC_`, or `PUBLIC_`.
-- Do not hard-code visual tokens when a token system exists.
-- Do not bypass CI/CD gate planning.
-- Do not mark tasks complete without implementation evidence.
-- Do not hide production-reality failures by converting tests into superficial assertions.
-
-## Done criteria
+This repository follows the Contract-Driven Delivery workflow.
 
-A change is complete only when:
+- `contracts/` is the single source of truth for what the system should do.
+- `tests/` proves the contracts hold.
+- `specs/changes/<id>/` records why decisions were made (passive archive — read only when investigating history).
+- To start any non-trivial change, use `/cdd-new <description>` in Claude Code.
 
-- specs and contracts reflect the final behavior
-- test coverage maps to acceptance criteria
-- CI/CD gates pass or are explicitly documented as informational with promotion path
-- QA report records commands, evidence, and known residual risks
-- archive captures reusable learnings and standard updates
+Run `cdd-kit detect-stack` to verify the detected tech stack.

package/assets/agents/backend-engineer.md

@@ -17,7 +17,7 @@ Before editing production code, read the change artifacts, API/env/data/business
 - Validate input at the boundary.
 - Return standardized errors, not raw exceptions.
 - Preserve backward compatibility unless the spec explicitly marks a breaking change.
-- Add tests before or alongside implementation according to the test plan.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit, contract, and integration tests BEFORE writing feature code. Tests in `tasks.md` items 3.1–3.2 are your responsibility.
 - Update CI/CD workflows when required by `ci-gates.md`.
 
 ## Common pitfalls
@@ -34,6 +34,11 @@ Before editing production code, read the change artifacts, API/env/data/business
 
 Report changed files, contract updates, tests added, commands run, known risks, and next reviewer.
 
+## Artifact discipline
+
+Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
+In your agent log, reference file paths and function names — do not paste code blocks.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`

package/assets/agents/change-classifier.md

@@ -9,6 +9,17 @@ You are the change classifier for Contract-Driven Delivery.
 
 Your job is to stop premature implementation. Read the user request and nearby project context, then produce a classification report.
 
+## Tier mapping
+
+| Risk Level | Impact Radius | Tier |
+|---|---|---|
+| critical or high | system-wide or cross-module | 0–1 |
+| medium | cross-module or module-level | 2–3 |
+| low | module-level or isolated | 3–4 |
+| low | docs / prompts / config only, no behavior change | 4–5 |
+
+When in doubt, classify upward.
+
 ## Output
 
 Use this structure:
@@ -26,15 +37,30 @@ Use this structure:
 ## Impact Radius
 - isolated / module-level / cross-module / system-wide
 
+## Tier
+- 0 / 1 / 2 / 3 / 4 / 5
+
+## Architecture Review Required
+- yes / no
+- reason: (fill only if yes)
+
 ## Required Artifacts
-- request.md:
-- current-behavior.md:
-- proposal.md:
-- spec.md:
-- design.md:
-- contracts.md:
-- test-plan.md:
-- ci-gates.md:
+
+The following 5 artifacts are always required for implementation changes:
+`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+
+## Optional Artifacts (default: no — set yes only with explicit reason)
+
+| artifact | create? | reason |
+|---|---|---|
+| current-behavior.md | no | |
+| proposal.md | no | |
+| spec.md | no | |
+| design.md | no | |
+| qa-report.md | no | |
+| regression-report.md | no | |
+
+Note: `archive.md` is created during change close-out, not at classification time.
 
 ## Required Contracts
 - API:

package/assets/agents/frontend-engineer.md

@@ -16,7 +16,7 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 - Do not bypass shared component rules.
 - Handle loading, empty, error, disabled, long text, no permission, and slow network states when applicable.
 - Be aware of monkey-class bugs (double submit, rapid actions, navigation state, hidden tab); the actual preventive specs and tests are owned by monkey-test-engineer.
-- Add or update E2E/visual/data-boundary/resilience tests when UI behavior changes.
+- **TDD**: Read `specs/changes/<id>/test-plan.md` first. Write failing unit and component tests BEFORE writing feature code. E2E, visual, and data-boundary tests are also your responsibility when UI behavior changes. Tasks.md items 3.1–3.2 include frontend test scope.
 
 ## Common pitfalls
 
@@ -32,6 +32,11 @@ Before editing, read the change artifacts, API contract, CSS/UI contract, compon
 
 Report changed screens, component states covered, screenshots/videos if generated, tests added, commands run, and remaining UI risks.
 
+## Artifact discipline
+
+Implementation code goes into source files. Do NOT write runnable code into any `specs/changes/<id>/` artifact.
+In your agent log, reference file paths and function names — do not paste code blocks.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`

package/assets/agents/repo-context-scanner.md

@@ -22,6 +22,9 @@ Inspect the repository and produce a project profile before implementation or st
 - CI/CD workflows
 - worker/cache/database/storage configuration
 
+**Do NOT read `specs/changes/` or `specs/archive/`.** Those are passive history records. Inspect only live sources: source code, package files, contracts/, tests/, CI workflows, and CLAUDE.md.
+Also do not read specs/templates/ — those are scaffolding stubs, not live project state.
+
 ## Detection extras
 
 - Monorepo / workspace — check `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, `go.work`, `pyproject.toml [tool.uv]` workspaces.

package/assets/agents/spec-architect.md

@@ -49,45 +49,42 @@ proposed / accepted / superseded
 
 ## Output
 
-```md
-# Architecture Impact Report
+Write to `specs/changes/<change-id>/design.md` using this structure:
+
+```markdown
+# Design: <change-id>
 
 ## Summary
-...
+(1 paragraph: what changes architecturally and why)
 
-## Architecture Impact
-- yes / no / uncertain
-
-## Affected Areas
-- frontend:
-- backend:
-- database:
-- cache/queue:
-- auth/permission:
-- API contract:
-- CSS/UI system:
-- env/deploy:
-- CI/CD:
-
-## Options
-### Option A
-...
-### Option B
-...
+## Affected Components
+| component | file path(s) | nature of change |
+|---|---|---|
 
-## Recommendation
-...
+## Key Decisions
+- **Decision**: rationale — rejected alternative: reason rejected
 
-## ADR Required
-yes (written to docs/adr/...) / no
+## Migration / Rollback
+(Prose description. SQL and code go in migration files, not here.)
 
-## Required Follow-up Artifacts
-...
-
-## Risks and Mitigations
-...
+## Open Risks
 ```
 
+## Output discipline
+
+Your output goes into `specs/changes/<id>/design.md`. It must capture architectural decisions — not implement them.
+
+- **DO** write: 1-paragraph architecture summary
+- **DO** write: affected components table (component | file path | nature of change)
+- **DO** write: key decisions and rejected alternatives in prose
+- **DO** write: migration/rollback strategy in prose
+- **DO NOT** write: SQL DDL or migration scripts (those go in migrations/)
+- **DO NOT** write: ORM model code, API handler code, or any runnable code block > 10 lines
+- **DO NOT** write: storage estimates, benchmark numbers, or detailed implementation steps
+
+Reference file paths instead of duplicating implementation content.
+Target: `design.md` ≤ 150 lines.
+
 ## Machine-Verifiable Evidence
 
 After completing your task, write or append to `specs/changes/<change-id>/agent-log/<your-agent-name>.md`

package/assets/agents/spec-drift-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: spec-drift-auditor
-description: Audit drift across specs, contracts, implementation, tests, CI/CD gates, tasks, and archived learnings over multiple iterations.
+description: Audit drift between live contracts, implementation code, tests, and CI gates. Does NOT read historical specs/changes — contracts/ is the single source of truth.
 tools: Read, Grep, Glob, Bash
 model: claude-opus-4-7
 ---
@@ -9,22 +9,27 @@ You are the spec drift auditor.
 
 Multi-iteration development creates drift. Find it before it becomes production debt.
 
-## Audit questions
+## Audit axes
 
-- Does every implemented behavior trace to a spec or approved bug fix?
-- Does every spec acceptance criterion have test evidence?
-- Did API/CSS/env/data/business/CI contracts change with the code?
-- Are tasks marked complete actually implemented?
-- Are CI gates running the tests they claim to run?
-- Did completed changes archive durable rules back into contracts?
-- Are old archived specs contradicting current contracts?
+**1. contracts/ vs code**
+- Does every contract entry (API endpoint, business rule, env var, CSS token) have evidence in source code?
+- Does any code behaviour exceed or contradict what contracts declare?
+
+**2. contracts/ vs tests**
+- Does every contract entry have at least one corresponding test?
+- Are tests asserting the correct contract schema (not internal implementation details)?
+
+**3. CI workflows vs ci-gates declarations**
+- Does every gate declared in contracts/ci/ci-gate-contract.md exist in .github/workflows/?
+- Are required gates non-skippable?
+
+By default, do NOT read `specs/changes/` history. Only read historical change records when the user explicitly asks for cross-iteration traceability or historical investigation ("why was X decided?"). Contracts are the authority.
 
 ## Cadence and automation
 
 - Cadence — before every release to main; weekly during active multi-iteration work; ad-hoc when QA finds unexplained behavior.
 - Automatable — file existence, traceability term presence, contract column completeness, CI step presence (already covered by `validate_*.py` scripts).
-- Manual-only — semantic correctness ("does the spec actually describe what shipped?"), archive currency ("does this archive still reflect today's standard?"), cross-iteration redundancy.
-- Sunset policy — archived specs older than 12 months that conflict with current contracts must be either updated, marked superseded, or moved to `specs/archive/_deprecated/`.
+- Manual-only — semantic correctness ("does the spec actually describe what shipped?"), cross-iteration redundancy.
 
 ## Output
 
@@ -43,19 +48,17 @@ Multi-iteration development creates drift. Find it before it becomes production
 
 ## CI/Test Drift
 ...
-
-## Archive Actions Needed
-...
 ```
 
 ## Machine-Verifiable Evidence
 
-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`.
+Write this block to `specs/audits/<YYYY-MM-DD>-drift-audit.md` (create the file yourself).
+Use this exact structure (lines starting with `- ` are required):
 
 ```
 ## Agent Log
 # Spec Drift Auditor Log
-- change-id: <id>
+- audit-id: <YYYY-MM-DD>-drift
 - timestamp: <ISO 8601, e.g. 2026-04-27T14:30:00Z>
 - status: complete | needs-review | blocked
 - artifacts:
@@ -67,12 +70,11 @@ After completing your task, include an **## Agent Log** section at the end of yo
 ### Required artifacts for this agent
 - `surfaces-audited`: list (specs/contracts/code/tests/CI/tasks/archive)
 - `drift-items`: count + severity
-- `drift-summary-path`: path
+- `drift-summary-path`: `specs/audits/<YYYY-MM-DD>-drift-audit.md`
 - `next-audit-due`: ISO date
 
 ### Rules
-- NEVER omit this log file. `cdd-kit gate` rejects changes whose agent-log
-  is missing the `status:` line or has an invalid status.
+- NEVER omit this audit summary file. The drift-audit cadence (release / weekly / ad-hoc) requires this file as its persistence record; missing `status:` voids the audit.
 - If you cannot complete the task, set `status: blocked` and write a
   concrete `next-action` (NOT "investigate further" — write the actual
   next step a human can act on).

package/assets/agents/test-strategist.md

@@ -29,43 +29,40 @@ Design tests before implementation. Prefer concrete test cases, inputs, expected
 
 ## Output
 
-```md
-# Test Plan
+Write to `specs/changes/<change-id>/test-plan.md` using this structure:
 
-## Acceptance Criteria Mapping
-| requirement | test family | test file/spec | expected evidence |
-|---|---|---|---|
-
-## Unit Tests
-...
-
-## Contract Tests
-...
+```markdown
+# Test Plan: <change-id>
 
-## Integration Tests
-...
+## Acceptance Criteria → Test Mapping
+| criterion id | test family | test file path | tier |
+|---|---|---|---|
 
-## E2E Tests
-...
+## Test Families Required
+| family | tier | notes |
+|---|---|---|
+| (unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak) | | |
 
-## Data Boundary Tests
-...
+## Out of Scope
 
-## Resilience Tests
-...
+## Notes
+(Keep under 10 lines. Implementation detail belongs in the test files themselves.)
+```
 
-## Monkey Operation Tests
-...
+## Output discipline
 
-## Stress / Soak Tests
-...
+Your output goes into `specs/changes/<id>/test-plan.md`. It must answer WHAT to test and WHY — not HOW to implement the tests.
 
-## Mutation Checks
-...
+- **DO** write: acceptance criteria → test family mapping (table)
+- **DO** write: test file paths and test function names (one line each, no body)
+- **DO** write: tier assignment per test family
+- **DO NOT** write: full test function bodies
+- **DO NOT** write: mock setup details, fixture data, or expected JSON payloads
+- **DO NOT** write: per-test input/output tables with more than 15 rows
+- **DO NOT** write: example assertions or test helper code
 
-## Commands
-...
-```
+Implementation detail belongs in the test files, not in test-plan.md.
+Target: `test-plan.md` ≤ 100 lines.
 
 ## Machine-Verifiable Evidence
 

package/assets/ci-templates/conda.yml

@@ -1,7 +1,7 @@
 - uses: conda-incubator/setup-miniconda@v3
   with:
     environment-file: environment.yml
-    activate-environment: ""  # 空字串讓 conda 從 environment.yml 讀 name
+    activate-environment: "{{conda-env-name}}"
     auto-activate-base: false
 - name: Lint + Type + Test
   shell: bash -el {0}

package/assets/{ci/github-actions → github-workflows}/contract-driven-gates.yml

@@ -1,10 +1,12 @@
 # Contract-driven gates baseline (provided by cdd-kit).
-# Contract validation steps run as-is; application/test commands MUST be customized for your stack.
-# See README.md and ci/gate-policy.md for tier semantics and promotion policy.
+# Application/test commands MUST be customized for your stack.
+# See ci/gate-policy.md for tier semantics and promotion policy.
 
 name: contract-driven-gates
 
 on:
+  push:
+    branches: [main, master]
   pull_request:
   workflow_dispatch:
   schedule:
@@ -21,23 +23,16 @@ jobs:
         with:
           python-version: '3.10'
 
-      - name: Detect project profile
-        run: python .claude/skills/contract-driven-delivery/scripts/detect_project_profile.py . --write project-profile.generated.md || true
-
-      - name: Validate contracts
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_contracts.py .
-
-      - name: Validate env contract
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_env_contract.py contracts/env/env-contract.md
-
-      - name: Validate ci gates
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_ci_gates.py
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
 
-      - name: Validate spec traceability
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_spec_traceability.py
+      - name: Install cdd-kit
+        run: npm install -g contract-driven-delivery
 
-      - name: Validate contract versions
-        run: python .claude/skills/contract-driven-delivery/scripts/validate_contract_versions.py .
+      - name: Validate contracts and gates
+        run: cdd-kit validate
 
       - name: Repository-specific fast gate
         run: |

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

@@ -186,3 +186,9 @@ Next step: /cdd-new <describe the gap or feature to address first>
 - 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`
+
+---
+
+## After Completion
+
+The `/cdd-init` workflow is now complete. **Return to normal assistant mode immediately.** Answer any question the user asks — including questions unrelated to this project, new feature discussions, or general conversation — without requiring them to use a specific command. Do not wait for a commit or any other action before resuming normal behavior.

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

@@ -5,6 +5,42 @@ description: Start a new tracked change. Scaffolds all required artifacts, class
 
 # cdd-new — New Change Request
 
+## Mental model
+
+- `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)
+- `CLAUDE.md` = what this project is and how to start work
+
+## Spec depth rules
+
+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
+
+**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/
+- 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)
+- Test file paths and test names (one line per test, no implementation detail)
+- Tier assignment per family
+- Out-of-scope list
+
+**design.md should contain:**
+- Architecture summary (1 paragraph)
+- Affected components (table: component | file path | nature of change)
+- Key decisions and rejected alternatives (prose)
+- Migration/rollback strategy (prose, not SQL)
+
 ## 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").
@@ -26,6 +62,14 @@ If no description is provided, ask the user: "Please describe the change you wan
 
 ---
 
+## Artifact opt-in policy
+
+Only create optional artifacts (`current-behavior.md`, `proposal.md`, `spec.md`, `design.md`, `qa-report.md`, `regression-report.md`, `archive.md`) when the classifier's `change-classification.md` explicitly marks them as `yes`.
+
+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 5 always-required artifacts are: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`.
+
 ## Step 1: Generate change-id and scaffold
 
 Derive a `change-id` from the description:
@@ -243,24 +287,28 @@ If any agent sets `status: blocked` in its log, halt immediately and report the
 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
 
-3. **`spec-architect`** (write-capable) — only if the classifier flagged an architectural boundary or cross-module impact.
+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.
    - YOU tick: `4.1` and/or `4.3` based on scope
+   - Note: `tasks.md` 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).
 
 5. **`frontend-engineer`** (write-capable) — if the change touches UI, components, or client-side behavior. Writes implementation and its own agent-log.
    - YOU tick: `4.2`
 
 6. **`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.md`
    - YOU tick: applicable security-related items
 
 7. **`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.md`
    - YOU tick: `5.1`
 
 8. **`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.md`
    - YOU tick: `5.2`
 
@@ -293,6 +341,8 @@ All agents from Tier 2–3, plus insert these after `frontend-engineer` / `backe
 - If backend-only with no UI: skip `frontend-engineer`, `ui-ux-reviewer`, `visual-reviewer`
 - If UI-only with no backend: skip `backend-engineer`
 
+**Resuming from blocked**: After the user resolves the blocking issue, re-invoke the blocked agent (do not restart from Step 1). Continue with the remaining agents in their original order.
+
 ---
 
 ## Step 4: Run the gate
@@ -314,6 +364,8 @@ cdd-kit gate <change-id>
 4. Re-run `cdd-kit gate <change-id>`
 5. Repeat until gate passes (max 3 iterations; if still failing after 3, report to user)
 
+**Terminal state after 3 failures**: Add a line at the top of `tasks.md` reading `status: gate-blocked` and report all blocking items to the user. The change is paused — do not proceed to Step 5.
+
 ---
 
 ## Step 5: Report to user
@@ -364,3 +416,9 @@ Please review the above items and re-run: cdd-kit gate <change-id>
 - 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
 - Tick the relevant `tasks.md` 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.

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

@@ -11,17 +11,23 @@
 - isolated / module-level / cross-module / system-wide
 
 ## Required Artifacts
-| artifact | required | reason |
-|---|---:|---|
-| current-behavior.md |  |  |
-| proposal.md |  |  |
-| spec.md |  |  |
-| design.md |  |  |
-| contracts.md |  |  |
-| test-plan.md | yes | every implementation change requires test planning |
-| ci-gates.md | yes | every implementation change requires CI/CD gate planning |
-| qa-report.md |  |  |
-| regression-report.md |  |  |
+
+The following 5 artifacts are always required for implementation changes:
+`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+
+Optional artifacts — only create when explicitly needed:
+
+| artifact | create? (yes / no) | reason |
+|---|---|---|
+| current-behavior.md | no | |
+| proposal.md | no | |
+| spec.md | no | |
+| design.md | no | |
+| qa-report.md | no | |
+| regression-report.md | no | |
+| archive.md | no | |
+
+Default is **no**. Change classifier must explicitly set `yes` with a reason.
 
 ## Required Contracts
 - API:

package/assets/skills/contract-driven-delivery/templates/design.md

@@ -1,23 +1,26 @@
-# Technical Design
+---
+change-id: <id>
+schema-version: 0.1.0
+last-changed: <date>
+---
 
-## Architecture Summary
+# Design: <change-id>
 
-## Affected Components
-
-## API Design
+## Summary
 
-## Data / Schema Design
+(1 paragraph: what changes architecturally and why)
 
-## UI / UX Design
+## Affected Components
 
-## Env / Config Design
+| component | file path(s) | nature of change |
+|---|---|---|
 
-## Error Handling
+## Key Decisions
 
-## Performance Considerations
+- **Decision**: rationale — rejected alternative: reason rejected
 
-## Security Considerations
+## Migration / Rollback
 
-## Deployment / Rollback
+(Prose description. SQL and code go in migration files, not here.)
 
-## Architecture Decision Notes
+## Open Risks

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

@@ -1,31 +1,25 @@
-# Test Plan
+---
+change-id: <id>
+schema-version: 0.1.0
+last-changed: <date>
+risk: low | medium | high
+tier: 0 | 1 | 2 | 3 | 4 | 5
+---
 
-## Acceptance Criteria Mapping
-| requirement | test family | planned file/spec | expected evidence |
-|---|---|---|---|
-
-## Unit Tests
-
-## Contract Tests
-
-## Integration Tests
+# Test Plan: <change-id>
 
-## E2E Tests
+## Acceptance Criteria → Test Mapping
 
-## Visual Tests / Review
-
-## Data Boundary Tests
-
-## Resilience Tests
-
-## Fuzz / Monkey Operation Tests
+| criterion id | test family | test file path | tier |
+|---|---|---|---|
+| AC-1 | unit | tests/unit/test_xxx.py | 0 |
 
-## Stress Tests
+## Test Families Required
 
-## Soak Tests
+Mark all that apply: unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak
 
-## Mutation Checks
+## Out of Scope
 
-## Commands
+## Notes
 
-## CI/CD Gate Mapping
+(Keep this section under 10 lines. Implementation detail belongs in the test files themselves.)

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

@@ -11,17 +11,23 @@
 - isolated / module-level / cross-module / system-wide
 
 ## Required Artifacts
-| artifact | required | reason |
-|---|---:|---|
-| current-behavior.md |  |  |
-| proposal.md |  |  |
-| spec.md |  |  |
-| design.md |  |  |
-| contracts.md |  |  |
-| test-plan.md | yes | every implementation change requires test planning |
-| ci-gates.md | yes | every implementation change requires CI/CD gate planning |
-| qa-report.md |  |  |
-| regression-report.md |  |  |
+
+The following 5 artifacts are always required for implementation changes:
+`change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+
+Optional artifacts — only create when explicitly needed:
+
+| artifact | create? (yes / no) | reason |
+|---|---|---|
+| current-behavior.md | no | |
+| proposal.md | no | |
+| spec.md | no | |
+| design.md | no | |
+| qa-report.md | no | |
+| regression-report.md | no | |
+| archive.md | no | |
+
+Default is **no**. Change classifier must explicitly set `yes` with a reason.
 
 ## Required Contracts
 - API:

package/assets/specs-templates/design.md

@@ -1,23 +1,26 @@
-# Technical Design
+---
+change-id: <id>
+schema-version: 0.1.0
+last-changed: <date>
+---
 
-## Architecture Summary
+# Design: <change-id>
 
-## Affected Components
-
-## API Design
+## Summary
 
-## Data / Schema Design
+(1 paragraph: what changes architecturally and why)
 
-## UI / UX Design
+## Affected Components
 
-## Env / Config Design
+| component | file path(s) | nature of change |
+|---|---|---|
 
-## Error Handling
+## Key Decisions
 
-## Performance Considerations
+- **Decision**: rationale — rejected alternative: reason rejected
 
-## Security Considerations
+## Migration / Rollback
 
-## Deployment / Rollback
+(Prose description. SQL and code go in migration files, not here.)
 
-## Architecture Decision Notes
+## Open Risks

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

@@ -1,31 +1,25 @@
-# Test Plan
+---
+change-id: <id>
+schema-version: 0.1.0
+last-changed: <date>
+risk: low | medium | high
+tier: 0 | 1 | 2 | 3 | 4 | 5
+---
 
-## Acceptance Criteria Mapping
-| requirement | test family | planned file/spec | expected evidence |
-|---|---|---|---|
-
-## Unit Tests
-
-## Contract Tests
-
-## Integration Tests
+# Test Plan: <change-id>
 
-## E2E Tests
+## Acceptance Criteria → Test Mapping
 
-## Visual Tests / Review
-
-## Data Boundary Tests
-
-## Resilience Tests
-
-## Fuzz / Monkey Operation Tests
+| criterion id | test family | test file path | tier |
+|---|---|---|---|
+| AC-1 | unit | tests/unit/test_xxx.py | 0 |
 
-## Stress Tests
+## Test Families Required
 
-## Soak Tests
+Mark all that apply: unit / contract / integration / e2e / data-boundary / resilience / monkey / stress / soak
 
-## Mutation Checks
+## Out of Scope
 
-## Commands
+## Notes
 
-## CI/CD Gate Mapping
+(Keep this section under 10 lines. Implementation detail belongs in the test files themselves.)

package/dist/cli/index.js

@@ -26,6 +26,7 @@ var ASSET = {
   specsTemplates: join(ASSETS_DIR, "specs-templates"),
   testsTemplates: join(ASSETS_DIR, "tests-templates"),
   ci: join(ASSETS_DIR, "ci"),
+  githubWorkflows: join(ASSETS_DIR, "github-workflows"),
   hooks: join(ASSETS_DIR, "hooks"),
   claudeTemplate: join(ASSETS_DIR, "CLAUDE.template.md"),
   agentsTemplate: join(ASSETS_DIR, "AGENTS.template.md")
@@ -224,6 +225,18 @@ function detectStack(repoRoot) {
 }
 
 // src/commands/init.ts
+function readCondaEnvName(cwd) {
+  const envYml = join4(cwd, "environment.yml");
+  if (!existsSync3(envYml))
+    return "base";
+  try {
+    const content = readFileSync2(envYml, "utf8");
+    const match = content.match(/^name:\s*(.+)$/m);
+    return match ? match[1].trim() : "base";
+  } catch {
+    return "base";
+  }
+}
 function loadCiTemplate(stack) {
   const templatePath = join4(ASSETS_DIR, "ci-templates", `${stack}.yml`);
   if (!existsSync3(templatePath))
@@ -326,6 +339,13 @@ async function init(opts) {
       );
       track(ciCreated);
       log.ok(`ci/ \u2014 ${ciCount} file(s) written.`);
+      const { count: wfCount, created: wfCreated } = copyDirTracked(
+        ASSET.githubWorkflows,
+        join4(cwd, ".github", "workflows"),
+        { overwrite: opts.force, label: ".github/workflows" }
+      );
+      track(wfCreated);
+      log.ok(`.github/workflows/ \u2014 ${wfCount} file(s) written.`);
       const detection = detectStack(cwd);
       if (detection.polyglot) {
         const PYTHON_STACKS = ["conda", "poetry", "uv", "pip"];
@@ -345,12 +365,17 @@ async function init(opts) {
       } else {
         log.warn("Could not detect stack \u2014 CI placeholder left in place.");
       }
-      const ciYmlDest = join4(cwd, "ci", "github-actions", "contract-driven-gates.yml");
+      const ciYmlDest = join4(cwd, ".github", "workflows", "contract-driven-gates.yml");
       if (existsSync3(ciYmlDest)) {
         const template = loadCiTemplate(detection.primary);
         if (template) {
           const original = readFileSync2(ciYmlDest, "utf8");
-          const patched = patchFastGateYml(original, template, detection.primary);
+          let patched = patchFastGateYml(original, template, detection.primary);
+          if (detection.primary === "conda" && patched.includes("{{conda-env-name}}")) {
+            const envName = readCondaEnvName(cwd);
+            patched = patched.replace(/\{\{conda-env-name\}\}/g, envName);
+            log.ok(`Conda environment name set to: ${envName}`);
+          }
           if (patched !== original) {
             writeFileSync(ciYmlDest, patched, "utf8");
             log.ok(`CI fast-gate patched for stack: ${detection.primary}`);

package/package.json

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