Back to Details

architecture-scaffold

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
当Agent直接跳转到实现阶段时，大型重构往往会失败。它们会偏离核心目标，做出与全局设计相悖的局部决策，最终导致新的混乱局面。“人工构建外壳”范式（Mengdi Chen，2026）通过将结构与逻辑分离解决了这一问题：
  1. 类型是硬约束——编译器会在构建阶段拒绝违反约束的代码
  2. 测试是行为验证——在运行时确认代码的实际功能
  3. 规范是软性指导——仅提供参考但无法强制执行
本技能作用于第一层。完成后，每个模块、每个函数签名、每个protocol/trait以及每种类型关系都会以编译器已验证的真实代码形式存在。此时还没有业务逻辑，只有架构骨架。Agent根本无法绕过编译器错误生成幻觉代码。

The Three Phases

三个阶段

Phase 1: Extract the Target Architecture

阶段1：提取目标架构

Read the spec. Produce a structured outline of every module, type, and signature.
阅读架构规范，生成包含所有模块、类型和签名的结构化大纲。

Phase 2: Build the Skeleton

阶段2：构建骨架

Write real source files with real types and stub bodies. Compile layer by layer until it all passes.
编写包含真实类型和存根主体的源代码文件，逐层编译直至全部通过。

Phase 3: Map the Old Codebase

阶段3：映射旧代码库

For each stub, determine whether existing logic can be ported or needs rewriting.
针对每个存根，确定现有逻辑是否可以移植或需要重写。

Phase 1: Extract the Target Architecture

阶段1：提取目标架构

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
undefined
阅读用户提供的评估报告或设计文档，你需要从中提取以下信息：
  • 模块/组件——新的架构单元有哪些？
  • 职责——每个单元负责什么？
  • 类型——哪些数据结构会跨边界传递？
  • 依赖关系——哪些模块依赖于其他模块？依赖方向是什么？
  • 边界——硬边界在哪里？（FFI、网络、持久化、框架边缘）
生成一份模块映射图——捕获上述信息的结构化大纲。此时不要编写代码，模块映射图是 prose 规范与代码骨架之间的中间表示。
markdown
undefined

Module Map

Module Map

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

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

module: domain

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.
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)

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

module: RuntimeEngine

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, ...)
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

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> ...
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)

Layer 3: FFI Boundary (translates between layers)

module: ffi

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]
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)

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

module: RuntimeSupervisor

module: RuntimeSupervisor

Location: apps/swift/Sources/Capacitor/Services/RuntimeSupervisor.swift ...
undefined
Location: apps/swift/Sources/Capacitor/Services/RuntimeSupervisor.swift ...
undefined

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.
模块映射图必须为每个层级声明明确的依赖规则，这些规则将在验证阶段成为可强制执行的约束：
Layer 1 (domain)     → 不导入项目内任何模块
Layer 2 (services)   → 仅导入Layer 1
Layer 3 (FFI)        → 导入Layer 1和Layer 2
Layer 4 (Swift app)  → 仅导入Layer 3的公共接口
这些规则是防止架构退化为 spaghetti 代码的关键。请将它们记录下来，在阶段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.
评估报告难免存在遗漏，常见的歧义包括：
  • 错误类型——规范提到“提取SetupService”但未说明它可能产生哪些错误。查看现有代码，了解当前实现处理的错误类型，并据此设计错误枚举。
  • 共享类型——两个模块都需要访问
    Project
    类型。该类型应放在两个模块都依赖的领域层（依赖指向内部）。
  • 边界数据——哪些数据会跨越FFI或持久化边界？这些类型需要可序列化，请明确标记它们。
如有疑问，请询问用户。现在花五秒澄清问题，能避免后续一小时的返工。

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.
如果评估报告指定了具体的文件、函数和行号（优秀的评估报告会这样做），请将这些作为推断签名的锚点。当评估报告已经指向
lib.rs:276
中的
CoreRuntime.initialize()
时，无需从头搜索代码库。查看该函数并据此设计新的签名。

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

