feat: add patterns library with @ reference support

Phase 3: Patterns Library
- Create src/bmm/patterns/ with reusable pattern files:
  - hospital-grade.md - Quality standards for safety-critical code
  - tdd.md - Test-driven development guidance
  - security-checklist.md - OWASP-based security review
  - verification.md - File and code verification patterns
  - agent-completion.md - Standard output format for agents

- Update all agent templates with <execution_context> sections:
  - builder.md: @patterns/hospital-grade, tdd, agent-completion
  - inspector.md: @patterns/verification, hospital-grade, agent-completion
  - reviewer.md: @patterns/security-checklist, hospital-grade, agent-completion
  - fixer.md: @patterns/hospital-grade, agent-completion

This follows GSD's @ reference pattern for loading context.
This commit is contained in:
Jonah Schulte 2026-01-26 23:36:26 -05:00
parent 07592e4c36
commit 46ec840235
18 changed files with 1358 additions and 0 deletions

View File

@ -0,0 +1,187 @@
# Agent Completion Format
<overview>
All agents must return structured output that the orchestrator can parse. This enables automated verification and reliable workflow progression.
**Principle:** Return parseable data, not prose. The orchestrator needs to extract file lists, status, and evidence.
</overview>
<format>
## Standard Completion Format
Every agent returns this structure when done:
```markdown
## AGENT COMPLETE
**Agent:** [builder|inspector|reviewer|fixer]
**Story:** {{story_key}}
**Status:** [SUCCESS|PASS|FAIL|ISSUES_FOUND|PARTIAL]
### [Agent-Specific Section]
[See below for each agent type]
### Files Created
- path/to/new/file.ts
- path/to/another.ts
### Files Modified
- path/to/existing/file.ts
### Ready For
[Next phase or action required]
```
</format>
<builder_format>
## Builder Agent Output
```markdown
## AGENT COMPLETE
**Agent:** builder
**Story:** {{story_key}}
**Status:** SUCCESS | FAILED
### Files Created
- src/lib/feature/service.ts
- src/lib/feature/__tests__/service.test.ts
### Files Modified
- src/app/api/feature/route.ts
### Tests Added
- 3 test files
- 12 test cases total
### Implementation Summary
Brief description of what was built.
### Known Gaps
- Edge case X not handled
- NONE if all complete
### Ready For
Inspector validation
```
</builder_format>
<inspector_format>
## Inspector Agent Output
```markdown
## AGENT COMPLETE
**Agent:** inspector
**Story:** {{story_key}}
**Status:** PASS | FAIL
### Evidence
- **Type Check:** PASS (0 errors)
- **Lint:** PASS (0 warnings)
- **Build:** PASS
- **Tests:** 45 passing, 0 failing, 92% coverage
### Files Verified
- src/lib/feature/service.ts ✓
- src/app/api/feature/route.ts ✓
### Failures (if FAIL status)
1. Type error in service.ts:45
2. Test failing: "should handle empty input"
### Ready For
Reviewer (if PASS) | Builder fix (if FAIL)
```
</inspector_format>
<reviewer_format>
## Reviewer Agent Output
```markdown
## AGENT COMPLETE
**Agent:** reviewer
**Story:** {{story_key}}
**Status:** ISSUES_FOUND | CLEAN
### Issue Summary
- **CRITICAL:** 1 (security, data loss)
- **HIGH:** 2 (production bugs)
- **MEDIUM:** 3 (tech debt)
- **LOW:** 1 (nice-to-have)
### Must Fix (CRITICAL + HIGH)
1. [CRITICAL] service.ts:45 - SQL injection vulnerability
2. [HIGH] route.ts:23 - Missing authorization check
3. [HIGH] service.ts:78 - Unhandled null case
### Should Fix (MEDIUM)
1. service.ts:92 - No error logging
### Files Reviewed
- src/lib/feature/service.ts ✓
- src/app/api/feature/route.ts ✓
### Ready For
Fixer agent to address CRITICAL and HIGH issues
```
</reviewer_format>
<fixer_format>
## Fixer Agent Output
```markdown
## AGENT COMPLETE
**Agent:** fixer
**Story:** {{story_key}}
**Status:** SUCCESS | PARTIAL | FAILED
### Issues Fixed
- **CRITICAL:** 1/1 fixed
- **HIGH:** 2/2 fixed
- **Total:** 3 issues resolved
### Fixes Applied
1. [CRITICAL] service.ts:45 - Parameterized query
2. [HIGH] route.ts:23 - Added auth check
3. [HIGH] service.ts:78 - Added null guard
### Quality Checks
- **Type Check:** PASS
- **Lint:** PASS
- **Tests:** 47 passing (2 new)
### Git Commit
- **Hash:** abc123def
- **Message:** fix({{story_key}}): address security and null handling
### Deferred Issues
- MEDIUM: 3 (defer to follow-up)
- LOW: 1 (skip as gold-plating)
### Ready For
Orchestrator reconciliation
```
</fixer_format>
<parsing_hints>
## Parsing Hints for Orchestrator
Extract key data using grep:
```bash
# Get status
grep "^\*\*Status:\*\*" agent_output.txt | cut -d: -f2 | xargs
# Get files created
sed -n '/### Files Created/,/###/p' agent_output.txt | grep "^-" | cut -d' ' -f2
# Get issue count
grep "CRITICAL:" agent_output.txt | grep -oE "[0-9]+"
# Check if ready for next phase
grep "### Ready For" -A 1 agent_output.txt | tail -1
```
</parsing_hints>

