modularize

name	modularize
description	Cache-aware task decomposition — split large coding tasks into independent modules, define interface contracts, schedule execution waves, and execute each module as an isolated Reasonix subagent. Invoke when user needs to break down a complex task, build a multi-module system, or wants structured contract-driven development.
argument-hint	<task description or command>
allowed-tools	["Read","Write","Bash","Glob","Grep","Edit","WebFetch"]

Split large coding tasks into independent modules executed as Reasonix subagents. All modules share a byte-stable SYSTEM prefix (prefix.md) so DeepSeek's prefix cache hits across subagent sessions.

Five phases: analyze → contracts → schedule → execute → integrate. On failure: only re-run the broken module + its downstream dependents.

Workflow files in `phases/`, templates in `templates/`, references in `reference/` — available if more detail is needed, but the core instructions are here.

Phase 1: Task Analysis → Module Decomposition

Trigger: natural language task description or /decompose

Step 1 — Scout existing context

• Read .reasonix/modules/prefix.md and .reasonix/modules/plan.json if they exist (resume or recursive split)
• Run ls -R src/ to see existing code

Step 2 — Propose module decomposition

Analyze the user's task and identify functional module boundaries.

Principles:

• Each module = one cohesive feature unit (e.g. "user auth", not "auth.ts file")
• Minimal inter-module dependencies
• Shared infrastructure (db, logging) splits first
• Mark oversized modules as recursive-splittable

Output format:

我分析了你的任务，建议拆成以下模块：

┌── database ──┐
│              ├──► auth ──┐
└──────────────┘           ├──► api ──► frontend
                           │
┌── storage ───────────────┘
└──────────────┘

| 模块 | 职责 | 依赖 | 复杂度 |
|------|------|------|--------|
| database | 数据库连接、查询封装 | 无 | medium |
| storage | 文件存储 | 无 | low |
| auth | 注册、登录、鉴权 | database | medium |
| api | REST 接口层 | auth, storage | high |
| frontend | 前端页面 | api | high |

确认？

Step 3 — Write plan.json on confirmation

Path: .reasonix/modules/plan.json

{
  "task_id": "<kebab-case>",
  "task_description": "<original task>",
  "modules": [
    { "name": "database", "depends_on": [], "complexity": "medium" },
    { "name": "auth", "depends_on": ["database"], "complexity": "medium" }
  ],
  "waves": [],
  "status": "analyzed",
  "created_at": "<ISO timestamp>"
}

If the user's description is too vague — ask clarifying questions. Do not guess.

Phase 2: Interface Contracts + Shared Prefix

Trigger: user says "OK" after Phase 1, or /contracts

Step 1 — Load templates

Read templates/contract.template.md and templates/prefix.template.md for the exact format.

Step 2 — Generate contracts per module

For each module (topological order — root dependencies first):

Generate contracts/<module>.md containing:

