architecture-scaffold

What this skill does

# Architecture Scaffold

Turn a high-level architecture spec into a compilable type skeleton, then prove it's sound with the compiler before anyone writes a line of logic.

## Why This Exists

Large refactors fail when agents jump straight to implementation. They lose the thread, make local decisions that contradict the global design, and you end up with a different mess than the one you started with. The "Human Builds the Shell" paradigm (Mengdi Chen, 2026) solves this by separating structure from logic:

1. **Types** are hard constraints — the compiler rejects violations at build time
2. **Tests** are behavioral verification — they confirm what the code does at runtime
3. **Specs** are soft guidance — they inform but can't enforce

This skill operates at layer 1. By the time you're done, every module, every function signature, every protocol/trait, and every type relationship exists as real code that the compiler has verified. No logic yet — just the architectural skeleton. An agent literally cannot hallucinate past a compiler error.

## The Three Phases

### Phase 1: Extract the Target Architecture
Read the spec. Produce a structured outline of every module, type, and signature.

### Phase 2: Build the Skeleton
Write real source files with real types and stub bodies. Compile layer by layer until it all passes.

### Phase 3: Map the Old Codebase
For each stub, determine whether existing logic can be ported or needs rewriting.

---

## Phase 1: Extract the Target Architecture

Read the assessment or design document the user provides. You're looking for:

- **Modules/components** — what are the new architectural units?
- **Responsibilities** — what does each unit own?
- **Types** — what data structures cross boundaries?
- **Dependencies** — which modules depend on which? What's the dependency direction?
- **Boundaries** — where are the hard seams? (FFI, network, persistence, framework edge)

Produce a **module map** — a structured outline that captures this. Don't write code yet. The module map is your intermediate representation between the prose spec and the code skeleton.

```markdown
# Module Map

## Layer 1: Domain Types (innermost — no dependencies on other project modules)

### module: domain
Location: core/capacitor-core/src/domain/
Responsibility: Shared value types, identities, and enums used across all modules
Types:
  - Project { id, name, path, ... }
  - RuntimeSnapshot { active_project, hooks, timestamp, ... }
  - HookEvent (enum: session_start, session_end, tool_use, ...)
Dependency rule: This module imports nothing from the project. Everything else may import this.

## Layer 2: Service Contracts (depend only on domain types)

### module: RuntimeEngine
Location: core/capacitor-core/src/runtime/
Responsibility: Core runtime lifecycle — start, stop, snapshot reads
Dependencies: domain (inward only)
Exposes:
  - RuntimeEngine (protocol/trait)
    - start(config: RuntimeConfig) -> Result<(), RuntimeError>
    - stop() -> Result<(), RuntimeError>
    - current_snapshot() -> RuntimeSnapshot
Types:
  - RuntimeConfig { storage_path, poll_interval, ... }
  - RuntimeError (enum: already_running, storage_unavailable, ...)

### module: SetupService
Location: core/capacitor-core/src/setup/
Responsibility: First-run and configuration workflows
Dependencies: domain (inward only)
Exposes:
  - SetupService (protocol/trait)
    - validate_setup() -> SetupStatus
    - perform_setup(config: SetupConfig) -> Result<(), SetupError>
...

## Layer 3: FFI Boundary (translates between layers)

### module: ffi
Location: core/capacitor-core/src/ffi/
Responsibility: Expose Rust services to Swift via C-compatible interface
Dependencies: Layer 2 services, domain types
Boundary types (must be repr(C) or serializable):
  - FFIRuntimeConfig, FFIRuntimeSnapshot, ...
Binding mechanism: [cbindgen / uniffi / manual C headers — match what the project uses]

## Layer 4: Swift Application Layer (outermost — depends on FFI)

### module: RuntimeSupervisor
Location: apps/swift/Sources/Capacitor/Services/RuntimeSupervisor.swift
...
```

### Dependency rules

The module map must declare explicit dependency rules per layer. These become enforceable constraints during verification:

```
Layer 1 (domain)     → imports nothing from the project
Layer 2 (services)   → imports only Layer 1
Layer 3 (FFI)        → imports Layers 1 and 2
Layer 4 (Swift app)  → imports only Layer 3's public interface
```

These rules are what prevent the architecture from drifting back to spaghetti. Write them down. They'll be verified mechanically in Phase 2.

### The level of detail matters

Each function signature should include parameter names, parameter types, and return types. If the assessment doesn't specify them, infer them from the described responsibilities and the existing codebase. Flag anything you're uncertain about — the user should confirm before you proceed to code.

### Handling ambiguity

The assessment will inevitably leave gaps. Common ones:

- **Error types** — the spec says "extract SetupService" but doesn't say what errors it can produce. Look at the existing code to see what errors the current implementation handles, and design the error enum from that.
- **Shared types** — two modules both need access to `Project`. Where does the type live? In the domain layer that both depend on (dependency points inward).
- **Boundary data** — what crosses the FFI or persistence boundary? These types need to be serializable. Flag them explicitly.

When in doubt, ask the user. A five-second clarification now prevents an hour of rework later.

### Leverage the assessment's existing references

If the assessment names specific files, functions, and line numbers (and a good one will), use those as anchors when inferring signatures. Don't search the codebase from scratch when the assessment already points you to `CoreRuntime.initialize()` in `lib.rs:276`. Read what's there and design the new signature from it.

### Present the module map for sign-off

Show the module map to the user before writing any code. They should confirm:
- The modules cover all the assessment's recommendations
- The dependency directions are correct
- The file/directory placement makes sense for the project
- Nothing critical is missing
- The granularity feels right (not too many tiny modules, not too few bloated ones)

---

## Phase 2: Build the Skeleton

Now you write real code. Every module, every type, every function signature — but no implementation logic. Bodies are stubs.

### Create a working branch

```
git checkout -b architecture-scaffold
```

### File placement

Where new files go matters — it determines the module graph. Follow these principles:

- **New modules get new files/directories**, not insertions into existing files. If you're splitting `CoreRuntime` into `RuntimeEngine` + `SetupService`, create `src/runtime/mod.rs` and `src/setup/mod.rs` — don't try to carve them out of `lib.rs` yet.
- **The module map's "Location" field is the source of truth.** You decided on placement in Phase 1; now execute it.
- **Old files stay untouched for now.** The skeleton lives alongside the existing code. Don't delete or modify old code — that's the migration phase's job.
- **Update module declarations** (Rust `mod` statements, Swift package targets) so the compiler sees the new files.

### Scaffold layer by layer

Don't write all the skeleton files at once and then compile. Build from the inside out, compiling at each layer. This keeps errors localized and prevents cascading failures.

**Step 1: Domain types (Layer 1)**
Write the shared types — structs, enums, type aliases. Compile.
These have no dependencies, so if they don't compile, it's a self-contained problem.

**Step 2: Service contracts (Layer 2)**
Write the protocols/traits and their associated types. Write stub implementations. Compile.
If this fails, it's either a bad import (trivial) or a type mismatch with the domain layer (architectural — see below).

**Step