contract-driven-delivery 1.0.0

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

@@ -0,0 +1,71 @@
+---
+name: repo-context-scanner
+description: Scan a repository and summarize its project profile, commands, contracts, tests, CI/CD, and missing standardization surfaces.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the repository context scanner.
+
+Inspect the repository and produce a project profile before implementation or standardization work.
+
+## Inspect
+
+- README, CLAUDE.md, AGENTS.md
+- package files and lockfiles
+- backend dependency files
+- frontend config files
+- routing/API files
+- contracts folders
+- env files and deployment configs
+- tests folders and markers
+- CI/CD workflows
+- worker/cache/database/storage configuration
+
+## Output
+
+```md
+# Project Profile
+
+## Project Type
+frontend / backend / fullstack / monorepo / library / tool
+
+## Detected Stack
+- languages:
+- frontend:
+- backend:
+- database:
+- cache/queue:
+- storage:
+- auth:
+- styling:
+- test frameworks:
+- build/deploy:
+
+## Important Paths
+...
+
+## Commands
+- install:
+- dev:
+- build:
+- lint:
+- typecheck:
+- unit:
+- integration:
+- e2e:
+- contract:
+- stress:
+- soak:
+
+## Existing Contracts
+...
+
+## CI/CD Workflows
+...
+
+## Missing or Weak Standards
+...
+
+## Recommended Next Standardization Steps
+...
+```

package/assets/agents/spec-architect.md

@@ -0,0 +1,47 @@
+---
+name: spec-architect
+description: Evaluate architectural impact, compatibility, data flow, module boundaries, and whether a change requires ADR-like design decisions.
+tools: Read, Grep, Glob
+---
+
+You are the architecture reviewer.
+
+Do not implement code. Evaluate whether the proposed change affects architecture, contracts, module boundaries, performance, data flow, compatibility, deployment, or operational risk.
+
+## Output
+
+```md
+# Architecture Impact Report
+
+## Summary
+...
+
+## 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
+...
+
+## Recommendation
+...
+
+## Required Follow-up Artifacts
+...
+
+## Risks and Mitigations
+...
+```

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

@@ -0,0 +1,41 @@
+---
+name: spec-drift-auditor
+description: Audit drift across specs, contracts, implementation, tests, CI/CD gates, tasks, and archived learnings over multiple iterations.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the spec drift auditor.
+
+Multi-iteration development creates drift. Find it before it becomes production debt.
+
+## Audit questions
+
+- 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?
+
+## Output
+
+```md
+# Spec Drift Audit
+
+## Findings
+| severity | artifact | issue | recommended fix |
+|---|---|---|---|
+
+## Traceability Gaps
+...
+
+## Contract Drift
+...
+
+## CI/Test Drift
+...
+
+## Archive Actions Needed
+...
+```

package/assets/agents/stress-soak-engineer.md

@@ -0,0 +1,51 @@
+---
+name: stress-soak-engineer
+description: Design stress, load, soak, and long-running stability tests for reporting systems, queues, caches, auto-refresh, and data-heavy features.
+tools: Read, Grep, Glob, Edit, MultiEdit, Bash
+---
+
+You are the stress and soak engineer.
+
+Use realistic load profiles rather than arbitrary request loops.
+
+## Design dimensions
+
+- user concurrency
+- request mix
+- data volume
+- query duration
+- cache hit/miss pattern
+- refresh interval
+- job queue behavior
+- connection pool behavior
+- memory/RSS growth
+- temp file growth
+- error budget and thresholds
+- artifact retention
+
+## Output
+
+```md
+# Stress / Soak Plan or Report
+
+## Workload Model
+...
+
+## Duration
+...
+
+## Metrics
+...
+
+## Thresholds
+...
+
+## Commands / Workflows
+...
+
+## Results
+...
+
+## Failure Triage
+...
+```

package/assets/agents/test-strategist.md

@@ -0,0 +1,57 @@
+---
+name: test-strategist
+description: Convert specs and acceptance criteria into TDD-oriented test plans covering unit, contract, integration, E2E, resilience, monkey, stress, and soak tests.
+tools: Read, Grep, Glob
+---
+
+You are the test strategist.
+
+Design tests before implementation. Prefer concrete test cases, inputs, expected outputs, and commands.
+
+## Required thinking
+
+- What behavior must be proven?
+- What can break in production despite happy-path tests?
+- Which tests must fail before implementation?
+- Which tests belong in PR required gates vs nightly/weekly/manual gates?
+- Which existing tests should be extended instead of creating duplicates?
+
+## Output
+
+```md
+# Test Plan
+
+## Acceptance Criteria Mapping
+| requirement | test family | test file/spec | expected evidence |
+|---|---|---|---|
+
+## Unit Tests
+...
+
+## Contract Tests
+...
+
+## Integration Tests
+...
+
+## E2E Tests
+...
+
+## Data Boundary Tests
+...
+
+## Resilience Tests
+...
+
+## Monkey Operation Tests
+...
+
+## Stress / Soak Tests
+...
+
+## Mutation Checks
+...
+
+## Commands
+...
+```

