contract-driven-delivery 1.0.0

package/assets/skill/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: contract-driven-delivery
+description: contract-driven delivery workflow for brownfield full-stack systems. use when handling software requests that require specification-driven development, test-driven development, api/css/env/data/business contracts, ci/cd gates, frontend visual review, e2e/resilience/monkey/stress/soak testing, qa fixback loops, or multi-iteration spec drift control.
+---
+
+# Contract-Driven Delivery
+
+## Purpose
+
+Use this skill to turn software requests into traceable, testable, CI/CD-gated changes. This skill is optimized for brownfield internal production systems such as dashboards, reporting apps, workflow tools, and data-heavy full-stack applications.
+
+## Workflow decision tree
+
+1. Classify the request.
+   - Use `references/workflow-router.md`.
+   - Create or update `classification.md`.
+2. Scan project context.
+   - Use `scripts/detect_project_profile.py` when useful.
+   - Capture stack, commands, contracts, tests, and CI/CD.
+3. Select required artifacts.
+   - Use templates in `templates/`.
+   - Do not force every artifact for tiny changes, but do require `classification.md`, `test-plan.md`, and `ci-gates.md` for implementation changes.
+4. Update contracts before or alongside implementation.
+   - API: `references/api-contract-standard.md`
+   - CSS/UI: `references/css-contract-standard.md`
+   - Env: `references/env-contract-standard.md`
+   - Data/report shape: `references/data-contract-standard.md`
+   - Business logic: `references/business-logic-standard.md`
+   - CI/CD: `references/ci-cd-policy.md`
+5. Apply SDD + TDD discipline.
+   - Use `references/sdd-tdd-policy.md`.
+   - Tests should be planned before implementation and should fail first when feasible.
+6. Implement through the right role.
+   - Backend/frontend work must follow contracts and tests.
+   - UI changes require UI/UX and visual review.
+7. Run quality gates.
+   - Use `references/qa-gates.md`.
+   - CI/CD gate plan is mandatory.
+8. Archive and audit drift.
+   - Use `references/spec-drift-policy.md`.
+   - Durable learnings must be promoted back to contracts or CLAUDE.md.
+
+## Required gates by risk
+
+### Low-risk documentation or prompt-only change
+
+- classification
+- affected artifact list
+- no implementation gate unless code behavior changes
+
+### Normal feature or enhancement
+
+- classification
+- current behavior if modifying existing feature
+- proposal/spec/design as needed
+- contracts
+- test-plan
+- ci-gates
+- tasks
+- QA report
+
+### UI change
+
+- CSS/UI contract review
+- UI/UX review
+- visual review evidence
+- E2E or component interaction coverage
+- accessibility check
+
+### API/backend/data/report change
+
+- API contract or data-shape contract
+- unit, contract, integration tests
+- route validation and fuzz tests for user-controlled inputs
+- E2E or smoke path when user-visible
+- CI/CD gate update
+
+### High-risk production-reality change
+
+Required when the change involves report generation, large queries, auto-refresh, cache, queues, workers, DB pools, exports, imports, long-running sessions, or concurrency.
+
+- resilience tests
+- data-boundary tests
+- monkey-operation tests
+- stress tests
+- soak tests or scheduled long-run gate
+- telemetry and threshold plan
+
+## Output discipline
+
+When using this skill, produce concrete artifact content instead of vague recommendations. Include exact files to create/update, exact gates to run, exact commands if detectable, and exact acceptance criteria.
+
+## Scripts
+
+- `scripts/detect_project_profile.py`: inspect a repository and emit a Markdown project profile.
+- `scripts/generate_change_scaffold.py`: create a change folder from templates.
+- `scripts/validate_contracts.py`: check for required contract files.
+- `scripts/validate_env_contract.py`: check env contract basics.
+- `scripts/validate_ci_gates.py`: check `ci-gates.md` structure.
+- `scripts/validate_spec_traceability.py`: check coarse traceability between spec, tasks, tests, and CI gates.
+
+Run scripts with Python 3 from the repository root.