• Type definitions in ```typescript blocks — machine-parseable
• Interface signatures — export function signatures exactly as they'll appear in code
• Behavior descriptions — what each function does, inputs, outputs, errors, edge cases
• Upstream dependency interfaces — copy-pasted from upstream module contracts (not from memory)
• npm Dependencies — list every npm package this module needs. Prefer pure-JS packages (no native addons). If native is unavoidable, prefer sql.js over better-sqlite3. Node.js built-ins (fs, path, crypto) do NOT count as dependencies.

Show each contract to the user for review. Allow batch approval if user prefers.

Step 3 — Generate prefix.md

After all contracts are approved, generate prefix.md:

CRITICAL: prefix.md contains ONLY project overview + conventions. No module-specific content.

• Project description, tech stack, directory structure
• Coding conventions (indentation, naming, imports, error handling)
• Module list (just names + status, no contract details)
• NO timestamps, NO session IDs, NO dynamic content

Why: prefix.md is the byte-stable SYSTEM prompt shared across all subagent sessions. It must be identical everywhere. Module contracts go in USER messages.

Step 4 — Update plan.json

status → contracted

Phase 3: Dependency Graph → Wave Scheduling

Trigger: user says "OK" after Phase 2, or /schedule

Kahn algorithm:

1. Compute in-degree for each module (how many dependencies)
2. Modules with in-degree == 0 → Wave 0
3. Remove Wave 0 modules, decrement in-degrees of dependents
4. New in-degree == 0 → Wave 1
5. Repeat until all assigned
6. If modules remain → cycle detected → report error

Output:

执行计划（共 4 波）：

Wave 0 (可并行): database, storage
Wave 1: auth
Wave 2: api
Wave 3: frontend

确认？

On confirmation: write waves to plan.json, status → ready.

Pre-flight: Dependency Installation

Trigger: immediately after Phase 3 is confirmed, before Phase 4 starts. No user interaction required — this step is automatic.

Step 1 — Collect all dependencies

Read every contracts/<module>.md, extract the ## npm 依赖 section from each. Merge into a single dependency list (deduplicate, take highest version).

Step 2 — Install once

Run npm install <merged-packages> (or update package.json first, then npm install). This installs ALL module dependencies in ONE shot. Subagents will NOT run npm install themselves.

Step 3 — Verify

npm ls to confirm all packages are installed. If any native addon fails to compile → switch to pure-JS alternative and update the relevant contract.

Phase 4: Subagent Execution (CORE)

Trigger: user says "OK" after Phase 3, or /execute [module] or /execute-all

/execute-all — Auto wave execution

For each wave in order:
  For each module in wave:
    1. Check upstream deps are completed (outputs/<dep>/result.md exists)
    2. Generate subagent skill: .reasonix/modules/skills/modularize-<module>.md (see template below)
    3. Invoke run_skill modularize-<module>
    4. Subagent contract goes into SYSTEM prompt → first subagent caches it, rest hit cache
    5. Verify output: outputs/<module>/result.md exists + contract compliance
    6. Update plan.json module status
    7. Report progress

CRITICAL: Subagents must NOT run npm install. Dependencies already installed in Pre-flight. If a subagent needs a missing package, abort and report it — the contract must be updated.

/execute — Single module

Same flow. Check upstream deps first.

/revise — Recovery

1. Identify failed module
2. Check if contract or deps need fixing
3. If new deps needed → run Pre-flight again
4. Regenerate subagent skill, re-execute
5. Then /execute-all to pick up downstream

Subagent skill template

When generating .reasonix/modules/skills/modularize-<module>.md:

---
description: "Implement the <module> module for <task_id>. Only write code, do not run npm install."
runAs: subagent
---

# Implement <module>

## Contract (MUST follow exactly)
```typescript
<copy ONLY the interface signatures + type definitions from contracts/<module>.md>

Upstream Outputs

<for each upstream dep: copy its result.md "Interface Summary" section verbatim>

Hard Rules

1. Write ONLY the files listed in the contract
2. Use ONLY the upstream interfaces declared above — no private imports
3. NEVER run npm install — all deps already installed
4. NEVER run npm test — typecheck only: npx tsc --noEmit
5. After implementation: write outputs//result.md per templates/result.template.md
6. Write key decisions to project memory via /remember

### Progress reporting format

✅ auth 完成 — 接口全部符合契约 进度: Wave 1/3 — 2/5 模块 下一个: api 回复 OK 继续，或 /execute

## Phase 5: Integration Verification

**Trigger:** all modules completed, or `/integrate`

### Step 1 — Per-module contract verification
For each module, compare:
- `contracts/<module>.md` → what was promised
- `outputs/<module>/result.md` → what was delivered

Output mismatch report:

集成验证报告 ════════════════════ ✅ database — 全部匹配 ✅ storage — 全部匹配 ⚠️ auth — register 签名多了可选参数 name ✅ api — 全部匹配

结果: 4/5 通过，1 需修复 → /revise auth

### Step 2 — Upstream/downstream chain check
Verify that downstream module imports match upstream module exports.

### Step 3 — Finalize
All pass → `plan.json` status → `done`.
Partial failures → mark failed modules, prompt `/revise`.

## /status — Check progress
Read `plan.json`, display:
- Task name + status
- Per-module status (pending → in_progress → completed → failed)
- Current wave / total waves
- Suggested next action

</process>

<success_criteria>
- Task decomposed into functional modules with clear dependency graph
- All contracts defined with TypeScript signatures + behavior descriptions
- prefix.md is byte-stable (no timestamps, no dynamic content, no module details)
- Execution runs in waves via isolated subagents
- Cache hits sustained across subagent sessions (prefix.md unchanged)
- Integration verification passes all contracts
- On failure: only broken module + downstream re-run
</success_criteria>