opencode-workflow/skills/finalize-architecture/SKILL.md

name	description
finalize-architecture	Final completeness check and format validation for the architecture document. The Architect pipeline's final step before handoff to Planner.

This skill performs a final completeness check and format validation on the architecture document after challenge and revision.

Announce at start: "I'm using the finalize-architecture skill to perform the final completeness check on the architecture document."

Primary Input

• docs/architecture/{feature}.md

Primary Output (STRICT PATH)

• Final docs/architecture/{feature}.md

This is the only file artifact in the Architect pipeline. Finalization results are applied directly to this file.

Process

You MUST complete these steps in order:

Step 1: Section Completeness Check

Verify all 18 required sections are present and substantive (or explicitly marked N/A with reason):

1. Overview
2. System Architecture
3. Service Boundaries
4. Data Flow
5. Database Schema
6. API Contract
7. Async / Queue Design
8. Consistency Model
9. Error Model
10. Security Boundaries
11. Integration Boundaries
12. Observability
13. Scaling Strategy
14. Non-Functional Requirements
15. Mermaid Diagrams
16. ADR
17. Risks
18. Open Questions

For each missing or empty section, add a placeholder with N/A — [reason] or flag it as a gap that must be filled.

Step 2: Mermaid Diagram Verification

Verify the document contains at minimum:

• 1 System Architecture Diagram — showing all services, databases, queues, and external integrations
• 1 Sequence Diagram — showing the primary happy-path interaction flow
• 1 Data Flow Diagram — showing how data moves through the system

For each diagram, verify:

• Mermaid syntax is valid
• All components referenced in the architecture are present in the diagram
• No orphan components exist in diagrams that are not described elsewhere

Step 3: Database Schema Verification

Verify the Database Schema section contains:

• All tables with field names, types, constraints, and defaults
• Indexes with justification based on query patterns
• Partition keys where applicable
• Relationships (foreign keys, references)
• Denormalization strategy where applicable
• Migration strategy notes

Step 4: API Contract Verification

Verify the API Contract section contains:

• All endpoints with method, path, request schema, response schema
• Error codes and error response schemas
• Idempotency requirements per endpoint (where applicable)
• Pagination and filtering (where applicable)
• Authentication requirements

Step 5: ADR Verification

Verify the ADR section contains at minimum 1 ADR with:

• ADR number and title
• Context
• Decision
• Consequences
• Alternatives considered

Step 6: Traceability Verification

Verify:

• Every API endpoint traces to a PRD functional requirement
• Every DB table traces to a data requirement
• Every service boundary traces to a domain responsibility
• Every async flow traces to a PRD requirement
• Every security boundary traces to a requirement
• Every integration boundary traces to an external system requirement

Step 7: Format Verification

Verify:

• The document follows the exact section ordering from the template
• Section headings use proper markdown hierarchy
• Mermaid code blocks use ```mermaid syntax
• Tables use proper markdown table syntax
• No external files are referenced (all content is within the single document)

Step 8: Architecture Review Gate

Verify the Architecture Review section from challenge-architecture:

• Gate decision is either PASS or CONDITIONAL PASS
• All identified issues have been addressed
• No unresolved blockers remain

Finalization Checklist

• All 18 required sections present and substantive (or N/A with reason)
• At least 3 Mermaid diagrams present (system, sequence, data flow)
• Database Schema has complete table definitions
• API Contract has complete endpoint specifications
• At least 1 ADR present with full format
• All elements trace to PRD requirements
• Architecture Review gate is PASS or CONDITIONAL PASS
• Document format follows template ordering
• No external file references (all content is inline)
• Risks section is populated
• Open Questions section is populated (or explicitly states "None")

Guardrails

This is a pure validation and formatting skill.

Do:

• Verify completeness of all 18 sections
• Validate Mermaid diagram syntax and coverage
• Validate API contract completeness
• Validate database schema completeness
• Validate ADR format
• Validate traceability
• Fix formatting issues directly in docs/architecture/{feature}.md

Do not:

• Design new architecture
• Change architectural decisions
• Add significant new content that wasn't validated in challenge-architecture
• Produce any file artifact other than docs/architecture/{feature}.md

Transition

After finalization is complete and all checks pass, the architecture document is ready for handoff to the Planner. The Planner reads only docs/architecture/{feature}.md.