Charter-Driven Quality Gates
Who is this for (1)
- Stakeholder Persona: External Tech Lead Evaluator — Written for the External Tech Lead Evaluator reader.
Enforce consistent standards across all features using a project charter.
What is a Charter?
A project charter defines non-negotiable principles that guide all development:
- Code quality standards
- Testing requirements
- Security practices
- Performance expectations
- Documentation rules
Location: .kittify/charter/charter.md
Scope: Applies to ALL features in the project, enforced automatically by Spec Kitty commands
Setup Charter
1. Create Charter (One-time per project)
/spec-kitty.charter
Create principles for:
**Code Quality:**- All functions must have type hints (Python) or TypeScript types- Maximum function length: 50 lines- Cyclomatic complexity < 10- No commented-out code in production
**Testing:**- Minimum 80% unit test coverage required- Integration tests for all API endpoints- Test-first development (TDD) mandatory
**Security:**- All user inputs must be validated and sanitized- No secrets in code (environment variables only)- SQL injection prevention via parameterized queries- XSS protection on all rendered output
**Performance:**- API endpoints must respond within 200ms (p95)- Database queries optimized (no N+1)- Images compressed and lazy-loaded- Bundle size < 250KB for frontend
**Documentation:**- Every public function requires JSDoc/docstring- README updated for new features- API changes documented in CHANGELOG- Architectural decisions recorded in ADRsResult: Creates .kittify/charter/charter.md that all subsequent commands reference
2. View Charter
cat .kittify/charter/charter.mdHow Charter Enforces Quality
During Specification (/spec-kitty.specify)
Charter influences what goes into spec.md:
Without Charter:
## User StoryAs a user, I want to upload photosWith Charter (Security + Performance principles):
## User StoryAs a user, I want to upload photos
## Acceptance Criteria- Images validated (JPEG/PNG only, max 10MB)- Uploaded files scanned for malware- Images auto-compressed to <1MB- Lazy loading implemented for gallery view- Upload API responds within 200msDuring Planning (/spec-kitty.plan)
Charter shapes technical decisions:
Charter Says: “80% test coverage required”
Plan Includes:
## Testing Strategy- Unit tests for: image validation, compression, upload handler- Integration tests for: full upload flow, storage integration- Coverage measured via pytest-cov- CI pipeline blocks merge if coverage < 80%Charter Says: “No secrets in code”
Plan Includes:
## Configuration Management- AWS credentials from environment variables- S3 bucket name in .env file- API keys loaded via AWS Secrets Manager- .env.example template for developersDuring Task Generation (/spec-kitty.tasks)
Charter auto-generates quality tasks:
Charter enforces test coverage:
## Work Packages
### WP01: Implement Image Upload API#### Subtasks- [ ] T001: Create upload endpoint handler- [ ] T002: Write unit tests for handler (TDD)- [ ] T003: Add integration test for full flow- [ ] T004: Measure coverage, ensure >80%- [ ] T005: Configure CI coverage gate
### WP02: Add Input Validation#### Subtasks- [ ] T006: Validate file type (JPEG/PNG only)- [ ] T007: Validate file size (<10MB)- [ ] T008: Sanitize filename for storage- [ ] T009: Unit test all validation cases- [ ] T010: Add malware scanning integrationNotice: Testing and security tasks automatically included!
During Implementation (/spec-kitty.implement)
Charter reminds agents of standards:
Agent prompt includes:
IMPORTANT: Project charter requires:- 80% test coverage - write tests FIRST (TDD)- Input validation - check file type and size- No secrets in code - use environment variables- Performance target - API must respond <200ms
Before moving to review, verify:- [ ] Tests written and passing- [ ] Coverage measured and >80%- [ ] No hardcoded credentials- [ ] Performance benchmarkedDuring Review (/spec-kitty.review)
Charter provides review checklist:
Reviewing WP01: Image Upload API
Charter Compliance Checklist:- [ ] Test coverage measured? (Requirement: >80%)- [ ] Input validation present?- [ ] No secrets in code?- [ ] Performance benchmarked? (Target: <200ms)- [ ] Public functions documented?- [ ] Type hints/TypeScript types added?Agent must verify each before approving work.
During Acceptance (/spec-kitty.accept)
Charter enforces final gates:
/spec-kitty.acceptValidation checks:
✓ All work packages in done/✓ Charter compliance: ✓ Running coverage report... Result: 84% (Required: >80%) PASS ✓ Checking for secrets in code... Result: No secrets detected PASS ✓ Performance benchmarks recorded... Result: Average 156ms (Target: <200ms) PASS ✓ Documentation coverage... Result: All public functions documented PASS
Feature ready for merge!If violations found:
✗ Charter violations detected:
Coverage: 72% (Required: >80%)- Missing tests in upload_handler.py lines 45-67- Add unit tests before accepting
Secrets detected:- AWS_SECRET_KEY hardcoded in config.py line 12- Move to environment variable
Blocking acceptance until resolved.Example: Test Coverage Principle
Charter Definition
## Article III: Test-Driven Development
### Minimum CoverageAll production code MUST achieve minimum 80% test coverage.
### Coverage Measurement- Unit tests: pytest with pytest-cov- Coverage report: Generated on every CI run- Enforcement: Pre-merge hook blocks <80%
### Test-First RequirementTests MUST be written before implementation code:1. Write failing test2. Implement minimum code to pass3. Refactor while keeping tests green4. Measure coverage5. Add tests until >80%Workflow with This Principle
Step 1: Tasks generated include testing
### WP03: Add User Authentication- [ ] T015: Write unit test for login endpoint (FAIL)- [ ] T016: Implement login endpoint (PASS)- [ ] T017: Write test for token generation (FAIL)- [ ] T018: Implement token generation (PASS)- [ ] T019: Measure coverage- [ ] T020: Add missing test cases to reach 80%Step 2: Implementation follows TDD
# T015: Write failing test FIRSTdef test_login_success(): assert response.status_code == 200 assert "token" in response.json()
# T016: Then implement@app.post("/login")def login(credentials: Credentials): # Implementation here return {"token": generate_token(credentials)}Step 3: Coverage measured
pytest --cov=app --cov-report=term-missing# Result: 84% coverage - PASSStep 4: Accept command validates
/spec-kitty.accept✓ Coverage report found: 84% (Required: >80%) PASSExample: Security Validation Principle
Charter Definition
## Article V: Security Standards
### Input ValidationALL user-provided input MUST be validated before processing:- Type checking (string, int, email format, etc.)- Length limits enforced- Character whitelisting for IDs/filenames- SQL injection prevention via parameterized queries- XSS prevention via output escaping
### Validation Implementation- Use Pydantic models for API input validation- Database queries use SQLAlchemy parameterization- Templates use auto-escaping (Jinja2)Workflow Impact
Plan includes validation layer:
## Input Validation Architecture- Pydantic models for all API request bodies- Custom validators for email, phone, filename- Sanitization utilities for user-generated content- Automated XSS testing in integration testsTasks include security subtasks:
### WP04: User Profile Update API- [ ] T021: Create Pydantic model for profile data- [ ] T022: Add email format validator- [ ] T023: Add phone number validator- [ ] T024: Add filename sanitization- [ ] T025: Write XSS prevention tests- [ ] T026: Implement profile update endpoint- [ ] T027: Integration test with malicious inputReview checks security:
/spec-kitty.review
Security Checklist (Article V):- [ ] Input validation implemented? YES- [ ] Pydantic models used? YES- [ ] XSS test cases present? YES- [ ] Parameterized queries? YES
Approved for done/Benefits of Charter
1. Consistency Across Features
Every feature follows same standards automatically:
- Feature A: 84% coverage, input validation, <200ms
- Feature B: 87% coverage, input validation, <180ms
- Feature C: 81% coverage, input validation, <195ms
2. Prevents Shortcuts Under Pressure
Charter blocks acceptance when standards not met:
/spec-kitty.accept✗ Coverage: 68% - BLOCKED (15 more tests needed)Developer can’t skip quality gates even when rushed.
3. Onboarding New Developers
New team members see charter in every command:
- Specification shows quality requirements
- Plan includes testing/security strategy
- Tasks break down quality work
- Review validates compliance
4. Audit Trail
# Show charter version over timegit log .kittify/charter/charter.md
# See which features used which charter versiongrep "charter_version" kitty-specs/*/meta.json5. Living Documentation
Charter documents quality decisions:
- Why 80% coverage? (Balances thoroughness vs speed)
- Why 200ms target? (User experience research)
- Why no secrets? (Security incident from 2023)
Charter Evolution
Updating Charter
/spec-kitty.charter
Update Article III:- Increase coverage requirement from 80% to 85%- Add mutation testing requirement for critical paths- Require property-based tests for algorithms
Version bump: 1.2.0 → 2.0.0 (breaking change)Version Tracking
// meta.json in each feature{ "charter_version": "2.0.0", "accepted_at": "2025-01-20T15:30:00Z"}Grandfather Clause
Features accepted under v1.x don’t need to meet v2.x until updated.
Advanced: Custom Quality Gates
Example: Performance Benchmarking
## Article VIII: Performance Standards
### Benchmark RequirementsALL API endpoints MUST include performance benchmarks:- Locust load test: 1000 concurrent users- P50, P95, P99 latencies recorded- Results in `benchmarks/` directory- CI runs benchmarks on every PRTasks Auto-Generated
### WP05: Product Search API- [ ] T028: Implement search endpoint- [ ] T029: Write Locust benchmark script- [ ] T030: Run benchmark: 1000 concurrent users- [ ] T031: Record latencies in benchmarks/search.json- [ ] T032: Configure CI to run benchmarks- [ ] T033: Verify P95 < 200msAccept Command Validates
/spec-kitty.accept✓ Benchmark results found: benchmarks/search.json✓ P95 latency: 178ms (Target: <200ms) PASSCommon Charter Articles
Must-Have Articles
- Testing Standards - Coverage, test types, TDD
- Security Requirements - Input validation, secrets, auth
- Code Quality - Linting, complexity, documentation
- Performance Targets - Response times, bundle sizes
Optional Articles
- Accessibility - WCAG compliance, keyboard nav
- Internationalization - i18n support, localization
- Analytics - Event tracking, user telemetry
- Deployment - CI/CD, rollback procedures
Tips
- Start simple: 3-5 core principles, expand over time
- Make measurable: “Well-tested” → “80% coverage”
- Justify requirements: Explain WHY each standard exists
- Review quarterly: Update based on team learnings
- Version bumps: Major = breaking, Minor = additive, Patch = clarifications
- Enforce automatically: Charter only works if
/acceptvalidates it