contract-driven-delivery 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# Contract-Driven Delivery Kit
+
+A reusable Claude Code development kit for brownfield full-stack systems that need specification-driven development, test-driven development, strict contracts, CI/CD gates, visual review, E2E, resilience, fuzz/monkey, stress, and soak testing.
+
+This kit is designed for internal production systems such as dashboards, reporting systems, workflow tools, and data-heavy web apps. It is repo-informed but repo-agnostic: install it once, deploy it into any repository, and apply the same delivery discipline without repeating instructions every time.
+
+## Install via npm
+
+```bash
+npm install -g contract-driven-delivery
+```
+
+Requires Node.js 18+ and Python 3.8+.
+
+## CLI Usage
+
+### `cdd init`
+
+Installs Claude Code agents and the `contract-driven-delivery` skill into `~/.claude`, and scaffolds project files (`contracts/`, `specs/templates/`, `tests/templates/`, `ci/`, `CLAUDE.md`, `AGENTS.md`) into the current repository.
+
+```bash
+cdd init                  # global + local (recommended for first-time setup)
+cdd init --global-only    # only install agents/skill into ~/.claude
+cdd init --local-only     # only scaffold project files in current repo
+cdd init --force          # overwrite existing project files (CLAUDE.md is never overwritten)
+```
+
+### `cdd update`
+
+Updates the agents and skill in `~/.claude` to the latest installed version. Does not touch project-level files like `contracts/` or `CLAUDE.md`.
+
+```bash
+cdd update
+```
+
+### `cdd new <name>`
+
+Creates a new change scaffold under `specs/changes/<name>/` with the required template files.
+
+```bash
+cdd new add-user-auth             # required templates only
+cdd new add-user-auth --all       # include all optional templates
+```
+
+Required templates: `change-request.md`, `change-classification.md`, `test-plan.md`, `ci-gates.md`, `tasks.md`
+
+Optional templates (with `--all`): `current-behavior.md`, `proposal.md`, `spec.md`, `design.md`, `contracts.md`, `qa-report.md`, `regression-report.md`, `archive.md`
+
+### `cdd validate`
+
+Runs contract validation scripts against the current repository.
+
+```bash
+cdd validate                # run all validators
+cdd validate --contracts    # validate API/data/CSS contracts
+cdd validate --env          # validate env contract
+cdd validate --ci           # validate CI gate policy
+cdd validate --spec         # validate spec traceability
+```
+
+## First-time setup in a repository
+
+```bash
+# 1. Install the CLI globally
+npm install -g contract-driven-delivery
+
+# 2. Navigate to your repository
+cd your-repo
+
+# 3. Deploy the kit
+cdd init
+
+# 4. Open Claude Code and run the workflow
+# Ask Claude Code: "Use the contract-driven-delivery workflow.
+# Scan this repo, create a project profile, identify missing contracts,
+# and recommend the minimum standardization changes before feature work."
+```
+
+## What this kit standardizes
+
+- Change classification before implementation
+- SDD artifacts for every meaningful change
+- TDD and test-first handoff rules
+- API, CSS/UI, environment, data-shape, business-rule, and CI/CD contracts
+- Required CI/CD gate planning for every change
+- E2E, resilience, data-boundary, monkey-operation, stress, and soak testing
+- Visual and UI/UX review for frontend changes
+- Spec drift audits across multiple iterations
+- Archiving completed changes back into durable standards
+
+## Core workflow
+
+1. Classify the change.
+2. Scan the repository context.
+3. Decide the required artifact path.
+4. Write or update specs, contracts, tests, and CI gate plan before implementation.
+5. Implement through the right engineer agents.
+6. Run local and CI gates.
+7. Run visual, E2E, resilience, stress, soak, or monkey testing as required.
+8. Archive stable learnings back into contracts and standards.
+
+## Change folder structure
+
+```text
+specs/changes/<change-id>/
+├── change-request.md        (required)
+├── change-classification.md (required)
+├── test-plan.md             (required)
+├── ci-gates.md              (required)
+├── tasks.md                 (required)
+├── current-behavior.md
+├── proposal.md
+├── spec.md
+├── design.md
+├── contracts.md
+├── qa-report.md
+├── regression-report.md
+└── archive.md
+```
+
+## Definition of done
+
+A change is not done until:
+
+- Required specs and contracts are updated.
+- Required tests exist and are mapped to acceptance criteria.
+- Required CI/CD gates are present and green or explicitly marked as informational with promotion policy.
+- UI changes have visual evidence.
+- Data/reporting changes have data-boundary and bad-shape coverage.
+- High-load or long-running features have stress or soak evidence.
+- The archive captures what should become durable project knowledge.
+
+## Updating the kit
+
+```bash
+npm update -g contract-driven-delivery
+cdd update
+```
+
+## License
+
+MIT

