align-architecture

Skill: Align Architecture

Purpose

Verify that the code implementation is consistent with the architecture and design decisions recorded in ADRs, design documents, or architecture specifications. When the implementation deviates from the recorded decisions, generate an architecture compliance report.

Core Objective

Governance Objective: Generate an actionable architecture compliance report that compares documented architecture/design decisions with the current implementation, and lists compliance gaps along with impact and remediation recommendations.

Success Criteria(all requirements must be met):

✅ Identify design sources: Find and parse ADRs, design documents, or architecture specifications
✅ Implementation comparison: Analyze the code against the recorded decisions
✅ Gap classification: Each compliance gap is classified (e.g., boundary violation, missing component, different pattern) along with impact and root cause
✅ Report persisted: The architecture compliance report is written to the agreed path
✅ Reference evidence: Each gap cites specific design sources and code locations; when partial verification is used, the covered/uncovered scope and confidence level are explicit
✅ Recommendation switch: When the design is outdated or conflicting, recommend设计-解决方案; when a structural review is needed, recommend "Review Architecture"

AcceptanceTest: Can a teammate read the report and immediately understand which architecture decisions were violated, where in the code, and what to do next?

Scope Boundaries

This skill is responsible for：

Design document and code comparison
Compliance gap detection and classification
Impact scope and root cause of each gap
Remediation and handoff recommendations

This skill is not responsible for：

Code structure review without a design reference (use "review-architecture")
Requirements analysis (use "analyze-requirements")
Design creation or design alternatives (use "design-solution")
Planning layer alignment (use "align-planning")

Handoff Point: After the report, if the design must change, hand off to "design-solution", or if there is no design comparison, hand off to "review-architecture" for a structural code review.

Use Cases

Post-implementation check: Verify that the implementation matches the ADR or design document
Milestone or release gate: Ensure architecture decisions are reflected in the code
Drift investigation: Diagnose when the implementation deviates from the documented design
Onboarding review: Help new contributors understand the design and the actual state

Orchestration Guidance

Scenario	Recommended Order
Routine task completion	`align-planning`(lightweight)
Milestone or release gate	`align-planning`(full) → then`align-architecture`
Post-implementation check	`对齐架构`
Both planning and architecture have issues	First perform "align-planning"; if the report indicates design-code drift → `align-architecture`

When planning-layer alignment is uncertain, run "align-planning" before "align-architecture"; otherwise, run "align-architecture" independently for design and code verification.

Behavior (behavior)

Phase 0: Norms Resolution (new in v1.3)

Implement per specs/artifact-contract.md §8 Runtime Norms Resolution Protocol §8.2 / §8.3 / §8.5: read the project specification; if it declares the architecture-compliance of artifact_type path_pattern, use the project value; otherwise fall through to the skill default (docs/calibration/architecture-compliance.md). This skill isfixed-path governance output, using only the path_pattern override mechanism.

Agent immediate contract

You are responsible for architecture compliance verification.

Compare documented architecture and design decisions (ADRs, design docs) against
the codebase and produce an Architecture Compliance Report when divergence exists.

Interaction (interaction) policy

Default: ADR/design paths from the project specification or "docs/architecture/", "docs/design-decisions/", "docs/process-management/decisions/"; code scope in the workspace
Select option: explicit design document paths when non-default; explicit code paths when partially scoped
Confirm: before proposing edits to design documents; before large code scopes

Phase 0: Resolve design sources and code scope

1. Resolve design source paths (project specification or default:docs/architecture/、docs/design-decisions/、docs/process-management/decisions/) 2. Resolve code scope:

Full: entire repository (default)
Incremental: user-specified paths, packages, or modules (for large codebases; verify only affected design decisions)

If there are no design documents, output a blocking report with the minimum required input; suggest "design solution" or "bootstrap documentation"

Phase 0.5: Evidence readiness assessment

Assess design coverage before comparison:

Strong: design documents exist for all relevant components/modules in scope
Weak: partial design documents; some components have ADRs, others do not — perform partial verification with lower confidence
Missing: no design documents; report is blocked, suggest design workflow