package/assets/skill/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "Contract Driven Delivery"

package/assets/skill/references/api-contract-standard.md

@@ -0,0 +1,55 @@
+# API Contract Standard
+
+## Required API style decision
+
+Every repository must define its API response style. Acceptable styles include:
+
+- envelope response, for example `{ success, data, error, meta }`
+- direct resource response with standardized error envelope
+- framework-native response with documented exception mapping
+
+The style may vary by repo, but it must be explicit.
+
+## Required for every endpoint
+
+- method and path
+- auth and permission requirement
+- request params/body schema
+- response schema
+- error response format
+- status codes
+- pagination/sorting/filtering behavior
+- date/time format and timezone
+- null and empty behavior
+- compatibility notes
+- frontend client/type impact
+- test coverage
+
+## Endpoint inventory
+
+Repos should maintain an endpoint inventory. Any endpoint added, removed, renamed, moved, or exempted must update the inventory in the same change.
+
+## Breaking changes
+
+Breaking changes include:
+
+- field removal or rename
+- type change
+- enum value change
+- status code behavior change
+- pagination behavior change
+- error format change
+- auth/permission change
+- timing semantics change that clients depend on
+
+Every breaking change requires migration/compatibility plan and explicit QA sign-off.
+
+## API tests
+
+Minimum API change coverage:
+
+- contract test for response/error format
+- validation test for invalid input
+- compatibility test for existing clients when relevant
+- malicious/fuzz payload test for user-controlled inputs
+- smoke/E2E path if user-visible

package/assets/skill/references/business-logic-standard.md

@@ -0,0 +1,32 @@
+# Business Logic Standard
+
+Business logic changes must be explicit, example-driven, and regression-tested.
+
+## Required sections
+
+- current rule
+- problem with current rule
+- new rule
+- decision table
+- examples
+- edge cases
+- backward compatibility
+- data migration impact
+- audit/logging impact
+- permission impact
+- reporting/export impact
+- regression tests
+
+## Decision table template
+
+| condition | old behavior | new behavior | expected output | test id |
+|---|---|---|---|---|
+
+## Example matrix template
+
+| input | old output | new output | reason |
+|---|---|---|---|
+
+## Guardrail
+
+If a developer cannot describe the rule in a decision table, implementation is premature.

package/assets/skill/references/ci-cd-policy.md

@@ -0,0 +1,34 @@
+# CI/CD Policy
+
+CI/CD is a required delivery artifact.
+
+## Gate tiers
+
+| tier | name | purpose | default merge behavior |
+|---:|---|---|---|
+| 0 | local fast gate | quick feedback before commit/PR | local only |
+| 1 | PR required gate | block unsafe merges | required |
+| 2 | PR informational gate | collect signal before promotion | non-blocking |
+| 3 | nightly real-infra gate | detect real infrastructure failures | non-blocking unless stable |
+| 4 | weekly soak/stress gate | detect long-run/load issues | scheduled/manual |
+| 5 | manual production-like gate | high-risk release confidence | manual approval |
+
+## Required for every change
+
+`ci-gates.md` must state:
+
+- which gates apply
+- which are required
+- which are informational
+- workflow or command name
+- expected artifact/log location
+- promotion criteria for new gates
+- rollback path if gate fails after merge
+
+## Promotion policy
+
+New expensive or flaky gates should start as informational. Promote to required only after a stability window, for example 20 days or 60 runs with acceptable pass rate and known failure triage.
+
+## CI truthfulness rule
+
+CI green only proves the exact configured gates passed. Do not claim coverage that the pipeline did not execute.

package/assets/skill/references/css-contract-standard.md