阶段2：构建骨架

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
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.
新文件的位置很重要——它决定了模块图。请遵循以下原则：
  • 新模块对应新文件/目录，不要插入到现有文件中。如果你要将
    CoreRuntime
    拆分为
    RuntimeEngine
    + 
    SetupService
    ，请创建
    src/runtime/mod.rs
    和
    src/setup/mod.rs
    ——不要尝试从
    lib.rs
    中拆分它们。
  • 模块映射图中的“Location”字段是唯一依据。你在阶段1中已经确定了放置位置，现在只需执行即可。
  • 暂时保留旧文件。骨架与现有代码共存。不要删除或修改旧代码——这是迁移阶段的工作。
  • 更新模块声明（Rust的
    mod
    语句、Swift包目标），让编译器能识别新文件。

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 3: FFI boundary (Layer 3) Write the FFI types and the translation layer between Rust services and Swift. This layer must use whatever binding mechanism the project already uses (cbindgen, uniffi, manual C headers, etc.). Compile both sides — Rust and Swift — and verify the generated bindings match.
Step 4: Swift application layer (Layer 4) Write the Swift protocols, stub implementations, and any SwiftUI-facing types. Compile.
不要一次性编写所有骨架文件再编译，从内到外逐层构建，每完成一层就编译一次。这样可以将错误本地化，避免连锁失败。
步骤1：领域类型（Layer 1） 编写共享类型——结构体、枚举、类型别名。编译。 这些类型没有依赖，因此如果编译失败，问题是自包含的。
步骤2：服务契约（Layer 2） 编写protocols/traits及其关联类型，编写存根实现。编译。 如果失败，要么是导入错误（小问题），要么是与领域层的类型不匹配（架构问题——见下文）。
步骤3：FFI边界（Layer 3） 编写FFI类型以及Rust服务与Swift之间的转换层。该层必须使用项目已有的绑定机制（cbindgen、uniffi、手动C头文件等）。编译双方代码——Rust和Swift，并验证生成的绑定是否匹配。
步骤4：Swift应用层（Layer 4） 编写Swift协议、存根实现以及任何面向SwiftUI的类型。编译。

Language-specific patterns

语言特定模式

See 
references/language-patterns.md
for full examples in Swift, Rust, and TypeScript. The key pattern is the same everywhere: define the contract (protocol/trait/interface), define all types with all fields, and provide a stub implementation that compiles but panics if called (
fatalError
in Swift, 
todo!()
in Rust, 
throw new Error
in TypeScript).
请查看
references/language-patterns.md
获取Swift、Rust和TypeScript的完整示例。核心模式在所有语言中都是相同的：定义契约（protocol/trait/interface），定义包含所有字段/变体的类型，并提供可编译但调用时会报错的存根实现（Swift中用
fatalError
，Rust中用
todo!()
，TypeScript中用
throw new Error
）。

What goes in the skeleton

骨架包含的内容

Include:
  • All protocols/traits with full method signatures
  • All structs, enums, and type aliases with all fields/variants
  • Stub implementations of every protocol/trait (so the compiler can verify conformance)
  • Module declarations and import/export structure
  • Public API surface for each module
  • FFI boundary types AND the binding layer (headers, uniffi definitions, etc.)
Exclude:
  • Any actual business logic
  • Test files (those come later, during the migration phase)
  • Configuration files, build scripts, CI — unless the new architecture requires structural changes to these
包含：
  • 所有带有完整方法签名的protocols/traits
  • 所有包含字段/变体的结构体、枚举和类型别名
  • 每个protocol/trait的存根实现（以便编译器验证一致性）
  • 模块声明和导入/导出结构
  • 每个模块的公共API表面
  • FFI边界类型以及绑定层（头文件、uniffi定义等）
不包含：
  • 任何实际业务逻辑
  • 测试文件（这些会在迁移阶段添加）
  • 配置文件、构建脚本、CI——除非新架构需要对这些进行结构性更改

Responding to compiler errors

处理编译器错误

