Twelve Factor Design

Twelve-Factor Design

Use this skill to design or review an application before implementation or major refactoring. It turns requirements, architecture notes, and platform constraints into a factor-by-factor design review with decisions, risks, evidence needs, and remediation candidates.

Triggers

• "Design this service as a Twelve-Factor app"
• "Review this architecture against 12+ Factor criteria"
• "Generate a cloud-native operational design checklist"
• "Check whether this design is platform portable and observable"

Behavior

1. Identify the application boundary: service name, runtime, deployment model, backing services, operators, users, and platform targets.
2. Collect available design inputs: requirements, ADRs, API contracts, event schemas, service diagrams, deployment notes, runbooks, test strategy, and security assumptions.
3. Review the original Twelve-Factor dimensions: codebase, dependencies, config, backing services, build/release/run, processes, port binding, concurrency, disposability, dev/prod parity, logs, and admin processes.
4. Review modern 12+ Factor extensions: API-first contracts, telemetry and observability, security by default, supply-chain provenance, dependency hygiene, runtime disposability, and platform portability.
5. For each factor, produce a status of pass, partial, fail, or not_applicable, with rationale and missing evidence.
6. Map factors to requirements, ADRs, tests, code/config paths, and operational artifacts when they exist.
7. Generate remediation tasks for gaps that block implementation, readiness review, or continuous audit.

Output

Return a design review with these sections:

• Application boundary and assumptions
• Factor coverage summary
• Factor-by-factor design decisions and risks
• Required evidence for later audit
• Remediation backlog candidates
• Open questions for humans

Examples

Input:

Review the checkout API design for 12+ Factor readiness. Inputs: ADR-004, OpenAPI spec, Dockerfile, Kubernetes deployment, runbook, and CI workflow.

Expected output:

Design status: partial
High-risk gaps: config separation, dev/prod parity, telemetry SLOs
Remediation: externalize payment provider config; add OpenTelemetry trace plan; add ADR for backing-service attachment and failover.

References

• @$AIWG_ROOT/agentic/code/addons/twelve-factor/checklists/design-checklist.md
• @$AIWG_ROOT/agentic/code/addons/twelve-factor/templates/remediation-backlog.md
• @$AIWG_ROOT/agentic/code/addons/twelve-factor/rules/twelve-factor-evidence.md