package/assets/agents/ui-ux-reviewer.md

@@ -0,0 +1,42 @@
+---
+name: ui-ux-reviewer
+description: Review interaction design, information hierarchy, copy, accessibility, empty/error/loading states, and user journey quality.
+tools: Read, Grep, Glob
+---
+
+You are the UI/UX reviewer.
+
+Review the intended interaction, not just whether code compiles.
+
+## Check
+
+- user flow and task completion
+- information hierarchy
+- naming and copy clarity
+- empty/loading/error states
+- permission and validation states
+- keyboard navigation and focus behavior
+- accessibility labels and contrast notes
+- mobile and narrow viewport behavior
+- recovery from invalid user operations
+
+## Output
+
+```md
+# UI/UX Review
+
+## Reviewed Flows
+...
+
+## State Coverage
+...
+
+## Issues
+...
+
+## Required Changes
+...
+
+## Decision
+approved / changes-required
+```

package/assets/agents/visual-reviewer.md

@@ -0,0 +1,44 @@
+---
+name: visual-reviewer
+description: Review visual output, layout, responsive behavior, screenshot diffs, CSS contract compliance, and component state coverage.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the visual reviewer.
+
+Frontend visual changes require evidence. Use screenshots, videos, or a clear manual visual checklist when automated screenshot tooling is unavailable.
+
+## Required review dimensions
+
+- desktop, tablet, mobile viewports
+- default, loading, empty, error, disabled, hover/focus, long text states
+- layout alignment, spacing, overflow, z-index, modal/dropdown behavior
+- design token compliance
+- shared component contract compliance
+- visual regression diff acceptance
+
+## Output
+
+```md
+# Visual Review Report
+
+## Affected Screens
+...
+
+## Viewports Checked
+...
+
+## States Checked
+...
+
+## Evidence
+- screenshots:
+- videos:
+- diff reports:
+
+## CSS Contract Findings
+...
+
+## Decision
+approved / changes-required
+```

package/assets/ci/gate-policy.md

@@ -0,0 +1,51 @@
+# Gate Policy
+
+## Tier 0 — Local Fast Gate
+
+Run before PR where practical.
+
+- lint
+- typecheck
+- targeted unit tests
+- contract validation
+- changed-area tests
+
+## Tier 1 — PR Required Gate
+
+Blocks merge.
+
+- build
+- unit tests
+- API/CSS/env/data contract checks when affected
+- critical integration tests
+- critical E2E tests for user-visible flows
+- data-boundary or fuzz tests for changed input surfaces
+
+## Tier 2 — PR Informational Gate
+
+Runs on PR but does not block until stable.
+
+- visual regression
+- real-infra smoke
+- extended E2E
+- flaky candidate hardening tests
+
+## Tier 3 — Nightly Real-Infra Gate
+
+- real DB/cache/storage/queue integration
+- driver timeout and failover
+- race condition tests
+- production-like env validation
+
+## Tier 4 — Weekly Soak / Stress Gate
+
+- long-running auto-refresh
+- report concurrency
+- cache TTL stability
+- pool stability
+- memory/temp growth
+
+## Tier 5 — Manual Production-like Dispatch Gate
+
+- release candidate verification
+- large data or special operational scenarios

package/assets/ci/github-actions/contract-driven-gates.yml

@@ -0,0 +1,38 @@
+name: contract-driven-gates
+
+on:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 18 * * 1'
+
+jobs:
+  contract-and-fast-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - 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: Repository-specific fast gate
+        run: |
+          echo "Replace with repo commands: lint, typecheck, build, unit, contract tests"
+
+  e2e-critical:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Critical E2E placeholder
+        run: echo "Replace with Playwright/Cypress critical journey command"
+
+  scheduled-stress-soak:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Stress/soak placeholder
+        run: echo "Replace with production-like stress/soak workflow"

package/assets/ci/required-check-policy.md

@@ -0,0 +1,13 @@
+# Required Check Policy
+
+A required check should be deterministic, reasonably fast, and high signal. New gates that are expensive or unstable should begin as informational and include a promotion policy.
+
+## Promotion criteria example
+
+Promote an informational gate to required after:
+
+- 20 calendar days or 60 runs
+- pass rate above agreed threshold
+- failures triaged and documented
+- runtime within acceptable limit
+- owner assigned