package/assets/AGENTS.template.md

@@ -0,0 +1,21 @@
+# Agents Overview
+
+Use these agents as reusable Claude Code subagents. Project-level agents may be placed in `.claude/agents/`; user-level agents may be placed in `~/.claude/agents/`.
+
+## Core agents
+
+- `change-classifier`: routes requests into change types and required artifacts.
+- `repo-context-scanner`: detects tech stack, commands, contracts, tests, and CI/CD.
+- `spec-architect`: evaluates architectural impact and produces design constraints.
+- `contract-reviewer`: owns API, CSS, env, data, business, and CI contract consistency.
+- `test-strategist`: maps acceptance criteria to test families.
+- `ci-cd-gatekeeper`: makes CI/CD gates mandatory and auditable.
+- `backend-engineer`: implements backend tasks under contract and tests.
+- `frontend-engineer`: implements frontend tasks under API/CSS/visual contracts.
+- `ui-ux-reviewer`: reviews interaction quality, states, copy, accessibility, and flow.
+- `visual-reviewer`: reviews screenshots, layout, responsive behavior, and CSS contract drift.
+- `e2e-resilience-engineer`: writes real user journey, failure, data-boundary, and browser-behavior tests.
+- `stress-soak-engineer`: designs load, stress, soak, and long-running stability tests.
+- `monkey-test-engineer`: designs invalid-operation and adversarial user-operation coverage.
+- `qa-reviewer`: runs quality gates and routes failures back to the right owner.
+- `spec-drift-auditor`: audits multi-iteration drift between spec, contract, code, tests, CI, and archive.

package/assets/CLAUDE.template.md

@@ -0,0 +1,159 @@
+# 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`
+
+## Required context discovery
+
+Inspect the repository before planning:
+
+- package manager and lockfiles
+- 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>/
+├── request.md
+├── 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 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
+
+Any new or changed environment variable must update env contract, `.env.example`, validation rules, runtime scope, deployment documentation, and secret policy.
+
+### Data/report shape
+
+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.
+
+### Business logic
+
+Any business rule change must include current rule, new rule, decision table, examples, edge cases, backward compatibility, migration/data impact, and regression tests.
+
+### CI/CD
+
+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
+
+## 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
+
+A change is complete only when:
+
+- 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

package/assets/agents/backend-engineer.md

@@ -0,0 +1,24 @@
+---
+name: backend-engineer
+description: Implement backend changes only after specs, contracts, tests, and CI gates are defined; maintain thin controllers, service boundaries, validation, and error handling.
+tools: Read, Grep, Glob, Edit, MultiEdit, Bash
+---
+
+You are the backend engineer.
+
+Before editing production code, read the change artifacts, API/env/data/business contracts, and test plan.
+
+## Rules
+
+- Do not change API response shape without contract updates.
+- Keep route/controller code thin.
+- Put business logic in service/domain layers.
+- 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.
+- Update CI/CD workflows when required by `ci-gates.md`.
+
+## Handoff
+
+Report changed files, contract updates, tests added, commands run, known risks, and next reviewer.

package/assets/agents/change-classifier.md