Not all compiler errors are equal. Distinguish between two kinds:
Incidental errors — typos, missing imports, forgotten visibility modifiers, a type name that doesn't match between declaration and use. Fix these immediately and recompile. They're noise.
Architectural signals — these mean the module map is wrong:
  • Circular dependency between modules → the module boundaries are drawn wrong. Stop. Go back to the module map. Restructure until the dependency graph is a DAG.
  • Type mismatch at a boundary → the two sides of a seam disagree on what data crosses it. This is a design flaw, not a code flaw. Resolve which side is right, update the module map, then fix the code.
  • A protocol/trait that can't be implemented without reaching into another module's internals → the abstraction boundary is in the wrong place. The responsibility probably needs to move.
When you hit an architectural signal: stop compiling, update the module map, get user sign-off if the change is significant, then resume. Don't patch around the problem to make the compiler happy — that's how the mess started.
并非所有编译器错误都相同，请区分两种类型：
偶然错误——拼写错误、缺失导入、遗忘可见性修饰符、声明与使用的类型名称不匹配。立即修复这些错误并重新编译，它们只是噪音。
架构信号——这些错误意味着模块映射图存在问题：
  • 模块间循环依赖——模块边界划分错误。停止操作，返回模块映射图，重新调整结构直到依赖图为DAG。
  • 边界类型不匹配——边界两侧对传递的数据类型存在分歧。这是设计缺陷，而非代码缺陷。确定哪一侧是正确的，更新模块映射图，然后修复代码。
  • protocol/trait无法在不访问其他模块内部的情况下实现——抽象边界位置错误，职责可能需要转移。
遇到架构信号时：停止编译，更新模块映射图，如果更改重大需获得用户确认，然后继续。不要为了让编译器通过而修补问题——这正是混乱的根源。

Verifying dependency direction

验证依赖方向

After the skeleton compiles, verify that the declared dependency rules hold. For each layer:
Rust: Grep 
use
statements in each module directory. Every 
use crate::...
path should only reference modules in the same or lower layers.
bash
undefined
骨架编译通过后，验证声明的依赖规则是否成立。针对每个层级：
Rust： 在每个模块目录中搜索
use
语句。每个
use crate::...
路径应仅引用同一层级或更低层级的模块。
bash
undefined

Example: verify Layer 2 modules only import from Layer 1

示例：验证Layer 2模块仅导入Layer 1

grep -rn "use crate::" core/capacitor-core/src/runtime/ | grep -v "domain"
grep -rn "use crate::" core/capacitor-core/src/runtime/ | grep -v "domain"

Should return nothing — any hit is a dependency violation

应无输出——任何结果都是依赖违规


**Swift:** Check import statements. Swift modules should only reference their declared dependencies.

If violations are found, they're architectural flaws. Fix the module map, not the imports.

**Swift：** 检查导入语句。Swift模块应仅引用其声明的依赖项。

如果发现违规，说明存在架构缺陷。修复模块映射图，而非修改导入语句。

Soundness criteria

合理性标准

The skeleton is "sound" when:
  • The build passes with zero errors at every layer
  • Every module's public API is fully typed
  • Every protocol/trait has at least one stub implementation
  • Dependency direction has been mechanically verified (grep check above)
  • FFI boundary types are defined on both sides and the binding layer compiles
Record the verification result:
markdown
undefined
当满足以下条件时，骨架是“合理的”：
  • 每个层级的构建都零错误通过
  • 每个模块的公共API都完全类型化
  • 每个protocol/trait至少有一个存根实现
  • 依赖方向已通过机械验证（上述grep检查）
  • FFI边界类型在两侧都已定义，且绑定层编译通过
记录验证结果：
markdown
undefined

Skeleton Verification

Skeleton Verification

  • Rust (cargo check): PASS
  • Swift (swift build): PASS
  • FFI bindings: PASS (generated headers match Swift imports)
  • Dependency direction: PASS (no violations found)
  • Module count: 8 (4 Rust, 4 Swift)
  • Protocol/trait count: 6
  • Stub implementation count: 6
  • FFI boundary types: 12 shared types verified