View File

@ -0,0 +1,111 @@
# Hospital-Grade Code Standards
<overview>
This code may be deployed in healthcare, financial, or safety-critical contexts where failures have serious consequences. Every line of code must meet hospital-grade reliability standards.
**Principle:** Quality >> Speed. Take 5 hours to do it right, not 1 hour to do it poorly.
</overview>
<mindset>
## Think Like a Hospital Engineer
Before writing any code, ask:
- What happens if this fails at 3 AM?
- What happens if input is malformed?
- What happens if a dependency is unavailable?
- What happens if this runs with 10x expected load?
- Would I trust this code with patient data?
If you can't answer confidently, add safeguards.
</mindset>
<required_practices>
## Non-Negotiable Practices
**Error Handling:**
- Every external call wrapped in try/catch
- Meaningful error messages (not just "Error occurred")
- Graceful degradation when possible
- Errors logged with context (user, action, timestamp)
**Input Validation:**
- Never trust user input
- Validate at system boundaries
- Use schema validation (zod, joi, etc.)
- Sanitize before database operations
**Type Safety:**
- No `any` types (TypeScript)
- Explicit return types on functions
- Null checks before property access
- Union types for known variants
**Authentication/Authorization:**
- Every endpoint checks auth
- Every data access checks ownership
- No security through obscurity
- Principle of least privilege
</required_practices>
<forbidden>
## Forbidden Patterns
**Never do these:**
```typescript
// BAD: Swallowed errors
try { doThing() } catch (e) { }
// BAD: any type
function process(data: any) { }
// BAD: No null check
const name = user.profile.name
// BAD: String concatenation in queries
const query = `SELECT * FROM users WHERE id = '${id}'`
// BAD: Hardcoded secrets
const apiKey = "sk_live_abc123"
// BAD: TODO comments left in production
// TODO: implement validation
// BAD: Console.log debugging
console.log("got here")
```
</forbidden>
<quality_gates>
## Quality Gates (All Must Pass)
Before code is considered complete:
```bash
# Type check - zero errors
npm run type-check
# Lint - zero errors, zero warnings
npm run lint
# Tests - all passing
npm test
# Build - succeeds
npm run build
```
If any gate fails, code is not done.
</quality_gates>
<verification>
## Verification Checklist
- [ ] All error paths handled
- [ ] Input validated at boundaries
- [ ] No `any` types
- [ ] No hardcoded secrets
- [ ] No TODO/FIXME in production code
- [ ] Tests cover happy path AND error paths
- [ ] Auth checks on all protected routes
- [ ] Logging for debugging without exposing PII
</verification>

View File

