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
1---2namespace: aiwg3name: twelve-factor-design4description: Generate or review application architecture against Twelve-Factor and modern 12+ Factor design criteria.5platforms: [all]6triggers:7 - "twelve factor application design"8 - "12 factor design review"9 - "review architecture against 12+ factor"10 - "cloud native app design audit"11metadata:12 source: https://skillmd.com/skills/jmagly-ai-writing-guide/twelve-factor-design13---1415# Twelve-Factor Design1617Use 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.1819## Triggers2021- "Design this service as a Twelve-Factor app"22- "Review this architecture against 12+ Factor criteria"23- "Generate a cloud-native operational design checklist"24- "Check whether this design is platform portable and observable"2526## Behavior27281. Identify the application boundary: service name, runtime, deployment model, backing services, operators, users, and platform targets.292. Collect available design inputs: requirements, ADRs, API contracts, event schemas, service diagrams, deployment notes, runbooks, test strategy, and security assumptions.303. 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.314. Review modern 12+ Factor extensions: API-first contracts, telemetry and observability, security by default, supply-chain provenance, dependency hygiene, runtime disposability, and platform portability.325. For each factor, produce a status of `pass`, `partial`, `fail`, or `not_applicable`, with rationale and missing evidence.336. Map factors to requirements, ADRs, tests, code/config paths, and operational artifacts when they exist.347. Generate remediation tasks for gaps that block implementation, readiness review, or continuous audit.3536## Output3738Return a design review with these sections:3940- Application boundary and assumptions41- Factor coverage summary42- Factor-by-factor design decisions and risks43- Required evidence for later audit44- Remediation backlog candidates45- Open questions for humans4647## Examples4849Input:5051```text52Review the checkout API design for 12+ Factor readiness. Inputs: ADR-004, OpenAPI spec, Dockerfile, Kubernetes deployment, runbook, and CI workflow.53```5455Expected output:5657```text58Design status: partial59High-risk gaps: config separation, dev/prod parity, telemetry SLOs60Remediation: externalize payment provider config; add OpenTelemetry trace plan; add ADR for backing-service attachment and failover.61```6263## References6465- @$AIWG_ROOT/agentic/code/addons/twelve-factor/checklists/design-checklist.md66- @$AIWG_ROOT/agentic/code/addons/twelve-factor/templates/remediation-backlog.md67- @$AIWG_ROOT/agentic/code/addons/twelve-factor/rules/twelve-factor-evidence.md