@@ -0,0 +1,40 @@
+# CSS/UI Contract Standard
+
+## Principles
+
+- Tokens are the source of visual truth.
+- Shared components define allowed variants and states.
+- One-off visual hacks must be justified or avoided.
+- UI changes require visual evidence.
+
+## Required definitions
+
+- token source of truth
+- component variants
+- component sizes
+- component states: default, hover, focus, active, disabled, loading, error, empty
+- responsive behavior
+- accessibility requirements
+- allowed overrides
+- forbidden overrides
+
+## Forbidden by default
+
+- hard-coded colors when token system exists
+- arbitrary spacing when scale exists
+- global style leakage
+- overriding shared component internals from feature CSS
+- unreviewed z-index additions
+- UI states without loading/error/empty handling
+- browser dialogs when design system dialog/toast exists
+
+## Visual review requirements
+
+For UI output changes, check:
+
+- desktop, tablet, mobile viewports
+- long text and empty data
+- loading and error states
+- keyboard focus and tab order
+- modal/dropdown/tooltip overflow
+- visual diff or screenshot evidence

package/assets/skill/references/data-contract-standard.md

@@ -0,0 +1,43 @@
+# Data Shape Contract Standard
+
+Use this standard for reports, dashboards, exports, imports, tables, charts, and any feature that transforms tabular or semi-structured data.
+
+## Required definitions
+
+- required columns
+- optional columns
+- column types
+- nullability
+- allowed values
+- timezone and date format
+- numeric precision and rounding
+- row limits
+- pagination or truncation behavior
+- empty dataset behavior
+- malformed data behavior
+- export format and encoding
+- backward compatibility rules
+
+## Invalid data behavior
+
+| condition | required decision |
+|---|---|
+| missing required column | reject or default with warning |
+| wrong type | reject, coerce, or mark invalid |
+| duplicate key | deterministic merge or explicit error |
+| empty dataset | safe empty state, not 500 |
+| over row limit | truncate with metadata or reject |
+| unexpected enum | display fallback or reject |
+| malformed date | validation error with user-friendly message |
+
+## Required tests
+
+- valid representative dataset
+- empty dataset
+- large dataset
+- missing column
+- wrong type
+- null values
+- unexpected enum
+- malicious strings
+- export boundary if export exists

package/assets/skill/references/e2e-standard.md

@@ -0,0 +1,33 @@
+# E2E and Resilience Standard
+
+E2E tests prove user-visible workflows. Resilience tests prove safe behavior under failure.
+
+## Critical journey E2E
+
+Cover at least:
+
+- page load
+- primary task completion
+- validation errors
+- empty data
+- reload and URL state restoration
+- browser back/forward
+- permission or session error when applicable
+
+## Resilience coverage
+
+Cover as applicable:
+
+- API 500/503
+- timeout
+- aborted request
+- slow network
+- stale cache/snapshot
+- Redis/cache disabled
+- worker/job pending/running/failed
+- double submit prevention
+- repeated filter changes
+
+## Evidence
+
+E2E changes should record commands, test files, screenshots/videos/traces when available, and CI gate placement.

package/assets/skill/references/env-contract-standard.md

@@ -0,0 +1,30 @@
+# Env Contract Standard
+
+## Required fields for every env var
+
+| field | description |
+|---|---|
+| name | exact variable name |
+| scope | frontend, backend, build, runtime, test, deploy |
+| environments | local, dev, staging, production, CI |
+| required | yes/no |
+| secret | yes/no |
+| default | safe default or none |
+| example | non-secret example |
+| owner | responsible area |
+| validation | type/range/allowed values |
+| restart required | yes/no |
+| failure behavior | what happens if missing/invalid |
+
+## Public frontend env rule
+
+Variables with prefixes such as `VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`, or similar are browser-exposed and must never contain secrets.
+
+## Required updates for env changes
+
+- env contract
+- `.env.example`
+- runtime validation/config loader
+- deployment docs or workflow secrets
+- tests for missing/invalid values when high-risk
+- rollback/default behavior

package/assets/skill/references/monkey-operation-standard.md