---
  • Rust (cargo check): PASS
  • Swift (swift build): PASS
  • FFI bindings: PASS (generated headers match Swift imports)
  • Dependency direction: PASS (no violations found)
  • Module count: 8 (4 Rust, 4 Swift)
  • Protocol/trait count: 6
  • Stub implementation count: 6
  • FFI boundary types: 12 shared types verified

---

Phase 3: Map the Old Codebase

阶段3：映射旧代码库

With a proven skeleton in hand, you now go back to the existing code and create a precise mapping: for each stub in the new architecture, where does the logic come from?
有了已验证的骨架后，现在返回现有代码库，创建精确映射：针对新架构中的每个存根，逻辑来自哪里？

Start from the assessment's references

从评估报告的引用开始

If the assessment names specific files, functions, and line numbers — use them. Don't re-search the codebase for things the assessment already located. For example, if the assessment says 
CoreRuntime.initialize()
in 
lib.rs:276-340
handles startup, that's your anchor for mapping 
RuntimeEngine.start()
.
For stubs where the assessment doesn't point to specific code, then search the existing codebase by responsibility.
如果评估报告指定了具体的文件、函数和行号——请使用这些信息。无需重新搜索代码库寻找评估报告已定位的内容。例如，如果评估报告指出
core/capacitor-core/src/lib.rs:276-340
中的
CoreRuntime.initialize()
处理启动逻辑，那这就是映射
RuntimeEngine.start()
的锚点。
对于评估报告未指向具体代码的存根，则按职责搜索现有代码库。

The migration manifest

迁移清单

Create 
migration-manifest.md
in the project root:
markdown
undefined
在项目根目录创建
migration-manifest.md
：
markdown
undefined

Migration Manifest

Migration Manifest

Source assessment: [path to assessment] Skeleton branch: architecture-scaffold Generated: [date]
Source assessment: [path to assessment] Skeleton branch: architecture-scaffold Generated: [date]

RuntimeEngineImpl

RuntimeEngineImpl

start(config:)

start(config:)

  • Source: 
    CoreRuntime.initialize()
    in 
    core/capacitor-core/src/lib.rs:276-340
  • Action: PORT
  • Confidence: HIGH
  • Notes: Currently also does setup validation; that moves to SetupService. Signature change: takes RuntimeConfig instead of raw path + options.
  • Source: 
    CoreRuntime.initialize()
    in 
    core/capacitor-core/src/lib.rs:276-340
  • Action: PORT
  • Confidence: HIGH
  • Notes: Currently also does setup validation; that moves to SetupService. Signature change: takes RuntimeConfig instead of raw path + options.

stop()

stop()

  • Source: 
    CoreRuntime.shutdown()
    in 
    core/capacitor-core/src/lib.rs:342-380
  • Action: PORT
  • Confidence: HIGH
  • Notes: Straightforward extraction, no entangled dependencies.
  • Source: 
    CoreRuntime.shutdown()
    in 
    core/capacitor-core/src/lib.rs:342-380
  • Action: PORT
  • Confidence: HIGH
  • Notes: Straightforward extraction, no entangled dependencies.

currentSnapshot()

currentSnapshot()

  • Source: 
    CoreRuntime.get_snapshot()
    in 
    core/capacitor-core/src/lib.rs:382-395
  • Action: ADAPT
  • Confidence: HIGH
  • Notes: Remove the global state bypass that check_hook_health uses. The function is simple, but it currently reads from a global rather than the instance's storage — that's the adaptation.
  • Source: 
    CoreRuntime.get_snapshot()
    in 
    core/capacitor-core/src/lib.rs:382-395
  • Action: ADAPT
  • Confidence: HIGH
  • Notes: Remove the global state bypass that check_hook_health uses. The function is simple, but it currently reads from a global rather than the instance's storage — that's the adaptation.

SetupServiceImpl

SetupServiceImpl

performSetup(config:)

performSetup(config:)

  • Source: 
    CoreRuntime.run_setup()
    + 
    CoreRuntime.validate_config()
  • Action: REWRITE
  • Confidence: MEDIUM
  • Notes: Logic is scattered across the god object and interleaved with runtime concerns. Gather requirements from both sources but write fresh. Pay attention to the error handling in validate_config — it has edge cases the rewrite needs to preserve.
