architecture

name

architecture

description

This skill should be used when the user asks about "target architecture", "greenfield spec", "pure SPEC", "decision packet", "migration slice", "architecture decision", "spike to spec", "current vs target", "hybrid to target", "indirection audit", "dependency ordering", "cutover validation", "no legacy left", "legacy cutover", or needs guidance on defining target architecture, creating specs from exploration, resolving architectural ambiguity, planning migrations from current to target state, or validating cutover plans.

For humans: Covers the 'before decomposition' phase — turning exploration into clean architecture specs. Teaches your agent to separate current state, target state, and transition concerns. Most useful for refactors and migrations. See the glossary for terms like 'decision packet' and 'migration slice'.

Architecture Methodology

This skill provides domain knowledge for architecture definition, decision-making, and migration planning. It covers how to turn exploration into durable specifications, how to resolve architectural ambiguity, and how to plan realistic paths from current state to target state.

When to use this skill

• Defining a target architecture from exploration or spikes
• Resolving architectural ambiguity through structured decision-making
• Planning migrations from current/hybrid state to target state
• Creating or updating architecture specs
• Managing the separation of current, target, and transitional concerns
• Validating that a cutover milestone will reach target state with no legacy left

Core concepts

Separation of concerns

Architecture work requires keeping three concerns distinct:

Concern	Purpose	Artifact
Current state	What exists today, why it exists, where it diverges from target	Audit doc
Target state	Greenfield contract language, accepted decisions only	Pure SPEC
Transition	How to get from current to target, bridges, phases	Migration slices

Mixing these causes thrash. Keep them separated and linked.

Dependency ordering

Resolve decisions in dependency order to avoid downstream rework:

1. Spine — How things compose, what orchestrates them, registry model
2. Boundaries — External policies, validation baseline, failure modes
3. Domain — Semantic content, canonical representations, extension rules

Spine decisions affect everything downstream. Resolve them first.

Decision packets

Architectural ambiguity becomes explicit through decision packets—structured documents that:

• Make "this-or-this" uncertainty visible
• Gather minimum necessary context
• Present options with a proposed default
• Drive accept/reject outcomes

See references/decision-packets.md for structure and patterns.

Migration slices

Accepted decisions become executable through migration slices—phased plans that:

• Map current divergence to target change
• Break work into prepare → cutover → cleanup phases
• Ensure every bridge has a deletion target

See references/migration-slices.md for structure and patterns.

Cutover validation

Before starting a legacy cutover milestone, validate that the plan actually reaches target:

• Stress-test against the SPEC and "no legacy left" requirement
• Identify hidden dependencies and estimate gaps
• Surface legacy that would remain if executed as written
• Consolidate findings before implementation begins

See references/cutover-validation.md for the full workflow.

Reference map

Reference	Path	Purpose
Spike to Spec	references/spike-to-spec.md	Workflow for turning exploration into pure specs
Decision Packets	references/decision-packets.md	How to structure and resolve architectural decisions
Migration Slices	references/migration-slices.md	How to plan phased migrations from current to target
Cutover Validation	references/cutover-validation.md	Validate a cutover milestone reaches target with no legacy left

Assets map

Asset	Path	Purpose
Decision Packet	assets/decision-packet.md	Template for individual decisions
Migration Slice	assets/migration-slice.md	Template for phased migration plans

Core invariants

Keep current, target, and transition separated; link them instead of duplicating. Resolve spine decisions first to avoid downstream thrash. "This-or-this" ambiguities must be explicitly decided, not left implicit. Prefer tables and matrices over complex diagrams; all diagrams must render. Every non-obvious claim needs a pointer (code/doc/issue). Every bridge or shim must have an explicit deletion target.

Anti-patterns to avoid

• Hybrid soup: Mixing current, target, and transitional concerns in one doc
• Decision drift: Resolving decisions out of dependency order
• Implicit ambiguity: Leaving "this-or-this" questions unresolved
• Orphan decisions: Accepted decisions that never update the spec
• Forever transitional: Bridges without sunset triggers or cleanup phases
• Context-free decisions: Decision packets without pointers to code, docs, or prior art
• Unvalidated cutover: Starting a legacy cutover milestone without stress-testing it against the SPEC

Grounding in target repo

• Look for existing SPIKE docs (often in docs/projects/ or docs/system/)
• Check for existing SPEC docs that should be updated rather than duplicated
• Identify the canonical location for architecture decisions (may have ADR conventions)
• Confirm doc ownership before creating new files