@@ -0,0 +1,32 @@
+# Monkey Operation Standard
+
+Monkey testing must be structured, not random noise. The goal is to prevent and detect real production misuse.
+
+## Preventive spec checklist
+
+Every user-facing feature should define behavior for:
+
+- double click / repeated submit
+- rapid filter changes
+- invalid date range
+- missing required field
+- very long input
+- Unicode and special characters
+- SQL-like/script-like strings
+- hidden tab / visibility change
+- browser back/forward
+- stale session
+- wrong data shape
+- network abort
+
+## Test approaches
+
+- Playwright action sequences
+- route fuzz payloads
+- property-based tests
+- malformed fixture datasets
+- randomized but bounded user operations
+
+## Assertion rule
+
+A monkey test must assert a safe outcome: validation message, disabled action, stable URL state, retained last snapshot, no duplicate job, no 500, or recoverable error state.

package/assets/skill/references/qa-gates.md

@@ -0,0 +1,37 @@
+# QA Gates
+
+## Gate families
+
+- lint
+- typecheck
+- build
+- unit
+- contract
+- integration
+- E2E
+- visual
+- data-boundary
+- resilience
+- monkey/fuzz
+- stress
+- soak
+- security where applicable
+- deployment smoke
+
+## QA rule
+
+QA approval requires evidence. Evidence may be command output, CI links, logs, screenshots, videos, traces, metrics, or artifact files.
+
+## Fixback rule
+
+Failures must be routed to the correct owner:
+
+- contract mismatch -> contract reviewer + implementing engineer
+- backend/API failure -> backend engineer
+- frontend/UI failure -> frontend engineer
+- visual failure -> visual reviewer + frontend engineer
+- UX failure -> UI/UX reviewer + frontend engineer
+- CI/CD failure -> CI/CD gatekeeper
+- stress/soak failure -> stress-soak engineer
+- monkey/data-boundary failure -> monkey or E2E/resilience engineer
+- unclear systemic issue -> spec architect

package/assets/skill/references/sdd-tdd-policy.md

@@ -0,0 +1,53 @@
+# SDD + TDD Policy
+
+## SDD policy
+
+Specifications are the source of intent. Code serves the specification, not the other way around.
+
+A good spec must include:
+
+- user/business intent
+- in-scope and out-of-scope boundaries
+- acceptance criteria
+- edge cases
+- non-functional requirements
+- compatibility constraints
+- observable success signals
+
+For existing systems, never write a future spec without documenting current behavior when the change modifies existing behavior.
+
+## TDD policy
+
+Tests define expected behavior before or alongside implementation.
+
+Preferred order:
+
+1. write or update spec
+2. write or update contracts
+3. write test plan
+4. write failing tests when feasible
+5. implement minimal production code
+6. run local gate
+7. run CI/CD gate
+8. archive learning
+
+## Test-first exceptions
+
+Test-first can be softened for exploratory spikes, but spikes must not be merged as production work until tests, contracts, and CI gates exist.
+
+## Production-reality TDD
+
+For dashboards, reports, long-running jobs, auto-refresh, and data-heavy views, TDD includes:
+
+- malformed input
+- wrong columns and wrong types
+- empty data
+- large data
+- partial data
+- slow network
+- aborted requests
+- double submit
+- repeated clicks
+- back/forward navigation
+- cache stale/miss behavior
+- long-run memory and pool stability

package/assets/skill/references/spec-drift-policy.md

@@ -0,0 +1,28 @@
+# Spec Drift Policy
+
+Spec drift happens when requirements, contracts, tests, CI gates, and code evolve at different speeds.
+
+## Audit triggers
+
+Run a drift audit when:
+
+- a feature had multiple iterations
+- production behavior differs from archived spec
+- tests were added after implementation
+- CI gates were changed
+- a bug fix updates behavior but not spec
+- a contract changed without client/test update
+- tasks are marked complete but evidence is unclear
+
+## Audit checks
+
+- spec acceptance criteria map to tests
+- contracts map to implementation and tests
+- CI gates run relevant tests
+- tasks marked complete have code/test evidence
+- archive promotes durable learnings
+- deprecated behavior is removed or documented
+
+## Output
+
+Use `templates/regression-report.md` or create `spec-drift-audit.md` when the audit is standalone.