undefined
  • Source: 
    CoreRuntime.run_setup()
    + 
    CoreRuntime.validate_config()
  • Action: REWRITE
  • Confidence: MEDIUM
  • Notes: Logic is scattered across the god object and interleaved with runtime concerns. Gather requirements from both sources but write fresh. Pay attention to the error handling in validate_config — it has edge cases the rewrite needs to preserve.
undefined

Action categories

操作类别

For each stub, assign exactly one action:
  • PORT — The existing logic does what the new signature needs. Extract it, adapt the signature, move it. The logic itself is sound.
  • ADAPT — The existing logic is mostly right but needs non-trivial changes to fit the new architecture (e.g., removing a dependency on global state, splitting a function that does two things).
  • REWRITE — The existing logic is too entangled, too different in shape, or simply wrong. Write fresh logic guided by the old code as reference, not as source material.
  • NEW — No existing logic covers this. It's a new capability the old architecture didn't have.
  • DELETE — This existed in the old code but has no place in the new architecture. Confirm with the user that it's truly dead.
为每个存根分配恰好一个操作：
  • PORT——现有逻辑符合新签名的需求。提取、调整签名并迁移。逻辑本身是合理的。
  • ADAPT——现有逻辑基本正确，但需要进行非 trivial 更改以适应新架构（例如，移除对全局状态的依赖、拆分执行两个任务的函数）。
  • REWRITE——现有逻辑过于纠缠、形状差异过大或完全错误。以旧代码为参考编写新逻辑，而非直接使用旧代码。
  • NEW——现有逻辑未覆盖此部分。这是旧架构不具备的新功能。
  • DELETE——此部分存在于旧代码中，但在新架构中没有位置。请与用户确认它确实已废弃。

Confidence levels

置信度等级

Rate your confidence in each mapping: HIGH, MEDIUM, or LOW.
  • HIGH — The source location is clear, the logic is self-contained, the action is straightforward.
  • MEDIUM — The source is identifiable but the logic has dependencies or side effects that need careful handling.
  • LOW — You're not sure this is the right source, or the logic is so entangled that the action classification might be wrong.
LOW-confidence mappings should be flagged for the user to review. They're the ones most likely to cause problems during migration.
为每个映射评估置信度：HIGH、MEDIUM或LOW。
  • HIGH——源位置明确，逻辑自包含，操作简单直接。
  • MEDIUM——源可识别，但逻辑存在依赖或副作用，需要谨慎处理。
  • LOW——不确定这是否是正确的源，或者逻辑过于纠缠，操作分类可能有误。
低置信度的映射应标记出来供用户审核，这些是迁移过程中最可能出现问题的部分。

Present the manifest for review

提交清单供审核

Show the migration manifest to the user. Key things they should check:
  • Are the PORT vs REWRITE judgments correct? (Users often know which parts of their codebase are trustworthy)
  • Do the LOW-confidence mappings need investigation?
  • Is anything missing from the mapping?
  • Are the "DELETE" items truly dead?
向用户展示迁移清单。用户应重点检查以下内容：
  • PORT与REWRITE的判断是否正确？（用户通常知道代码库中哪些部分是可靠的）
  • 低置信度映射是否需要进一步调查？
  • 映射中是否遗漏了内容？
  • “DELETE”项是否确实已废弃？

Output

输出结果

When complete, the user has:
  1. A compilable type skeleton on a branch — the target architecture as verified code
  2. A module map — human-readable description of the architecture with dependency rules
  3. A migration manifest — precise mapping from old code to new stubs with actions and confidence levels
  4. Compiler + dependency verification — mechanical proof that the types fit together and dependencies flow correctly
