contract-driven-delivery 1.0.0

package/assets/skill/scripts/detect_project_profile.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Detect a repository profile and print Markdown."""
+from pathlib import Path
+import argparse
+
+FRONTEND_MARKERS = ['package.json', 'vite.config.js', 'vite.config.ts', 'next.config.js', 'tailwind.config.js', 'tailwind.config.ts']
+BACKEND_MARKERS = ['pyproject.toml', 'requirements.txt', 'app.py', 'main.py', 'manage.py', 'pom.xml', 'build.gradle']
+CI_MARKERS = ['.github/workflows', '.gitlab-ci.yml', 'bitbucket-pipelines.yml', '.circleci']
+CONTRACT_DIRS = ['contracts', 'contract']
+
+def exists(root: Path, rel: str) -> bool:
+    return (root / rel).exists()
+
+def list_existing(root: Path, rels):
+    return [r for r in rels if exists(root, r)]
+
+def detect_commands(root: Path):
+    commands = {}
+    pkg = root / 'package.json'
+    if pkg.exists():
+        text = pkg.read_text(encoding='utf-8', errors='ignore')
+        for script in ['dev','build','test','lint','typecheck','e2e']:
+            if f'"{script}"' in text:
+                commands[script] = f'npm run {script}'
+    if (root / 'pyproject.toml').exists() or (root / 'pytest.ini').exists() or (root / 'tests').exists():
+        commands.setdefault('unit', 'pytest')
+    return commands
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('root', nargs='?', default='.')
+    ap.add_argument('--write', help='optional output markdown path')
+    args = ap.parse_args()
+    root = Path(args.root).resolve()
+    frontend = list_existing(root, FRONTEND_MARKERS)
+    backend = list_existing(root, BACKEND_MARKERS)
+    ci = list_existing(root, CI_MARKERS)
+    contracts = [d for d in CONTRACT_DIRS if (root/d).exists()]
+    tests = [p for p in ['tests','frontend/tests','e2e','playwright.config.ts','playwright.config.js'] if (root/p).exists()]
+    commands = detect_commands(root)
+    lines = ['# Project Profile', '', f'## Root', str(root), '', '## Detected Markers']
+    lines += ['- frontend: ' + (', '.join(frontend) if frontend else 'none detected')]
+    lines += ['- backend: ' + (', '.join(backend) if backend else 'none detected')]
+    lines += ['- contracts: ' + (', '.join(contracts) if contracts else 'none detected')]
+    lines += ['- tests: ' + (', '.join(tests) if tests else 'none detected')]
+    lines += ['- ci/cd: ' + (', '.join(ci) if ci else 'none detected')]
+    lines += ['', '## Suggested Commands']
+    if commands:
+        lines += [f'- {k}: `{v}`' for k,v in sorted(commands.items())]
+    else:
+        lines += ['- none detected; inspect README/CI manually']
+    lines += ['', '## Missing Standard Surfaces']
+    if not contracts: lines.append('- contracts directory not detected')
+    if not ci: lines.append('- CI/CD workflow not detected')
+    if not tests: lines.append('- tests not detected')
+    out='\n'.join(lines)+'\n'
+    if args.write:
+        Path(args.write).write_text(out, encoding='utf-8')
+    print(out)
+if __name__ == '__main__':
+    main()

package/assets/skill/scripts/generate_change_scaffold.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Generate a specs/changes/<change-id> scaffold from bundled templates."""
+from pathlib import Path
+import argparse
+import shutil
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('change_id')
+    ap.add_argument('--root', default='.')
+    ap.add_argument('--templates', default=None)
+    args=ap.parse_args()
+    root=Path(args.root).resolve()
+    templates=Path(args.templates).resolve() if args.templates else Path(__file__).resolve().parents[1]/'templates'
+    dest=root/'specs'/'changes'/args.change_id
+    dest.mkdir(parents=True, exist_ok=False)
+    mapping={
+        'change-request.md':'request.md',
+        'change-classification.md':'classification.md',
+        'current-behavior.md':'current-behavior.md',
+        'proposal.md':'proposal.md',
+        'spec.md':'spec.md',
+        'design.md':'design.md',
+        'contracts.md':'contracts.md',
+        'test-plan.md':'test-plan.md',
+        'ci-gates.md':'ci-gates.md',
+        'tasks.md':'tasks.md',
+        'qa-report.md':'qa-report.md',
+        'regression-report.md':'regression-report.md',
+        'archive.md':'archive.md',
+    }
+    for src,dst in mapping.items():
+        s=templates/src
+        if s.exists():
+            shutil.copyfile(s, dest/dst)
+    print(f'created {dest}')
+if __name__ == '__main__':
+    main()