package/assets/skill/references/stress-soak-standard.md

@@ -0,0 +1,42 @@
+# Stress and Soak Standard
+
+Use stress and soak tests for high-load, long-running, cache-heavy, queue-heavy, report, dashboard, export, import, and auto-refresh behavior.
+
+## Stress test
+
+Stress tests answer: what happens under high concurrency or high data volume?
+
+Define:
+
+- concurrent users or requests
+- request mix
+- data size
+- ramp-up and duration
+- success criteria
+- error budget
+- system metrics
+
+## Soak test
+
+Soak tests answer: what happens after sustained operation?
+
+Define:
+
+- duration
+- refresh interval
+- cache TTL expectations
+- DB/worker/cache pool stability
+- RSS/memory trend
+- queue backlog trend
+- temp file growth
+- circuit breaker transitions
+- artifacts retained
+
+## Required outputs
+
+- workload model
+- thresholds
+- commands/workflows
+- raw logs or metrics
+- pass/fail conclusion
+- follow-up issues for degraded but non-blocking findings

package/assets/skill/references/visual-review-standard.md

@@ -0,0 +1,27 @@
+# Visual Review Standard
+
+Visual review is required when frontend output changes.
+
+## Required dimensions
+
+- affected pages/screens
+- changed components
+- desktop, tablet, and mobile viewports
+- default, loading, empty, error, disabled, focus, hover, long text, no permission states
+- modal, drawer, dropdown, tooltip overflow behavior
+- table overflow and column width behavior
+- dark mode or theme behavior when applicable
+- accessibility: focus, keyboard, labels, contrast
+
+## Evidence levels
+
+| level | evidence |
+|---|---|
+| basic | manual checklist with viewports and states |
+| standard | screenshots before/after or after-only for new UI |
+| strong | visual regression diff with accepted changes |
+| high-risk | video/trace plus visual diff and UX review |
+
+## Review output
+
+Use `templates/visual-review-report.md`.

package/assets/skill/references/workflow-router.md

@@ -0,0 +1,34 @@
+# Workflow Router
+
+## Change classification
+
+Classify every request before implementation. A request may have more than one type.
+
+| Change type | Required path |
+|---|---|
+| new-feature | proposal, spec, design, contracts, test-plan, ci-gates, tasks |
+| feature-enhancement | current-behavior, diff spec, regression scope, contracts, test-plan, ci-gates |
+| business-logic-change | current rule, new rule, decision table, examples, edge cases, regression tests |
+| bug-fix | reproduction, root cause, failing test, fix, regression test, QA evidence |
+| regression-fix | broken prior behavior, regression source, failing test, rollback or forward fix |
+| ui-only-change | CSS/UI contract, UI/UX review, visual review, E2E/interaction coverage |
+| api-only-change | API contract, endpoint inventory, client/type impact, contract tests |
+| env-change | env contract, `.env.example`, deployment impact, secret/public scope review |
+| data-contract-change | column/type/nullability contract, malformed data behavior, data-boundary tests |
+| performance-change | baseline, target, load profile, stress/soak plan, telemetry thresholds |
+| refactor | no behavior change proof, regression tests, architecture note |
+| ci-cd-change | pipeline contract, required check impact, rollback policy |
+| test-hardening-change | target risk, new test signal, mutation check, CI gate placement |
+
+## Artifact rule
+
+Do not create heavyweight artifacts when a tiny change does not need them. However, any implementation change must record:
+
+- what kind of change it is
+- which contracts are affected
+- which tests prove it
+- which CI/CD gates must run
+
+## Iteration rule
+
+Update an existing change when intent is the same and scope overlap remains high. Start a new change when intent changes, scope explodes, or the original work can be completed independently.