| 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:
- Spine — How things compose, what orchestrates them, registry model
- Boundaries — External policies, validation baseline, failure modes
- 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