package/assets/skill/scripts/validate_ci_gates.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Basic ci-gates.md validation."""
+from pathlib import Path
+import argparse, sys
+REQUIRED_TERMS=['required gates','tier','trigger','workflow','promotion policy','rollback policy']
+def main():
+    ap=argparse.ArgumentParser(); ap.add_argument('path')
+    args=ap.parse_args(); p=Path(args.path)
+    if not p.exists(): print(f'{p} not found'); sys.exit(1)
+    text=p.read_text(encoding='utf-8', errors='ignore').lower()
+    missing=[t for t in REQUIRED_TERMS if t not in text]
+    if missing: print('ci-gates missing terms: '+', '.join(missing)); sys.exit(1)
+    print('CI gates basic validation passed.')
+if __name__=='__main__': main()

package/assets/skill/scripts/validate_contracts.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+"""Check for required contract surfaces."""
+from pathlib import Path
+import argparse, sys
+REQUIRED=['contracts/api/api-contract.md','contracts/css/css-contract.md','contracts/env/env-contract.md','contracts/data/data-shape-contract.md','contracts/business/business-rules.md','contracts/ci/ci-gate-contract.md']
+def main():
+    ap=argparse.ArgumentParser(); ap.add_argument('root', nargs='?', default='.')
+    args=ap.parse_args(); root=Path(args.root)
+    missing=[p for p in REQUIRED if not (root/p).exists()]
+    if missing:
+        print('Missing contract files:'); [print(f'- {p}') for p in missing]; sys.exit(1)
+    print('All required contract files are present.')
+if __name__=='__main__': main()

package/assets/skill/scripts/validate_env_contract.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Basic env contract validation."""
+from pathlib import Path
+import argparse, sys
+REQUIRED_COLUMNS=['name','scope','required','secret','default','example','validation']
+def main():
+    ap=argparse.ArgumentParser(); ap.add_argument('path', nargs='?', default='contracts/env/env-contract.md')
+    args=ap.parse_args(); p=Path(args.path)
+    if not p.exists(): print(f'{p} not found'); sys.exit(1)
+    text=p.read_text(encoding='utf-8', errors='ignore').lower()
+    missing=[c for c in REQUIRED_COLUMNS if c not in text]
+    if missing: print('Env contract missing columns/terms: '+', '.join(missing)); sys.exit(1)
+    if 'vite_' not in text and 'next_public_' not in text and 'public_' not in text:
+        print('Warning: public frontend env policy not found.')
+    print('Env contract basic validation passed.')
+if __name__=='__main__': main()