@ -0,0 +1,122 @@
# Security Review Checklist
<overview>
Security vulnerabilities are CRITICAL issues. A single vulnerability can expose user data, enable account takeover, or cause financial loss.
**Principle:** Assume all input is malicious. Validate everything.
</overview>
<owasp_top_10>
## OWASP Top 10 Checks
### 1. Injection
```bash
# Check for SQL injection
grep -E "SELECT.*\+|INSERT.*\+|UPDATE.*\+|DELETE.*\+" . -r
grep -E '\$\{.*\}.*query|\`.*\$\{' . -r
# Check for command injection
grep -E "exec\(|spawn\(|system\(" . -r
```
**Fix:** Use parameterized queries, never string concatenation.
### 2. Broken Authentication
```bash
# Check for hardcoded credentials
grep -E "password.*=.*['\"]|api.?key.*=.*['\"]|secret.*=.*['\"]" . -r -i
# Check for weak session handling
grep -E "localStorage.*token|sessionStorage.*password" . -r
```
**Fix:** Use secure session management, never store secrets in code.
### 3. Sensitive Data Exposure
```bash
# Check for PII logging
grep -E "console\.(log|info|debug).*password|log.*email|log.*ssn" . -r -i
# Check for unencrypted transmission
grep -E "http://(?!localhost)" . -r
```
**Fix:** Never log sensitive data, always use HTTPS.
### 4. XML External Entities (XXE)
```bash
# Check for unsafe XML parsing
grep -E "parseXML|DOMParser|xml2js" . -r
```
**Fix:** Disable external entity processing.
### 5. Broken Access Control
```bash
# Check for missing auth checks
grep -E "export.*function.*(GET|POST|PUT|DELETE)" . -r | head -20
# Then verify each has auth check
```
**Fix:** Every endpoint must verify user has permission.
### 6. Security Misconfiguration
```bash
# Check for debug mode in prod
grep -E "debug.*true|NODE_ENV.*development" . -r
# Check for default credentials
grep -E "admin.*admin|password.*password|123456" . -r
```
**Fix:** Secure configuration, no defaults.
### 7. Cross-Site Scripting (XSS)
```bash
# Check for innerHTML usage
grep -E "innerHTML|dangerouslySetInnerHTML" . -r
# Check for unescaped output
grep -E "\$\{.*\}.*<|<.*\$\{" . -r
```
**Fix:** Always escape user input, use safe rendering.
### 8. Insecure Deserialization
```bash
# Check for unsafe JSON parsing
grep -E "JSON\.parse\(.*req\." . -r
grep -E "eval\(|Function\(" . -r
```
**Fix:** Validate structure before parsing.
### 9. Using Components with Known Vulnerabilities
```bash
# Check for outdated dependencies
npm audit
```
**Fix:** Keep dependencies updated, monitor CVEs.
### 10. Insufficient Logging
```bash
# Check for security event logging
grep -E "log.*(login|auth|permission|access)" . -r
```
**Fix:** Log security events with context.
</owasp_top_10>
<severity_ratings>
## Severity Ratings
| Severity | Impact | Examples |
|----------|--------|----------|
| CRITICAL | Data breach, account takeover | SQL injection, auth bypass |
| HIGH | Service disruption, data corruption | Logic flaws, N+1 queries |
| MEDIUM | Technical debt, maintainability | Missing validation, tight coupling |
| LOW | Code style, nice-to-have | Naming, documentation |
**CRITICAL and HIGH must be fixed before merge.**
</severity_ratings>

93
src/bmm/patterns/tdd.md Normal file
View File

@ -0,0 +1,93 @@
# Test-Driven Development Pattern
<overview>
TDD is about design quality, not coverage metrics. Writing tests first forces you to think about behavior before implementation.
**Principle:** If you can describe behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
</overview>
<when_to_use>
## When TDD Improves Quality
**Use TDD for:**
- Business logic with defined inputs/outputs
- API endpoints with request/response contracts
- Data transformations, parsing, formatting
- Validation rules and constraints
- Algorithms with testable behavior
**Skip TDD for:**
- UI layout and styling
- Configuration changes
- Glue code connecting existing components
- One-off scripts
- Simple CRUD with no business logic
</when_to_use>
<red_green_refactor>
## Red-Green-Refactor Cycle
**RED - Write failing test:**
1. Create test describing expected behavior
2. Run test - it MUST fail
3. If test passes: feature exists or test is wrong
**GREEN - Implement to pass:**
1. Write minimal code to make test pass
2. No cleverness, no optimization - just make it work
3. Run test - it MUST pass
**REFACTOR (if needed):**
1. Clean up implementation
2. Run tests - MUST still pass
3. Only commit if changes made
</red_green_refactor>
<test_quality>
## Good Tests vs Bad Tests
**Test behavior, not implementation:**
```typescript
// GOOD: Tests observable behavior
expect(formatDate(new Date('2024-01-15'))).toBe('Jan 15, 2024')
// BAD: Tests implementation details
expect(formatDate).toHaveBeenCalledWith(expect.any(Date))
```
**One concept per test:**
```typescript
// GOOD: Separate tests
it('accepts valid email', () => { ... })
it('rejects empty email', () => { ... })
it('rejects malformed email', () => { ... })
// BAD: Multiple assertions
it('validates email', () => {
expect(validate('test@example.com')).toBe(true)
expect(validate('')).toBe(false)
expect(validate('invalid')).toBe(false)
})
```
**Descriptive names:**
```typescript
// GOOD
it('returns null for invalid user ID')
it('should reject empty email')
// BAD
it('test1')
it('handles error')
it('works')
```
</test_quality>
<coverage_targets>
## Coverage Targets
- **90%+ line coverage** for new code
- **100% branch coverage** for critical paths (auth, payments)
- **Every error path** has at least one test
- **Edge cases** explicitly tested
</coverage_targets>