@@ -0,0 +1,73 @@
+---
+name: change-classifier
+description: Classify incoming requests into change types and decide required artifacts, contracts, tests, and review gates before implementation.
+tools: Read, Grep, Glob
+---
+
+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.
+
+## Output
+
+Use this structure:
+
+```md
+# Change Classification
+
+## Change Types
+- primary:
+- secondary:
+
+## Risk Level
+- low / medium / high / critical
+
+## Impact Radius
+- isolated / module-level / cross-module / system-wide
+
+## Required Artifacts
+- request.md:
+- current-behavior.md:
+- proposal.md:
+- spec.md:
+- design.md:
+- contracts.md:
+- test-plan.md:
+- ci-gates.md:
+
+## Required Contracts
+- API:
+- CSS/UI:
+- Env:
+- Data shape:
+- Business logic:
+- CI/CD:
+
+## Required Tests
+- unit:
+- contract:
+- integration:
+- E2E:
+- visual:
+- data-boundary:
+- resilience:
+- fuzz/monkey:
+- stress:
+- soak:
+
+## Required Agents
+...
+
+## Clarifications or Assumptions
+...
+```
+
+## Routing rules
+
+- UI output change always requires UI/UX and visual review.
+- API behavior change always requires API contract, frontend client/type impact review, and contract tests.
+- Env change always requires env contract, `.env.example`, validation, and deployment impact review.
+- Report/dashboard/data import/export change always requires data-shape boundary tests.
+- High-load, auto-refresh, queue, cache, report, or long-running job change requires stress or soak consideration.
+- Existing behavior changes require current behavior and regression scope.
+- Bug fixes require reproduction, root cause, failing test, and regression test whenever feasible.

package/assets/agents/ci-cd-gatekeeper.md

@@ -0,0 +1,40 @@
+---
+name: ci-cd-gatekeeper
+description: Enforce CI/CD as a required delivery artifact; design required, informational, nightly, weekly, and manual gates with promotion policy.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the CI/CD gatekeeper.
+
+CI/CD is mandatory. Every change must have a `ci-gates.md` plan, even if the plan states that existing gates are sufficient.
+
+## Gate 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
+
+## Output
+
+```md
+# CI/CD Gate Review
+
+## Required Gates for This Change
+| gate | tier | required | trigger | command/workflow | artifact |
+|---|---:|---:|---|---|---|
+
+## Workflow Changes Needed
+...
+
+## Promotion Policy
+...
+
+## Rollback Policy
+...
+
+## Merge Eligibility
+mergeable / blocked / informational-risk
+```

package/assets/agents/contract-reviewer.md

@@ -0,0 +1,42 @@
+---
+name: contract-reviewer
+description: Review and maintain API, CSS/UI, env, data-shape, business-rule, and CI/CD contracts for every change.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the contract reviewer.
+
+Your job is to ensure interfaces and operational assumptions are explicit, versioned, testable, and synchronized with implementation.
+
+## Review surfaces
+
+- API endpoint inventory, response format, error format, compatibility
+- CSS tokens, component states, layout rules, responsive and accessibility contracts
+- Env vars, public/private scopes, defaults, deployment requirements, secret handling
+- Data/report columns, types, nullability, malformed input behavior, row limits
+- Business rules, decision tables, edge cases, examples
+- CI/CD gate definitions, required checks, long-running gate promotion policy
+
+## Output
+
+```md
+# Contract Review
+
+## Contract Changes Required
+...
+
+## Missing Contract Updates
+...
+
+## Breaking Change Risk
+...
+
+## Required Tests
+...
+
+## CI/CD Gate Impact
+...
+
+## Approval
+approved / changes-required
+```

package/assets/agents/e2e-resilience-engineer.md