These artifacts are the input to the next phase: actual implementation, either via the 
architectural-refactor
skill or manual development. The skeleton branch becomes the target that all implementation work builds toward, and the migration manifest tells the agents exactly where to find the logic they need.
完成后，用户将获得：
  1. 分支上的可编译类型骨架——作为已验证代码的目标架构
  2. 模块映射图——带有依赖规则的架构可读描述
  3. 迁移清单——旧代码到新存根的精确映射，包含操作和置信度等级
  4. 编译器+依赖验证——类型匹配且依赖流向正确的机械证明
这些工件是下一阶段的输入：实际实现，可通过
architectural-refactor
技能或手动开发完成。骨架分支成为所有实现工作的目标，迁移清单告诉Agent确切的逻辑来源。

Bridging to the 
architectural-refactor
skill

与
architectural-refactor
技能衔接

If the user plans to use the 
architectural-refactor
skill for execution, the migration manifest needs to be converted into that skill's format. Each stub mapping becomes a chunk in the refactor plan:
  • PORT stubs become "extract and move" chunks (low risk, do these first)
  • ADAPT stubs become "extract, modify, and move" chunks (medium risk)
  • REWRITE stubs become "write new implementation" chunks (highest risk, do these last)
  • DELETE items become cleanup chunks at the end
  • NEW items become implementation chunks after the ports are done
Group related stubs into single chunks (e.g., all PORT stubs for one module = one chunk). Order by risk: PORT first, ADAPT second, REWRITE third. Each chunk's exit criteria should include the same compilation check used in Phase 2 — if the skeleton still compiles after filling in real logic, the architecture hasn't drifted.
如果用户计划使用
architectural-refactor
技能执行迁移，需要将迁移清单转换为该技能的格式。每个存根映射成为重构计划中的一个chunk：
  • PORT存根成为“提取并迁移”chunk（低风险，优先处理）
  • ADAPT存根成为“提取、修改并迁移”chunk（中等风险）
  • REWRITE存根成为“编写新实现”chunk（最高风险，最后处理）
  • DELETE项成为最后的清理chunk
  • NEW项成为完成PORT后的实现chunk
将相关存根分组为单个chunk（例如，一个模块的所有PORT存根=一个chunk）。按风险排序：PORT优先，ADAPT次之，REWRITE最后。每个chunk的退出标准应包含阶段2中使用的相同编译检查——如果填充真实逻辑后骨架仍能编译通过，说明架构未偏离。

Guiding Principles

指导原则

  • The compiler is the authority, not the agent. If the agent says the architecture is sound but the compiler disagrees, the compiler wins. Always.
  • Types before logic. Resist the urge to "just implement this one function real quick." The entire point is to validate structure independently of behavior.
  • Architectural errors are not compiler errors. When the compiler reveals a structural problem (circular dep, boundary mismatch), go back to the module map. Don't patch the code to silence the compiler.
  • Precision over speed. A vague migration manifest ("logic is somewhere in lib.rs") is worse than useless — it gives agents permission to guess. Be specific.
  • Ask early, ask often. Every ambiguity resolved before code is written saves an order of magnitude of rework later. When the spec is unclear, stop and ask.
  • One direction through the pipeline. Don't jump back to skeleton-writing while you're mapping. If the mapping reveals a skeleton flaw, go back to Phase 2 explicitly, fix the skeleton, recompile, then resume mapping.
  • 编译器是权威，而非Agent。如果Agent称架构合理但编译器不同意，以编译器为准。永远如此。
  • 先类型后逻辑。抵制“快速实现这个函数”的冲动。核心目标是独立于行为验证结构。
  • 架构错误不是编译器错误。当编译器揭示结构问题（循环依赖、边界不匹配）时，返回模块映射图。不要修补代码以掩盖编译器错误。
  • 精确优先于速度。模糊的迁移清单（“逻辑在lib.rs的某个地方”）比无用更糟——它允许Agent猜测。请务必具体。
  • 尽早询问，经常询问。编写代码前解决的每个歧义都能节省十倍的后续返工时间。当规范不明确时，停止操作并询问。
  • 按流程单向推进。不要在映射阶段跳回骨架编写。如果映射发现骨架存在缺陷，请明确返回阶段2，修复骨架，重新编译，然后继续映射。