View File

@ -0,0 +1,143 @@
# Verification Patterns
<overview>
Existence ≠ Implementation. A file existing does not mean the feature works.
**Verification levels:**
1. **Exists** - File is present
2. **Substantive** - Content is real, not placeholder
3. **Wired** - Connected to rest of system
4. **Functional** - Actually works when invoked
</overview>
<stub_detection>
## Detecting Stubs and Placeholders
```bash
# Comment-based stubs
grep -E "(TODO|FIXME|XXX|PLACEHOLDER)" "$file"
grep -E "implement|add later|coming soon" "$file" -i
# Empty implementations
grep -E "return null|return undefined|return \{\}|return \[\]" "$file"
grep -E "console\.(log|warn).*only" "$file"
# Placeholder text
grep -E "placeholder|lorem ipsum|sample data" "$file" -i
```
**Red flags in code:**
```typescript
// STUBS - Not real implementations:
return <div>Placeholder</div>
onClick={() => {}}
export async function POST() { return Response.json({ ok: true }) }
```
</stub_detection>
<file_verification>
## File Verification Commands
**React Components:**
```bash
# Exists and exports component
[ -f "$file" ] && grep -E "export.*function|export const.*=" "$file"
# Has real JSX (not null/empty)
grep -E "return.*<" "$file" | grep -v "return.*null"
# Uses props/state (not static)
grep -E "props\.|useState|useEffect" "$file"
```
**API Routes:**
```bash
# Exports HTTP handlers
grep -E "export.*(GET|POST|PUT|DELETE)" "$file"
# Has database interaction
grep -E "prisma\.|db\.|query|find|create" "$file"
# Has error handling
grep -E "try|catch|throw" "$file"
```
**Tests:**
```bash
# Test file exists
[ -f "$test_file" ]
# Has test cases
grep -E "it\(|test\(|describe\(" "$test_file"
# Not all skipped
grep -c "\.skip" "$test_file"
```
</file_verification>
<quality_commands>
## Quality Check Commands
```bash
# Type check - zero errors
npm run type-check
echo "Exit code: $?"
# Lint - zero errors/warnings
npm run lint 2>&1 | tail -5
# Tests - all passing
npm test 2>&1 | grep -E "pass|fail|error" -i | tail -10
# Build - succeeds
npm run build 2>&1 | tail -5
```
**All must return exit code 0.**
</quality_commands>
<wiring_checks>
## Wiring Verification
**Component → API:**
```bash
# Check component calls the API
grep -E "fetch\(['\"].*$api_path|axios.*$api_path" "$component"
```
**API → Database:**
```bash
# Check API queries database
grep -E "await.*prisma|await.*db\." "$route"
```
**Form → Handler:**
```bash
# Check form has real submit handler
grep -A 5 "onSubmit" "$component" | grep -E "fetch|axios|mutate"
```
</wiring_checks>
<verdict_format>
## Verdict Format
```markdown
## VALIDATION RESULT
**Status:** PASS | FAIL
### Evidence
- Type check: PASS (0 errors)
- Lint: PASS (0 warnings)
- Build: PASS
- Tests: 45/45 passing
### Files Verified
- path/to/file.ts ✓
- path/to/other.ts ✓
### Failures (if FAIL)
1. [CRITICAL] Missing file: src/api/route.ts
2. [HIGH] Type error in lib/auth.ts:45
```
</verdict_format>

View File