package/assets/skill/scripts/validate_spec_traceability.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""Coarse traceability check for a change folder."""
+from pathlib import Path
+import argparse, sys
+REQUIRED=['classification.md','test-plan.md','ci-gates.md','tasks.md']
+def main():
+    ap=argparse.ArgumentParser(); ap.add_argument('change_dir')
+    args=ap.parse_args(); d=Path(args.change_dir)
+    if not d.exists(): print(f'{d} not found'); sys.exit(1)
+    missing=[f for f in REQUIRED if not (d/f).exists()]
+    if missing: print('Missing required change artifacts: '+', '.join(missing)); sys.exit(1)
+    text='\n'.join((d/f).read_text(encoding='utf-8', errors='ignore') for f in REQUIRED)
+    warnings=[]
+    for term in ['contract','test','ci','gate']:
+        if term not in text.lower(): warnings.append(term)
+    if warnings: print('Warning: weak traceability terms: '+', '.join(warnings))
+    print('Change traceability basic validation passed.')
+if __name__=='__main__': main()

package/assets/skill/templates/archive.md

@@ -0,0 +1,17 @@
+# Archive
+
+## Change Summary
+
+## Final Behavior
+
+## Final Contracts Updated
+
+## Final Tests Added / Updated
+
+## Final CI/CD Gates
+
+## Production Reality Findings
+
+## Lessons Promoted to Standards
+
+## Follow-up Work

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

@@ -0,0 +1,48 @@
+# Change Classification
+
+## Change Types
+- primary:
+- secondary:
+
+## Risk Level
+- low / medium / high / critical
+
+## Impact Radius
+- 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 |  |  |
+
+## Required Contracts
+- API:
+- CSS/UI:
+- Env:
+- Data shape:
+- Business logic:
+- CI/CD:
+
+## Required Test Families
+- unit:
+- contract:
+- integration:
+- E2E:
+- visual:
+- data-boundary:
+- resilience:
+- fuzz/monkey:
+- stress:
+- soak:
+
+## Required Agents
+
+## Assumptions / Clarifications

package/assets/skill/templates/change-request.md

@@ -0,0 +1,15 @@
+# Change Request
+
+## Original Request
+
+## Business / User Goal
+
+## Non-goals
+
+## Constraints
+
+## Known Context
+
+## Open Questions
+
+## Requested Delivery Date / Priority

package/assets/skill/templates/ci-gates.md

@@ -0,0 +1,31 @@
+# CI/CD Gate Plan
+
+## Change ID
+
+## Required Gates
+| gate | tier | required | trigger | command/workflow | expected artifact |
+|---|---:|---:|---|---|---|
+| lint | 1 | yes | pull_request |  |  |
+| build | 1 | yes | pull_request |  |  |
+| unit | 1 | yes | pull_request |  |  |
+| contract | 1 | conditional | pull_request |  |  |
+| integration | 1/3 | conditional | pull_request/nightly |  |  |
+| e2e-critical | 1 | conditional | pull_request |  |  |
+| visual | 2 | conditional | pull_request |  |  |
+| data-boundary | 1 | conditional | pull_request |  |  |
+| resilience | 1/3 | conditional | pull_request/nightly |  |  |
+| fuzz/monkey | 1/3 | conditional | pull_request/nightly |  |  |
+| stress | 4/5 | conditional | weekly/manual |  |  |
+| soak | 4/5 | conditional | weekly/manual |  |  |
+
+## New Workflow Changes
+
+## Required Check Policy
+
+## Informational Gate Promotion Policy
+
+## Rollback Policy
+
+## Artifact Retention
+
+## Merge Eligibility Decision

package/assets/skill/templates/contracts.md

@@ -0,0 +1,37 @@
+# Contract Change Report
+
+## API Contract
+- changed:
+- files:
+- compatibility:
+- tests:
+
+## CSS/UI Contract
+- changed:
+- files:
+- visual evidence required:
+- tests:
+
+## Env Contract
+- changed:
+- variables:
+- public/private scope:
+- deployment impact:
+- tests:
+
+## Data Shape Contract
+- changed:
+- required columns/types:
+- malformed data behavior:
+- tests:
+
+## Business Logic Contract
+- changed:
+- decision table:
+- regression tests:
+
+## CI/CD Contract
+- changed:
+- gates:
+- required checks:
+- promotion policy:

package/assets/skill/templates/current-behavior.md

@@ -0,0 +1,17 @@
+# Current Behavior
+
+## Current User Flow
+
+## Current API / Data Flow
+
+## Current Business Rules
+
+## Current UI States
+
+## Current Tests
+
+## Known Issues
+
+## Compatibility Constraints
+
+## Regression Scope

package/assets/skill/templates/design.md

@@ -0,0 +1,23 @@
+# Technical Design
+
+## Architecture Summary
+
+## Affected Components
+
+## API Design
+
+## Data / Schema Design
+
+## UI / UX Design
+
+## Env / Config Design
+
+## Error Handling
+
+## Performance Considerations
+
+## Security Considerations
+
+## Deployment / Rollback
+
+## Architecture Decision Notes

package/assets/skill/templates/monkey-test-report.md

@@ -0,0 +1,17 @@
+# Monkey Operation Test Report
+
+## Target Feature
+
+## Preventive Spec Cases
+
+## Exploratory Operation Sequences
+| id | sequence | expected safe outcome | result |
+|---|---|---|---|
+
+## Fuzz Payloads / Malformed Data
+
+## Findings
+
+## Required Fixes
+
+## Regression Tests Added

package/assets/skill/templates/project-profile.md

@@ -0,0 +1,38 @@
+# Project Profile
+
+## Project Type
+
+## 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 Steps

package/assets/skill/templates/proposal.md

@@ -0,0 +1,17 @@
+# Proposal
+
+## Intent
+
+## Scope
+
+## Out of Scope
+
+## Proposed Approach
+
+## Alternatives Considered
+
+## Compatibility / Migration
+
+## Rollback Plan
+
+## Success Criteria

package/assets/skill/templates/qa-report.md

@@ -0,0 +1,26 @@
+# QA Report
+
+## Summary
+
+## Gate Results
+| gate | command/workflow | result | artifact/log |
+|---|---|---|---|
+
+## Functional Verification
+
+## Contract Verification
+
+## Visual / UX Verification
+
+## E2E / Resilience Verification
+
+## Stress / Soak Verification
+
+## Known Risks
+
+## Failures and Fixback Routing
+| failure | evidence | owner | required fix |
+|---|---|---|---|
+
+## Decision
+approved / blocked / approved-with-risk

package/assets/skill/templates/regression-report.md

@@ -0,0 +1,21 @@
+# Regression Report
+
+## Changed Areas
+
+## Directly Affected Features
+
+## Indirectly Affected Features
+
+## Critical User Journeys Re-tested
+
+## API Regression
+
+## UI Regression
+
+## Data / Business Logic Regression
+
+## CI/CD Regression
+
+## Spec Drift Findings
+
+## Decision

package/assets/skill/templates/spec.md

@@ -0,0 +1,23 @@
+# Specification
+
+## User Stories / Scenarios
+
+### Scenario 1
+Given
+When
+Then
+
+## Functional Requirements
+
+## Non-functional Requirements
+
+## Edge Cases
+
+## Acceptance Criteria
+
+| id | criterion | measurable signal |
+|---|---|---|
+
+## Clarifications
+
+## Open Risks

package/assets/skill/templates/stress-soak-report.md

@@ -0,0 +1,22 @@
+# Stress / Soak Report
+
+## Workload Model
+
+## Environment
+
+## Duration
+
+## Metrics Collected
+
+## Thresholds
+
+## Results
+| metric | threshold | observed | result |
+|---|---|---|---|
+
+## Failures / Degradation
+
+## Artifacts
+
+## Recommendation
+pass / fail / repeat-with-adjusted-load / promote-to-gate

package/assets/skill/templates/tasks.md

@@ -0,0 +1,43 @@
+# Tasks
+
+## 1. Preparation
+- [ ] 1.1 Confirm classification and required artifacts
+- [ ] 1.2 Confirm contracts to update
+- [ ] 1.3 Confirm CI/CD gate plan
+
+## 2. Contract Updates
+- [ ] 2.1 API contract
+- [ ] 2.2 CSS/UI contract
+- [ ] 2.3 Env contract
+- [ ] 2.4 Data shape contract
+- [ ] 2.5 Business logic contract
+- [ ] 2.6 CI/CD contract
+
+## 3. Tests First
+- [ ] 3.1 Unit/contract tests
+- [ ] 3.2 Integration tests
+- [ ] 3.3 E2E/resilience tests
+- [ ] 3.4 Data-boundary/monkey tests
+- [ ] 3.5 Stress/soak tests if required
+
+## 4. Implementation
+- [ ] 4.1 Backend
+- [ ] 4.2 Frontend
+- [ ] 4.3 Env/deploy
+- [ ] 4.4 CI/CD workflows
+
+## 5. Review
+- [ ] 5.1 UI/UX review
+- [ ] 5.2 Visual review
+- [ ] 5.3 Contract review
+- [ ] 5.4 QA review
+
+## 6. Verification
+- [ ] 6.1 Local gates
+- [ ] 6.2 PR required gates
+- [ ] 6.3 Informational gates
+- [ ] 6.4 Nightly/weekly/manual gates if required
+
+## 7. Archive
+- [ ] 7.1 Archive change
+- [ ] 7.2 Promote durable learnings to contracts or CLAUDE.md

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

@@ -0,0 +1,31 @@
+# Test Plan
+
+## Acceptance Criteria Mapping
+| requirement | test family | planned file/spec | expected evidence |
+|---|---|---|---|
+
+## Unit Tests
+
+## Contract Tests
+
+## Integration Tests
+
+## E2E Tests
+
+## Visual Tests / Review
+
+## Data Boundary Tests
+
+## Resilience Tests
+
+## Fuzz / Monkey Operation Tests
+
+## Stress Tests
+
+## Soak Tests
+
+## Mutation Checks
+
+## Commands
+
+## CI/CD Gate Mapping

package/assets/skill/templates/visual-review-report.md

@@ -0,0 +1,33 @@
+# Visual Review Report
+
+## Affected Screens
+
+## Viewports Checked
+- desktop:
+- tablet:
+- mobile:
+
+## States Checked
+- default:
+- loading:
+- empty:
+- error:
+- disabled:
+- focus/keyboard:
+- long text:
+- no permission:
+
+## Evidence
+- screenshots:
+- videos:
+- traces:
+- diff reports:
+
+## CSS Contract Findings
+
+## Accessibility Findings
+
+## Required Fixes
+
+## Decision
+approved / changes-required

package/assets/specs-templates/archive.md

@@ -0,0 +1,17 @@
+# Archive
+
+## Change Summary
+
+## Final Behavior
+
+## Final Contracts Updated
+
+## Final Tests Added / Updated
+
+## Final CI/CD Gates
+
+## Production Reality Findings
+
+## Lessons Promoted to Standards
+
+## Follow-up Work