split-architecture

Split Architecture Skill

Converts a single-file architecture document ({{specs_dir}}/architecture.md) into a directory-based format ({{specs_dir}}/architecture/) for better organization and targeted context loading.

When to Use

• Automatically by design-architecture and source-architecture-from-code when the single-file architecture doc crosses 500 lines or 10 decision records (sections matching ### DR-\d+)
• Manually when the user invokes /split-architecture

Step 0: Resolve Project Context

1. Monorepo check: Does .groundwork.yml exist at the repo root?
   • If yes → Is {{project_name}} non-empty?
     • If empty → Invoke Skill(skill="groundwork:select-project") to select a project, then restart this skill.
     • If set → Project is {{project_name}}, specs at {{specs_dir}}/.
   • If no → Continue (single-project repo).
2. Proceed with the resolved project context.

Step 1: Validate Preconditions

1. Check single file exists: {{specs_dir}}/architecture.md must exist
   • If missing → output "No single-file architecture doc found at {{specs_dir}}/architecture.md. Nothing to split." and stop.
2. Check directory does NOT exist: {{specs_dir}}/architecture/ must not already exist
   • If it exists → output "Architecture doc is already in directory format at {{specs_dir}}/architecture/. Nothing to do." and stop.
3. Read the file and count lines and decision records (sections matching ^### DR-\d+).

Step 2: Split the File

Parse the single-file architecture doc into sections and write each to its own file under {{specs_dir}}/architecture/.

Directory Structure

{{specs_dir}}/architecture/
├── _index.md                 # Header, metadata
├── 01-executive-summary.md   # Section 1: Executive Summary
├── 02-architectural-drivers.md # Section 2: Architectural Drivers
├── 03-system-overview.md     # Section 3: System Overview
├── 04-components/            # Section 4: One file per component
│   ├── _index.md             # Section 4 header ("## 4) Component Details")
│   └── <component-slug>.md   # e.g., cli.md, query-router.md
├── 05-data.md                # Section 5: Data Architecture
├── 06-integration.md         # Section 6: Integration Architecture
├── 07-security.md            # Section 7: Security Architecture
├── 08-infrastructure.md      # Section 8: Infrastructure & Deployment
├── 09-observability.md       # Section 9: Observability
├── 10-cost-model.md          # Section 10: Cost Model
├── 11-decisions/             # Section 11: One file per DR
│   ├── _index.md             # Section 11 header ("## 11) Decision Records")
│   └── DR-NNN.md             # e.g., DR-001.md, DR-015.md
├── 12-open-questions.md      # Section 12: Open Questions & Risks
└── 13-appendices.md          # Section 13: Appendices