@ -4,6 +4,12 @@
**Steps:** 1-4 (init, pre-gap, write-tests, implement) **Steps:** 1-4 (init, pre-gap, write-tests, implement)
**Trust Level:** LOW (assume will cut corners) **Trust Level:** LOW (assume will cut corners)
<execution_context>
@patterns/hospital-grade.md
@patterns/tdd.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -4,6 +4,11 @@
**Steps:** 8-9 (review-analysis, fix-issues) **Steps:** 8-9 (review-analysis, fix-issues)
**Trust Level:** MEDIUM (incentive to minimize work) **Trust Level:** MEDIUM (incentive to minimize work)
<execution_context>
@patterns/hospital-grade.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -4,6 +4,12 @@
**Steps:** 5-6 (post-validation, quality-checks) **Steps:** 5-6 (post-validation, quality-checks)
**Trust Level:** MEDIUM (no conflict of interest) **Trust Level:** MEDIUM (no conflict of interest)
<execution_context>
@patterns/verification.md
@patterns/hospital-grade.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -4,6 +4,12 @@
**Steps:** 7 (code-review) **Steps:** 7 (code-review)
**Trust Level:** HIGH (wants to find issues) **Trust Level:** HIGH (wants to find issues)
<execution_context>
@patterns/security-checklist.md
@patterns/hospital-grade.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -0,0 +1,187 @@
# Agent Completion Format
<overview>
All agents must return structured output that the orchestrator can parse. This enables automated verification and reliable workflow progression.
**Principle:** Return parseable data, not prose. The orchestrator needs to extract file lists, status, and evidence.
</overview>
<format>
## Standard Completion Format
Every agent returns this structure when done:
```markdown
## AGENT COMPLETE
**Agent:** [builder|inspector|reviewer|fixer]
**Story:** {{story_key}}
**Status:** [SUCCESS|PASS|FAIL|ISSUES_FOUND|PARTIAL]
### [Agent-Specific Section]
[See below for each agent type]
### Files Created
- path/to/new/file.ts
- path/to/another.ts
### Files Modified
- path/to/existing/file.ts
### Ready For
[Next phase or action required]
```
</format>
<builder_format>
## Builder Agent Output
```markdown
## AGENT COMPLETE
**Agent:** builder
**Story:** {{story_key}}
**Status:** SUCCESS | FAILED
### Files Created
- src/lib/feature/service.ts
- src/lib/feature/__tests__/service.test.ts
### Files Modified
- src/app/api/feature/route.ts
### Tests Added
- 3 test files
- 12 test cases total
### Implementation Summary
Brief description of what was built.
### Known Gaps
- Edge case X not handled
- NONE if all complete
### Ready For
Inspector validation
```
</builder_format>
<inspector_format>
## Inspector Agent Output
```markdown
## AGENT COMPLETE
**Agent:** inspector
**Story:** {{story_key}}
**Status:** PASS | FAIL
### Evidence
- **Type Check:** PASS (0 errors)
- **Lint:** PASS (0 warnings)
- **Build:** PASS
- **Tests:** 45 passing, 0 failing, 92% coverage
### Files Verified
- src/lib/feature/service.ts ✓
- src/app/api/feature/route.ts ✓
### Failures (if FAIL status)
1. Type error in service.ts:45
2. Test failing: "should handle empty input"
### Ready For
Reviewer (if PASS) | Builder fix (if FAIL)
```
</inspector_format>
<reviewer_format>
## Reviewer Agent Output
```markdown
## AGENT COMPLETE
**Agent:** reviewer
**Story:** {{story_key}}
**Status:** ISSUES_FOUND | CLEAN
### Issue Summary
- **CRITICAL:** 1 (security, data loss)
- **HIGH:** 2 (production bugs)
- **MEDIUM:** 3 (tech debt)
- **LOW:** 1 (nice-to-have)
### Must Fix (CRITICAL + HIGH)
1. [CRITICAL] service.ts:45 - SQL injection vulnerability
2. [HIGH] route.ts:23 - Missing authorization check
3. [HIGH] service.ts:78 - Unhandled null case
### Should Fix (MEDIUM)
1. service.ts:92 - No error logging
### Files Reviewed
- src/lib/feature/service.ts ✓
- src/app/api/feature/route.ts ✓
### Ready For
Fixer agent to address CRITICAL and HIGH issues
```
</reviewer_format>
<fixer_format>
## Fixer Agent Output
```markdown
## AGENT COMPLETE
**Agent:** fixer
**Story:** {{story_key}}
**Status:** SUCCESS | PARTIAL | FAILED
### Issues Fixed
- **CRITICAL:** 1/1 fixed
- **HIGH:** 2/2 fixed
- **Total:** 3 issues resolved
### Fixes Applied
1. [CRITICAL] service.ts:45 - Parameterized query
2. [HIGH] route.ts:23 - Added auth check
3. [HIGH] service.ts:78 - Added null guard
### Quality Checks
- **Type Check:** PASS
- **Lint:** PASS
- **Tests:** 47 passing (2 new)
### Git Commit
- **Hash:** abc123def
- **Message:** fix({{story_key}}): address security and null handling
### Deferred Issues
- MEDIUM: 3 (defer to follow-up)
- LOW: 1 (skip as gold-plating)
### Ready For
Orchestrator reconciliation
```
</fixer_format>
<parsing_hints>
## Parsing Hints for Orchestrator
Extract key data using grep:
```bash
# Get status
grep "^\*\*Status:\*\*" agent_output.txt | cut -d: -f2 | xargs
# Get files created
sed -n '/### Files Created/,/###/p' agent_output.txt | grep "^-" | cut -d' ' -f2
# Get issue count
grep "CRITICAL:" agent_output.txt | grep -oE "[0-9]+"
# Check if ready for next phase
grep "### Ready For" -A 1 agent_output.txt | tail -1
```
</parsing_hints>