Rules:

When readiness is "weak", verify only decisions that have design sources; mark undiscovered code as "unknown" and list it in the report.
When readiness is "weak", do not claim high confidence.
Report explicitly: coverage, uncovered scope, and confidence.

Phase 1: Extract design decisions

Parse ADRs, design documents, and architecture specifications
Extract key decisions: boundaries, components, patterns, constraints
Establish decision indicators for comparison

Phase 2: Compare implementation

Analyze the code against each recorded decision
For each decision, evaluate: "compliant" | 部分 | 'violation' | 未知
Capture evidence: file paths, modules, or snippets
Gap classification:
- Boundary violation: code crosses documented module/layer boundaries
- Missing component: documented component or interface is not implemented
- Divergent pattern: implementation uses a different pattern than documented
- Outdated design: The design document may be outdated; the implementation may reflect the current intent - assign "recommended_action":
  - update_设计: Implementation is authoritative; the design should be updated to match (recommend "design-solution")
  - update_code: The design remains authoritative; the code should be refactored to match
  - "both": unclear; requires a stakeholder decision; recommend "design-solution" to reconcile

Phase 3: Generate Report

Summarize the investigation findings, including impact scope, root cause, and the "recommended action" for each gap
For each gap, clearly state: update the code, update the design, or both (see the gap types above)
When the design must change, recommend handing off to设计-解决方案; when only a structural review is needed, perform "review architecture"
Include evidence preparation and confidence when using partial verification

Phase 4: Persist Report

Write the report to:

