| namespace | aiwg |
| name | twelve-factor-design |
| description | Generate or review application architecture against Twelve-Factor and modern 12+ Factor design criteria. |
| platforms | ["all"] |
| triggers | ["twelve factor application design","12 factor design review","review architecture against 12+ factor","cloud native app design audit"] |
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
- Identify the application boundary: service name, runtime, deployment model, backing services, operators, users, and platform targets.
- Collect available design inputs: requirements, ADRs, API contracts, event schemas, service diagrams, deployment notes, runbooks, test strategy, and security assumptions.
- 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.
- Review modern 12+ Factor extensions: API-first contracts, telemetry and observability, security by default, supply-chain provenance, dependency hygiene, runtime disposability, and platform portability.
- For each factor, produce a status of
pass, partial, fail, or not_applicable, with rationale and missing evidence.
- Map factors to requirements, ADRs, tests, code/config paths, and operational artifacts when they exist.
- 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