View File

@ -0,0 +1,111 @@
# Hospital-Grade Code Standards
<overview>
This code may be deployed in healthcare, financial, or safety-critical contexts where failures have serious consequences. Every line of code must meet hospital-grade reliability standards.
**Principle:** Quality >> Speed. Take 5 hours to do it right, not 1 hour to do it poorly.
</overview>
<mindset>
## Think Like a Hospital Engineer
Before writing any code, ask:
- What happens if this fails at 3 AM?
- What happens if input is malformed?
- What happens if a dependency is unavailable?
- What happens if this runs with 10x expected load?
- Would I trust this code with patient data?
If you can't answer confidently, add safeguards.
</mindset>
<required_practices>
## Non-Negotiable Practices
**Error Handling:**
- Every external call wrapped in try/catch
- Meaningful error messages (not just "Error occurred")
- Graceful degradation when possible
- Errors logged with context (user, action, timestamp)
**Input Validation:**
- Never trust user input
- Validate at system boundaries
- Use schema validation (zod, joi, etc.)
- Sanitize before database operations
**Type Safety:**
- No `any` types (TypeScript)
- Explicit return types on functions
- Null checks before property access
- Union types for known variants
**Authentication/Authorization:**
- Every endpoint checks auth
- Every data access checks ownership
- No security through obscurity
- Principle of least privilege
</required_practices>
<forbidden>
## Forbidden Patterns
**Never do these:**
```typescript
// BAD: Swallowed errors
try { doThing() } catch (e) { }
// BAD: any type
function process(data: any) { }
// BAD: No null check
const name = user.profile.name
// BAD: String concatenation in queries
const query = `SELECT * FROM users WHERE id = '${id}'`
// BAD: Hardcoded secrets
const apiKey = "sk_live_abc123"
// BAD: TODO comments left in production
// TODO: implement validation
// BAD: Console.log debugging
console.log("got here")
```
</forbidden>
<quality_gates>
## Quality Gates (All Must Pass)
Before code is considered complete:
```bash
# Type check - zero errors
npm run type-check
# Lint - zero errors, zero warnings
npm run lint
# Tests - all passing
npm test
# Build - succeeds
npm run build
```
If any gate fails, code is not done.
</quality_gates>
<verification>
## Verification Checklist
- [ ] All error paths handled
- [ ] Input validated at boundaries
- [ ] No `any` types
- [ ] No hardcoded secrets
- [ ] No TODO/FIXME in production code
- [ ] Tests cover happy path AND error paths
- [ ] Auth checks on all protected routes
- [ ] Logging for debugging without exposing PII
</verification>

View File