The path resolved from the project specification (docs/ARTIFACT_NORMS.md or .ai-cortex/artifact-norms.yaml）
Default:docs/calibration/architecture-compliance.md(overridden unless a snapshot is explicitly requested)
Or a user-specified path

The report must contain a machine-readable compliance block (YAML or JSON).

Input & Output

Input

Optional ADR/design document path
Optional code scope (path or module)
Optional project documentation root directory

Output

Architecture compliance report template

# Architecture Compliance Report

**Date:** YYYY-MM-DD
**Design Sources:**
**Code Scope:**
**Status:** compliant | partial | violated
**Evidence Readiness:** strong | weak | missing (when partial verification used)
**Confidence:** high | medium | low

## Summary
- Total decisions checked:
- Compliant:
- Partial:
- Violated:

## Compliance Gaps

### Gap 1
- **Type:** boundary violation | missing component | divergent pattern | outdated design
- **Design Source:**
- **Code Location:**
- **Impact Scope:**
- **Root Cause:**
- **Recommended Action:** update_code | update_design | both
- **Remediation:**

## Covered / Uncovered Scope (when partial verification)
- Covered:
- Uncovered:
- Reason:

## Recommended Next Actions
1.
2.

## Machine-Readable Compliance

    evidence:
      readiness: "strong"  # strong | weak | missing
      confidence: "high"   # high | medium | low
    gaps:
      - type: "boundary violation"
        designSource: "docs/architecture/adr-001.md"
        codeLocation: "pkg/infra/db.go"
        impactScope: "Domain layer imports infrastructure"
        rootCause: "Repository interface not used; direct DB import"
        recommendedAction: "update_code"  # update_code | update_design | both
        remediation: "Implement repository pattern per ADR-001"

Limits

Hard Boundaries

When documentation is missing, do not invent design decisions; report is blocked and recommend the design workflow
When evidence readiness is "weak", do not claim high confidence (partial verification)
When the design source is incomplete or unclear, do not claim compliance
Do not silently modify design documents without explicit user approval
Do not perform a structural code review without a design reference (i.e., "review architecture")

Skill Boundaries (avoid overlap)

Do not do these (other skills can handle them)：

Code structure review only → 审查架构
Design creation or alternatives → 设计解决方案
Planning layer backtracking →align-planning

When to stop and hand off：

No design document exists → recommend "design-solution" or "bootstrap documentation"
The design is conflicting or outdated → hand off to "design-solution"
Structural code review without design comparison → hand off to "review architecture"

Self-Check

Core success criteria (all criteria must be met)

Identification and resolution of the design source
Code is compared with documented decisions (or partial verification when readiness is weak)
Each gap includes impact scope, root cause, and the "recommended action" when the type is outdated design
The report persists to the agreed path
Provide evidence references for each gap (including covered/uncovered scope and confidence when using partial verification)
Provide handoff recommendations when applicable

Acceptance Test

Can team members act on the first 1-3 compliance gaps without additional explanation?

If no: refine the evidence and clarify the remediation measures.

If yes: report complete; proceed with handover or remediation.

Examples (Examples)

Example 1: Boundary violation

Context: ADR-001 specifies that the domain must not import infrastructure. The code shows the domain package importing a database driver.

Output：

Type: Boundary violation
Design source:docs/process-management/decisions/20240101-adr-001-layered-architecture.md
Code location:pkg/domain/order.go(importpkg/infra/db）
Impact: The domain is coupled to infrastructure; this violates clean architecture
Fix: Define a repository interface in the domain; implement it in infrastructure; inject it via the constructor

Example 2: No design document

Background: The project has no ADR or design document.

Output：

Status: Blocked
Message: No architecture or design document found. Run "Design Solution" to create a design document, or run "bootstrap-docs" to establish the structure.
Confidence: Not applicable

Example 3: Partial validation (weak readiness)

Context: Only pkg/auth has an ADR; pkg/orders and pkg/inventory have no design document.

Output：

Evidence readiness: Weak
Confidence: Medium
Covered scope:pkg/auth(validated against ADR-002)
Uncovered scope:pkg/orders、pkg/inventory(no design source; marked as unknown)
The report continues to include the findings for "pkg/auth"; if compliance is required, it is recommended to create design documents for the uncovered packages

Example 4: Outdated design and recommended action

Context: ADR-003 specifies a synchronous API; the implementation uses an asynchronous event-driven flow, which stakeholders prefer.

Output：

Type: Outdated design
Recommended action: update_design
Fix: Update ADR-003 to document the asynchronous event-driven approach; the implementation is authoritative. Hand over to "Design Solution" to modify the design document.

Appendix: Output Contract (Appendix: Output Contract)

This skill produces an Architecture Compliance Report. In addition to the human-readable narrative, the machine-readable fragment must satisfy the structure in the following table:

Element	Format	Required fields	Path pattern
Report body	Markdown	front-matter (artifact_type/created_by/created_at/lifecycle); body sections: Summary / Design Sources / Comparison Scope / Gap List / Handover Recommendations	docs/calibration/architecture-compliance.md (default; if a snapshot is needed, create a separate -snapshot copy)
Gap entry	List item	type (boundary_violation / outdated_design / undocumented / partial_validation) / design_source / code_location / impact / fix (or recommended_action)	Report body "Gap List" section
Evidence readiness	Scalar	readiness（strong / moderate / weak）/ confidence / covered_scope / uncovered_scope	Report body "Comparison Scope" section
Machine-readable block	YAML fenced `yaml compliance_gaps:`	Each gaps[] item contains id/type/design_source/code_location/severity/fix_kind	At the end of the report body, for consumption by plan-next/auto-iterate

About this skill

Purpose

Core Objective

Scope Boundaries

Use Cases

Orchestration Guidance

Behavior (behavior)

Phase 0: Norms Resolution (new in v1.3)

Agent immediate contract

Interaction (interaction) policy

Phase 0: Resolve design sources and code scope

Phase 0.5: Evidence readiness assessment

Phase 1: Extract design decisions

Phase 2: Compare implementation

Phase 3: Generate Report

Phase 4: Persist Report

Input & Output

Input

Output

Architecture compliance report template

Limits

Hard Boundaries

Skill Boundaries (avoid overlap)

Self-Check

Core success criteria (all criteria must be met)

Acceptance Test

Examples (Examples)

Example 1: Boundary violation

Example 2: No design document

Example 3: Partial validation (weak readiness)

Example 4: Outdated design and recommended action

Appendix: Output Contract (Appendix: Output Contract)