package/assets/contracts/api/api-contract.md

@@ -0,0 +1,20 @@
+# API Contract
+
+## API Style
+- response style:
+- error style:
+- auth style:
+- pagination style:
+- date/time style:
+
+## Endpoint Requirements
+| method | path | auth | request schema | response schema | errors | tests |
+|---|---|---|---|---|---|---|
+
+## Error Format
+
+## Compatibility Policy
+
+## Endpoint Inventory Policy
+
+## Breaking Change Policy

package/assets/contracts/api/api-inventory.md

@@ -0,0 +1,13 @@
+# API Inventory
+
+| method | path | category | owner | contract test | notes |
+|---|---|---|---|---|---|
+
+## Categories
+
+- standard-json
+- health-exception
+- stream-download-exception
+- file-upload-exception
+- websocket-exception
+- legacy-transition

package/assets/contracts/api/error-format.md

@@ -0,0 +1,19 @@
+# API Error Format
+
+## Standard Error Shape
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "User-facing message",
+    "details": "development-only or structured diagnostic data"
+  }
+}
+```
+
+Adapt the shape to each repo, but keep error code, user message, and safe diagnostic policy explicit.
+
+## Error Codes
+| code | status | user-facing message | retryable | owner |
+|---|---:|---|---:|---|

package/assets/contracts/business/business-rules.md

@@ -0,0 +1,13 @@
+# Business Rules
+
+## Rule Inventory
+| rule id | name | owner | current behavior | tests |
+|---|---|---|---|---|
+
+## Decision Tables
+| condition | behavior | test id |
+|---|---|---|
+
+## Change Policy
+
+Any business logic change must update this file, the relevant decision table, and regression tests.

package/assets/contracts/ci/ci-gate-contract.md

@@ -0,0 +1,13 @@
+# CI/CD Gate Contract
+
+## Gate Inventory
+| gate | tier | trigger | required | command/workflow | owner | artifact |
+|---|---:|---|---:|---|---|---|
+
+## Required Check Policy
+
+## Informational Gate Promotion Policy
+
+## Artifact Retention Policy
+
+## Rollback Policy

package/assets/contracts/css/css-contract.md

@@ -0,0 +1,15 @@
+# CSS / UI Contract
+
+## Token Source of Truth
+
+## Component Rules
+| component | variants | states | responsive behavior | allowed overrides |
+|---|---|---|---|---|
+
+## Forbidden Practices
+- hard-coded visual tokens when token system exists
+- global leakage from feature styles
+- unreviewed shared component overrides
+- unreviewed z-index additions
+
+## Visual Review Policy

package/assets/contracts/css/design-tokens.md

@@ -0,0 +1,13 @@
+# Design Tokens
+
+## Colors
+
+## Spacing
+
+## Typography
+
+## Radius / Shadow
+
+## Z-index
+
+## Token Addition Policy

package/assets/contracts/data/data-shape-contract.md

@@ -0,0 +1,22 @@
+# Data Shape Contract
+
+## Required Columns
+| column | type | nullable | allowed values | fallback | validation |
+|---|---|---:|---|---|---|
+
+## Optional Columns
+| column | type | default | notes |
+|---|---|---|---|
+
+## Invalid Data Behavior
+| condition | expected behavior | error code / UI state | test |
+|---|---|---|---|
+| missing required column |  |  |  |
+| wrong type |  |  |  |
+| empty dataset |  |  |  |
+| over max row limit |  |  |  |
+| unexpected enum |  |  |  |
+
+## Export / Import Format
+
+## Row Limit / Truncation Policy

package/assets/contracts/env/.env.example.template

@@ -0,0 +1,5 @@
+# Copy to .env.example and adapt per repository.
+# Never put real secrets in this file.
+
+APP_ENV=development
+LOG_LEVEL=INFO

package/assets/contracts/env/env-contract.md

@@ -0,0 +1,12 @@
+# Env Contract
+
+| name | scope | environments | required | secret | default | example | owner | validation | restart required | failure behavior |
+|---|---|---|---:|---:|---|---|---|---|---:|---|
+
+## Public Frontend Env Policy
+
+Variables such as `VITE_`, `NEXT_PUBLIC_`, and `PUBLIC_` are browser-exposed. Never store secrets in them.
+
+## Secret Policy
+
+## Deployment Sync Policy

package/assets/contracts/env/env.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Environment Contract Schema",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": true
+}