@ -0,0 +1,122 @@
# Security Review Checklist
<overview>
Security vulnerabilities are CRITICAL issues. A single vulnerability can expose user data, enable account takeover, or cause financial loss.
**Principle:** Assume all input is malicious. Validate everything.
</overview>
<owasp_top_10>
## OWASP Top 10 Checks
### 1. Injection
```bash
# Check for SQL injection
grep -E "SELECT.*\+|INSERT.*\+|UPDATE.*\+|DELETE.*\+" . -r
grep -E '\$\{.*\}.*query|\`.*\$\{' . -r
# Check for command injection
grep -E "exec\(|spawn\(|system\(" . -r
```
**Fix:** Use parameterized queries, never string concatenation.
### 2. Broken Authentication
```bash
# Check for hardcoded credentials
grep -E "password.*=.*['\"]|api.?key.*=.*['\"]|secret.*=.*['\"]" . -r -i
# Check for weak session handling
grep -E "localStorage.*token|sessionStorage.*password" . -r
```
**Fix:** Use secure session management, never store secrets in code.
### 3. Sensitive Data Exposure
```bash
# Check for PII logging
grep -E "console\.(log|info|debug).*password|log.*email|log.*ssn" . -r -i
# Check for unencrypted transmission
grep -E "http://(?!localhost)" . -r
```
**Fix:** Never log sensitive data, always use HTTPS.
### 4. XML External Entities (XXE)
```bash
# Check for unsafe XML parsing
grep -E "parseXML|DOMParser|xml2js" . -r
```
**Fix:** Disable external entity processing.
### 5. Broken Access Control
```bash
# Check for missing auth checks
grep -E "export.*function.*(GET|POST|PUT|DELETE)" . -r | head -20
# Then verify each has auth check
```
**Fix:** Every endpoint must verify user has permission.
### 6. Security Misconfiguration
```bash
# Check for debug mode in prod
grep -E "debug.*true|NODE_ENV.*development" . -r
# Check for default credentials
grep -E "admin.*admin|password.*password|123456" . -r
```
**Fix:** Secure configuration, no defaults.
### 7. Cross-Site Scripting (XSS)
```bash
# Check for innerHTML usage
grep -E "innerHTML|dangerouslySetInnerHTML" . -r
# Check for unescaped output
grep -E "\$\{.*\}.*<|<.*\$\{" . -r
```
**Fix:** Always escape user input, use safe rendering.
### 8. Insecure Deserialization
```bash
# Check for unsafe JSON parsing
grep -E "JSON\.parse\(.*req\." . -r
grep -E "eval\(|Function\(" . -r
```
**Fix:** Validate structure before parsing.
### 9. Using Components with Known Vulnerabilities
```bash
# Check for outdated dependencies
npm audit
```
**Fix:** Keep dependencies updated, monitor CVEs.
### 10. Insufficient Logging
```bash
# Check for security event logging
grep -E "log.*(login|auth|permission|access)" . -r
```
**Fix:** Log security events with context.
</owasp_top_10>
<severity_ratings>
## Severity Ratings
| Severity | Impact | Examples |
|----------|--------|----------|
| CRITICAL | Data breach, account takeover | SQL injection, auth bypass |
| HIGH | Service disruption, data corruption | Logic flaws, N+1 queries |
| MEDIUM | Technical debt, maintainability | Missing validation, tight coupling |
| LOW | Code style, nice-to-have | Naming, documentation |
**CRITICAL and HIGH must be fixed before merge.**
</severity_ratings>

View File

@ -0,0 +1,93 @@
# Test-Driven Development Pattern
<overview>
TDD is about design quality, not coverage metrics. Writing tests first forces you to think about behavior before implementation.
**Principle:** If you can describe behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
</overview>
<when_to_use>
## When TDD Improves Quality
**Use TDD for:**
- Business logic with defined inputs/outputs
- API endpoints with request/response contracts
- Data transformations, parsing, formatting
- Validation rules and constraints
- Algorithms with testable behavior
**Skip TDD for:**
- UI layout and styling
- Configuration changes
- Glue code connecting existing components
- One-off scripts
- Simple CRUD with no business logic
</when_to_use>
<red_green_refactor>
## Red-Green-Refactor Cycle
**RED - Write failing test:**
1. Create test describing expected behavior
2. Run test - it MUST fail
3. If test passes: feature exists or test is wrong
**GREEN - Implement to pass:**
1. Write minimal code to make test pass
2. No cleverness, no optimization - just make it work
3. Run test - it MUST pass
**REFACTOR (if needed):**
1. Clean up implementation
2. Run tests - MUST still pass
3. Only commit if changes made
</red_green_refactor>
<test_quality>
## Good Tests vs Bad Tests
**Test behavior, not implementation:**
```typescript
// GOOD: Tests observable behavior
expect(formatDate(new Date('2024-01-15'))).toBe('Jan 15, 2024')
// BAD: Tests implementation details
expect(formatDate).toHaveBeenCalledWith(expect.any(Date))
```
**One concept per test:**
```typescript
// GOOD: Separate tests
it('accepts valid email', () => { ... })
it('rejects empty email', () => { ... })
it('rejects malformed email', () => { ... })
// BAD: Multiple assertions
it('validates email', () => {
expect(validate('test@example.com')).toBe(true)
expect(validate('')).toBe(false)
expect(validate('invalid')).toBe(false)
})
```
**Descriptive names:**
```typescript
// GOOD
it('returns null for invalid user ID')
it('should reject empty email')
// BAD
it('test1')
it('handles error')
it('works')
```
</test_quality>
<coverage_targets>
## Coverage Targets
- **90%+ line coverage** for new code
- **100% branch coverage** for critical paths (auth, payments)
- **Every error path** has at least one test
- **Edge cases** explicitly tested
</coverage_targets>

View File

