Governance Skill Skill | Agent Skills

Governance Skill

Enforces engineering standards and code quality policies during development.

Standards Document: docs/architecture/standards.md Governance Documentation: docs/governance/ Audit Script: npm run audit:standards

Quick Start (First-Time Setup)

1. Run Setup Check

# Comprehensive governance setup verification
node .claude/skills/governance/scripts/governance-check.mjs

This checks CLAUDE.md, standards.md, audit script, ADRs, and pre-commit hooks with actionable fix instructions.

2. Understand the Two-Document Model

| Document | Purpose | Update Frequency | |----------|---------|------------------| | CLAUDE.md | AI operational context (commands, URLs, quick-ref) | Frequent | | standards.md | Engineering policy (authoritative) | Infrequent |

Rule: CLAUDE.md defers to standards.md for authoritative definitions.

3. Common Operations

# Check standards compliance
npm run audit:standards

# Typecheck before commit
npm run typecheck && npm run lint && npm run test

# View pre-commit checklist
cat docs/architecture/standards.md | grep -A20 "Pre-Commit Checklist"

When This Skill Activates

During Code Review

When reviewing code or discussing PRs, automatically check:

File length compliance (max 500 lines per file)
Naming conventions match project standards
Test coverage exists for new code
No forbidden patterns (any types, hardcoded secrets)

Before Commits

When helping prepare commits, remind about:

Pre-commit checklist (typecheck, lint, test)
Standards audit (npm run audit:standards)
Commit message format (conventional commits)

Core Standards Quick Reference

Full reference: docs/architecture/standards.md

Code Quality (§1)

| Standard | Requirement | Check | |----------|-------------|-------| | TypeScript | Strict mode enabled | npm run typecheck | | No any types | Use unknown for external data | Audit script | | Max file length | 500 lines | Audit script | | JSDoc | Required for public APIs | Audit script |

Naming Conventions (§1.2)

| Element | Convention | Example | |---------|------------|---------| | Components | PascalCase | Button.tsx, UserCard.astro | | Utilities | camelCase | userService.ts | | Variables | camelCase | getUserById() | | Constants | SCREAMING_SNAKE | const MAX_RETRIES = 3 | | DB columns | snake_case | user_id, created_at | | CSS classes | kebab-case | nav-sidebar |

Testing (§2)

| Layer | Target | Framework (example) | |-------|--------|---------------------| | Unit tests | 90-100% | Vitest, Jest, pytest | | API routes | 90-100% | Testing framework + supertest | | E2E critical paths | 100% | Playwright, Cypress |

Workflow (§3)

Branching: feature/, fix/, chore/, docs/ prefixes
Commits: <type>(scope): <description>
Review: All code requires approval before merge

Compliance Check

Run the standards audit before committing:

npm run audit:standards

This checks:

TypeScript strict mode
No any types in source
File length limits (500 lines)
JSDoc on exported functions
Test files exist
Feature flags module exists
CLAUDE.md exists
ADR directory exists
Pre-commit hooks configured

Handling Failures

| Failure | Resolution | |---------|------------| | File too long | Split into modules (document decision in ADR if significant) | | Missing JSDoc | Add documentation to exported functions | | any type found | Replace with proper type or unknown | | Missing tests | Add test coverage for new code |

Anti-Patterns vs Correct Patterns

Code Quality

| Anti-Pattern | Correct Pattern | Why | |--------------|-----------------|-----| | ❌ any type | ✅ unknown for external data | Type safety at runtime boundaries | | ❌ 600+ line files | ✅ Split at 500 lines | Maintainability, easier review | | ❌ console.log in production | ✅ Proper logging or remove | Security, performance | | ❌ Hardcoded secrets | ✅ Environment variables | Security best practice |

Documentation

| Anti-Pattern | Correct Pattern | Why | |--------------|-----------------|-----| | ❌ Duplicating policy in CLAUDE.md | ✅ Cross-reference standards.md | Single source of truth | | ❌ No JSDoc on public functions | ✅ JSDoc with @param, @returns | API discoverability | | ❌ Inline comments explaining "what" | ✅ Comments explaining "why" | Code should be self-documenting |

Workflow

| Anti-Pattern | Correct Pattern | Why | |--------------|-----------------|-----| | ❌ Committing directly to main | ✅ Feature branches with PR | Code review, CI checks | | ❌ git push --force to main | ✅ Never force-push protected branches | History integrity | | ❌ Skipping audit:standards | ✅ Run before every commit | Catch issues early | | ❌ Merge without review | ✅ Require approval | Quality gate |

Testing

| Anti-Pattern | Correct Pattern | Why | |--------------|-----------------|-----| | ❌ Tests after code | ✅ TDD or tests alongside | Better design, coverage | | ❌ Mocking internal modules | ✅ Mock only external services | Test real behavior | | ❌ Ignoring flaky tests | ✅ Fix or quarantine immediately | CI reliability |

Pre-Commit Checklist

Before every commit:

[ ] npm run typecheck     # TypeScript compiles
[ ] npm run lint          # Linter passes
[ ] npm run test          # Tests pass
[ ] npm run audit:standards  # Standards compliance
[ ] No console.log statements (use proper logging)
[ ] No hardcoded secrets
[ ] Meaningful commit message

PR Review Checklist

When reviewing or preparing PRs:

| Category | Criteria | |----------|----------| | Correctness | Does it work? Edge cases handled? | | Security | No secrets, injection vulnerabilities, or auth bypasses | | Performance | No N+1 queries, unnecessary re-renders, or memory leaks | | Style | Matches project conventions, readable, maintainable | | Testing | Tests exist for new functionality | | Scope | No unrelated changes, minimal footprint |

PR Description Template

## Summary
[What this PR does in 1-2 sentences]

## Ticket
[PROJECT-XXX](link)

## Changes
- Change 1
- Change 2

## Testing
- [ ] Unit tests added/updated
- [ ] Tested in deploy preview
- [ ] Edge cases considered

## Screenshots (if UI changes)
[Before/After screenshots]

Two-Document Model

This project uses a two-document governance model:

| Document | Purpose | Location | |----------|---------|----------| | CLAUDE.md | AI operational quick-reference | Project root | | standards.md | Engineering policy (authoritative) | docs/architecture/ |

CLAUDE.md is optimized for token efficiency — concise commands and context
standards.md is optimized for human comprehension — rationale and justifications

Rule: CLAUDE.md defers to standards.md for authoritative definitions using section references (§1.3).

Using This Skill in Other Projects

To replicate this governance model:

Copy the skill:

cp -r .claude/skills/governance /path/to/new-project/.claude/skills/

Copy governance docs:

cp -r docs/governance /path/to/new-project/docs/

Create standards.md using the template at docs/governance/guardrails-template.md
Create audit script using scripts/audit-standards.mjs as a starting point

Add npm script:

"audit:standards": "node scripts/audit-standards.mjs"

Update CLAUDE.md to cross-reference standards.md

Agent Skills: Governance Skill

Skill Files