arch-first

Arch-First Protocol

A meta-skill for executing architectural tasks — too big for a fast-track, too small for a full feature-execution. Use when:

• The task decomposes into 5+ blocks with dependencies
• Affects several layers (DB + code + skills + prompts + configs)
• Requires decisions on multiple forks (not just execution)
• May spawn a follow-up epic after closure
• Architectural cleanliness over distance is principally important

Input

A 5+ block feature task (typically routed from idea-first); optionally a Mode Brief path.

Output

research-doc.md with baseline assessment; block decomposition (5-15+ atomic blocks) inserted into task_blocks; per-block reports as blocks close.

Hands off to

Per-block flow-first cycle for each open block, then ship-first at task-level closure.

Principles

1. Decomposition by BLOCKS, not tasks

A large task = numbered blocks with an explicit goal each. Blocks live inside one task, in one task.md. An epic appears when a block is deferred or extracted.

Execution order != numbering order — reflects real dependencies.

2. Research BEFORE library-first

If the task has an unfamiliar component (new skill, new DB, unstudied table) — a separate research phase before planning.

Research outputs a comparison table "as is vs should be" with criticality (HIGH/MED/LOW) per item.

Without research → library-first builds on guesses → wrong scope estimates → missed deadlines.

3. Explicit pinning of architectural decisions

After each fork — pin the decision with rationale in task.md or a dedicated decision-NN.md.

Structure:

### Decision N — Brief statement

We choose **X** (not Y, not Z).

**Rationale:**
1. Specific reason 1 (with example)
2. Specific reason 2

**Alternatives:**
- Y — rejected (why)
- Z — rejected (why)

**What changes:** [specific file-level deltas]

Without explicit pinning → two weeks later the developer re-opens the discussion or makes the wrong choice.