@ -0,0 +1,143 @@
# Verification Patterns
<overview>
Existence ≠ Implementation. A file existing does not mean the feature works.
**Verification levels:**
1. **Exists** - File is present
2. **Substantive** - Content is real, not placeholder
3. **Wired** - Connected to rest of system
4. **Functional** - Actually works when invoked
</overview>
<stub_detection>
## Detecting Stubs and Placeholders
```bash
# Comment-based stubs
grep -E "(TODO|FIXME|XXX|PLACEHOLDER)" "$file"
grep -E "implement|add later|coming soon" "$file" -i
# Empty implementations
grep -E "return null|return undefined|return \{\}|return \[\]" "$file"
grep -E "console\.(log|warn).*only" "$file"
# Placeholder text
grep -E "placeholder|lorem ipsum|sample data" "$file" -i
```
**Red flags in code:**
```typescript
// STUBS - Not real implementations:
return <div>Placeholder</div>
onClick={() => {}}
export async function POST() { return Response.json({ ok: true }) }
```
</stub_detection>
<file_verification>
## File Verification Commands
**React Components:**
```bash
# Exists and exports component
[ -f "$file" ] && grep -E "export.*function|export const.*=" "$file"
# Has real JSX (not null/empty)
grep -E "return.*<" "$file" | grep -v "return.*null"
# Uses props/state (not static)
grep -E "props\.|useState|useEffect" "$file"
```
**API Routes:**
```bash
# Exports HTTP handlers
grep -E "export.*(GET|POST|PUT|DELETE)" "$file"
# Has database interaction
grep -E "prisma\.|db\.|query|find|create" "$file"
# Has error handling
grep -E "try|catch|throw" "$file"
```
**Tests:**
```bash
# Test file exists
[ -f "$test_file" ]
# Has test cases
grep -E "it\(|test\(|describe\(" "$test_file"
# Not all skipped
grep -c "\.skip" "$test_file"
```
</file_verification>
<quality_commands>
## Quality Check Commands
```bash
# Type check - zero errors
npm run type-check
echo "Exit code: $?"
# Lint - zero errors/warnings
npm run lint 2>&1 | tail -5
# Tests - all passing
npm test 2>&1 | grep -E "pass|fail|error" -i | tail -10
# Build - succeeds
npm run build 2>&1 | tail -5
```
**All must return exit code 0.**
</quality_commands>
<wiring_checks>
## Wiring Verification
**Component → API:**
```bash
# Check component calls the API
grep -E "fetch\(['\"].*$api_path|axios.*$api_path" "$component"
```
**API → Database:**
```bash
# Check API queries database
grep -E "await.*prisma|await.*db\." "$route"
```
**Form → Handler:**
```bash
# Check form has real submit handler
grep -A 5 "onSubmit" "$component" | grep -E "fetch|axios|mutate"
```
</wiring_checks>
<verdict_format>
## Verdict Format
```markdown
## VALIDATION RESULT
**Status:** PASS | FAIL
### Evidence
- Type check: PASS (0 errors)
- Lint: PASS (0 warnings)
- Build: PASS
- Tests: 45/45 passing
### Files Verified
- path/to/file.ts ✓
- path/to/other.ts ✓
### Failures (if FAIL)
1. [CRITICAL] Missing file: src/api/route.ts
2. [HIGH] Type error in lib/auth.ts:45
```
</verdict_format>

View File

@ -4,6 +4,12 @@
**Steps:** 1-4 (init, pre-gap, write-tests, implement) **Steps:** 1-4 (init, pre-gap, write-tests, implement)
**Trust Level:** LOW (assume will cut corners) **Trust Level:** LOW (assume will cut corners)
<execution_context>
@patterns/hospital-grade.md
@patterns/tdd.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -4,6 +4,11 @@
**Steps:** 8-9 (review-analysis, fix-issues) **Steps:** 8-9 (review-analysis, fix-issues)
**Trust Level:** MEDIUM (incentive to minimize work) **Trust Level:** MEDIUM (incentive to minimize work)
<execution_context>
@patterns/hospital-grade.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -4,6 +4,12 @@
**Steps:** 5-6 (post-validation, quality-checks) **Steps:** 5-6 (post-validation, quality-checks)
**Trust Level:** MEDIUM (no conflict of interest) **Trust Level:** MEDIUM (no conflict of interest)
<execution_context>
@patterns/verification.md
@patterns/hospital-grade.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission

View File

@ -4,6 +4,12 @@
**Steps:** 7 (code-review) **Steps:** 7 (code-review)
**Trust Level:** HIGH (wants to find issues) **Trust Level:** HIGH (wants to find issues)
<execution_context>
@patterns/security-checklist.md
@patterns/hospital-grade.md
@patterns/agent-completion.md
</execution_context>
--- ---
## Your Mission ## Your Mission