materials

Twelve-Factor Audit

Use this skill to inspect an implemented application and produce a structured audit report that downstream quality, security, reporting, and delivery workflows can consume.

Triggers

• "Audit this repo against Twelve-Factor"
• "Produce a 12+ Factor evidence report"
• "Find cloud-native operational readiness gaps"
• "Turn Twelve-Factor audit findings into remediation issues"

Behavior

1. Establish the audit scope: application name, repo paths, deployment targets, environments, release process, and evidence sources.
2. Collect evidence from code, dependency manifests, lockfiles, configuration, deployment manifests, CI, tests, API contracts, logs, dashboards, runbooks, ADRs, and security/provenance artifacts.
3. Assess every original Twelve-Factor principle plus the modern extension factors listed in the addon README.
4. Assign each factor a status of pass, partial, fail, or not_applicable.
5. For every finding, cite concrete evidence paths or note missing evidence explicitly.
6. Record risks with severity and impact, then map remediation to owner-ready tasks.
7. Validate the report against schemas/audit-report.schema.json when the output is JSON.

Output

Use templates/audit-report.md for human-readable reports or the JSON contract in schemas/audit-report.schema.json for machine-readable reports. Every factor finding should include:

• Factor identifier and title
• Status
• Evidence list
• Risks
• Remediation tasks
• Traceability links to requirements, ADRs, tests, code/config, and issues when available

Examples

Input:

Audit the billing service. Evidence is in package.json, package-lock.json, Dockerfile, helm/, openapi.yaml, .gitea/workflows/test.yml, docs/runbooks/billing.md, and dashboards/billing.json.

Expected output:

Overall status: partial
Pass: codebase, dependencies, port binding, logs
Partial: config, backing services, telemetry, dependency hygiene
Fail: build/release/run separation, supply-chain provenance
Remediation: split release metadata from image build; add SBOM/provenance evidence; document backing-service attachment contracts.

References

• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/checklists/audit-checklist.md
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/templates/audit-report.md
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/schemas/audit-report.schema.json
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/fixtures/sample-audit-report.json
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/rules/twelve-factor-evidence.md