feat: add twelve-factor app skill and compliance audit agent

[citypaul]

Summary

• New twelve-factor skill (377 lines) with actionable TypeScript patterns for building 12-factor compliant applications — covers all 12 factors with code examples, anti-patterns, and a verification checklist
• New twelve-factor-audit agent (330 lines) for auditing existing Node.js/TypeScript codebases against the 12-factor methodology — produces structured compliance reports with file/line citations, code suggestions, and prioritized action plans
• All 12 factors addressed: Factors I-XII with full code treatment for code-affecting factors and brief guidance for operational factors
• Greenfield projects must follow all factors; brownfield projects get a prioritized 5-step adoption order
• Integrated with /setup command for automatic detection of 12-factor patterns (Dockerfile, docker-compose, Procfile, .env.example, Kubernetes manifests)
• Updated install-claude.sh (16 skills, 10 agents), README.md, and agents/README.md with all counts, tables, and listings

Key design decisions

• Scope: Core factors (config, deps, backing services, logs) apply to any deployed app including frontends. Server-specific factors (port binding, concurrency, disposability) apply only to backend services.
• Code examples: All follow the repo's TypeScript conventions — factory functions, options objects, Zod schemas at trust boundaries, Pick<Config> for minimal surface, no any types
• Logging: Prescriptive on semantics (structured, stdout, levels, correlation IDs) but flexible on implementation (any library is fine)
• TDD integration: Dedicated section on how to test 12-factor patterns (config validation, shutdown, backing services) through behavior-driven tests
• Agent: Covers all 12 factors with Grep/Glob search patterns, false-positive guidance per factor, three response modes (full audit, quick health check, specific factor)

Files changed

File	Change
claude/.claude/skills/twelve-factor/SKILL.md	New (377 lines)
claude/.claude/agents/twelve-factor-audit.md	New (330 lines)
claude/.claude/CLAUDE.md	Skill catalog + workflow reference
claude/.claude/commands/setup.md	12-factor detection step
claude/.claude/agents/README.md	Agent entry, decision table, summary
README.md	Counts, tables, agent section, curl commands
install-claude.sh	mkdir, arrays, summary counts
.changeset/twelve-factor-skill.md	Minor bump

Test plan

• stow claude succeeds, ~/.claude/skills/twelve-factor/SKILL.md is symlinked
• grep twelve-factor ~/.claude/CLAUDE.md shows catalog entry and workflow reference
• ./install-claude.sh --skills-only includes the new skill
• Run twelve-factor-audit agent against an existing service project
• Run /setup on a project with a Dockerfile to verify 12-factor detection
• Verify all counts in README.md match actual file counts (16 skills, 10 agents)

🤖 Generated with Claude Code

[citypaul]

Automated PR Review

Summary

Category	Status	Issues
TDD Compliance	N/A	Documentation-only PR
Testing Quality	N/A	No production logic to test
TypeScript Strictness	PASS	All code examples follow strict conventions
Functional Patterns	PASS	All code examples use immutable patterns
General Quality	PASS	1 minor observation

Recommendation: APPROVE

CI: OpenCode Compatibility check passes.

---

What's Good

This is a well-structured documentation and tooling PR. The content quality is high throughout.

Skill content (SKILL.md):

• All TypeScript examples follow repo conventions precisely — factory functions with options objects, Pick<Config, ...> for minimal surface, Zod schemas at trust boundaries, z.infer<> for derived types, readonly arrays via as const, no any types
• The createConfig pattern is a clean reference implementation: validates at startup, logs structured JSON before process.exit(1), exports a plain Config type
• The graceful shutdown example is thorough: drain timeout via setTimeout, awaits server.close(), cleans up backing service connections, exits with process.exit(1) on failure — all the details that get missed in real projects
• The logging section is appropriately prescriptive on semantics (structured, stdout, levels, correlation IDs) while staying flexible on library choice — a good design decision for a reusable skill
• The brownfield adoption order (Config -> Logs -> Disposability -> Backing Services -> Stateless) is a practical prioritisation that acknowledges real-world constraints
• Cross-references to typescript-strict, testing, functional, and hexagonal-architecture skills are well-placed

Agent content (twelve-factor-audit.md):

• The false-positive guidance per factor is genuinely useful — the notes on localhost in .env.example being acceptable, new Map() inside a function vs. module scope, and Winston with console transport being compliant show careful thinking about real codebases
• The three response modes (full audit, quick health check, specific factor) follow the same pattern as other agents in the repo
• The instruction to write the report to twelve-factor-audit.md rather than chat is consistent with the output guardrails in CLAUDE.md
• Explicit use of Grep/Glob tools rather than bash grep is correctly enforced

Integration:

• CLAUDE.md skill catalogue entry and workflow reference are minimal and correct
• /setup detection heuristics (Dockerfile, docker-compose, Procfile, .env.example, PORT binding, k8s manifests) cover the common cases without being exhaustive
• All counts updated consistently across README.md, install-claude.sh, and agents/README.md
• Changeset file is present and correctly typed as minor

---

Suggestions (Nice to Have)

SKILL.md — Factor II example imports a package that may not be a standard dependency

The checkSystemDependencies example uses import which from 'which'. This is a real npm package and the example is illustrative, but a reader might add it as a dependency without realising it is only needed if their app shells out to system tools. A one-line note like "add which as a dependency if your app calls system tools" would make the example self-contained. Very minor.

twelve-factor-audit.md — Factor VI search pattern for in-process schedulers

The Grep pattern for setInterval|node-cron|schedule\.scheduleJob will match test files and utility helpers. The other factors explicitly note exclusion of test files, but Factor VI does not include the same false-positive note. Consistent to add: "False positive note: setInterval in test utilities (fake timers) and one-off scripts is acceptable. Only flag production request-handling code."

---

_{Generated by pr-reviewer agent}