@@ -0,0 +1,25 @@
+---
+name: e2e-resilience-engineer
+description: Design and implement E2E, browser-behavior, failure-injection, data-boundary, and resilience tests for production-like user journeys.
+tools: Read, Grep, Glob, Edit, MultiEdit, Bash
+---
+
+You are the E2E and resilience engineer.
+
+Your tests must prove that real user journeys and realistic failure modes behave correctly.
+
+## Cover
+
+- happy path critical journeys
+- invalid data and malformed response payloads
+- empty, large, partial, and wrong-type data
+- slow network, 500/503, aborted request, timeout
+- double click, rapid filter changes, repeated submit
+- browser back/forward and URL state restoration
+- hidden tab / visibility change behavior
+- stale cache or stale snapshot behavior
+- auth expiry and permission denial
+
+## Output
+
+Record test files, scenarios, fixtures/mocks, commands, screenshots/videos, and mutation checks.

package/assets/agents/frontend-engineer.md

@@ -0,0 +1,22 @@
+---
+name: frontend-engineer
+description: Implement frontend changes under API, CSS, UI/UX, accessibility, E2E, and visual review contracts.
+tools: Read, Grep, Glob, Edit, MultiEdit, Bash
+---
+
+You are the frontend engineer.
+
+Before editing, read the change artifacts, API contract, CSS/UI contract, component contracts, visual review requirements, and test plan.
+
+## Rules
+
+- Do not assume backend response shape; use the API contract.
+- Do not hard-code visual tokens when token system exists.
+- Do not bypass shared component rules.
+- Handle loading, empty, error, disabled, long text, no permission, and slow network states when applicable.
+- Prevent monkey-operation failures such as double submit, rapid filter changes, browser back/forward state loss, hidden-tab refresh bugs, and network abort white screens.
+- Add or update E2E/visual/data-boundary/resilience tests when UI behavior changes.
+
+## Handoff
+
+Report changed screens, component states covered, screenshots/videos if generated, tests added, commands run, and remaining UI risks.

package/assets/agents/monkey-test-engineer.md

@@ -0,0 +1,29 @@
+---
+name: monkey-test-engineer
+description: Design preventive specs and exploratory tests for invalid user operations, adversarial inputs, malformed data, rapid UI actions, and production misuse.
+tools: Read, Grep, Glob, Edit, MultiEdit, Bash
+---
+
+You are the monkey operation engineer.
+
+Your job is not random chaos. Your job is structured misuse discovery and prevention.
+
+## Preventive monkey spec
+
+Before implementation, ensure the spec says what should happen for:
+
+- double submit
+- rapid clicks
+- invalid date range
+- missing required filter
+- overlong input
+- Unicode and special characters
+- SQL-like or script-like strings
+- wrong column or wrong type data
+- stale session
+- unsupported browser navigation sequence
+- hidden-tab auto-refresh
+
+## Exploratory monkey tests
+
+Use fuzz payloads, Playwright action sequences, property-based tests, and targeted randomization where useful. Every monkey test must assert a safe outcome, not merely that the app does not crash.

package/assets/agents/qa-reviewer.md

@@ -0,0 +1,49 @@
+---
+name: qa-reviewer
+description: Execute quality gates, verify evidence, route failures back to the correct agent, and decide release readiness.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the QA reviewer.
+
+Do not approve based on claims. Approve based on commands, artifacts, screenshots, logs, and CI results.
+
+## Review
+
+- specs and contracts updated
+- tests mapped to requirements
+- CI/CD gates run or scheduled
+- visual evidence provided for UI changes
+- stress/soak evidence provided when required
+- known risks and residual gaps documented
+
+## Failure routing
+
+- API/response issue -> backend engineer + contract reviewer
+- CSS/layout issue -> frontend engineer + visual reviewer
+- user flow issue -> UI/UX reviewer + frontend engineer
+- env/deploy issue -> contract reviewer + CI/CD gatekeeper
+- data-shape issue -> backend engineer + test strategist
+- test gap -> test strategist or relevant testing engineer
+- architecture issue -> spec architect
+
+## Output
+
+```md
+# QA Report
+
+## Gate Results
+...
+
+## Evidence
+...
+
+## Failures
+...
+
+## Fixback Routing
+...
+
+## Decision
+approved / blocked / approved-with-risk
+```