Architecture Blueprint

Goal

Answer: What is this system, and what changed since I last looked? — without a graph DB, fifth surface, or topology quiz gate.

Repo detection (read first)

Continuum guard: If this is a Continuum repo, use X-3 and blueprint_append_agent / continuum-report — do not create parallel ARCHITECTURE.md unless the user explicitly asks for markdown-only dogfood.

When to use

• Multi-day agent-heavy work on one repo
• User can't explain module boundaries from memory
• Before/after large refactors or agent swarms
• User explicitly invokes this skill or asks for architecture tracking

Workflow (generic repos only)

Skip steps 2–3 in Continuum — append via X-3 instead.

1. Scan once — list top-level layers (≤6): shell, surfaces/modules, backend/crates, IPC/API, docs, automation. Cap 7 visible items per layer; summarize overflow as "+N more".
2. Write ARCHITECTURE.md — one-line project summary + layer sections with plain-language bullets (no jargon labels like "god mode").
3. Create ARCHITECTURE-CHANGES.md — append-only feed:

## 2026-07-06 — git — feat: add auth module
- Summary: Committed changes in Backend, Surfaces.
- Paths: src/auth.ts, crates/session/...

4. On task completion — append agent-sourced row (no commit required):

## 2026-07-06 — agent — IPC wiring for bookmarks
- Summary: Added bookmark IPC handlers and UI hooks.
- Paths: src-tauri/src/commands.rs, ...

5. Optional git hook — only if user asks; append commit rows with changed paths + first line of message.

Agent report contract

When closing a substantial task, emit one report block in the assistant message (user can copy to feed).

Continuum repos — prefer this block:

```continuum-report
architectureImpact:
  - src/surfaces/Build/BuildSurface.tsx
summary: Added file watcher debounce to indexer pipeline.
```

Generic repos — use this block:

```architecture-report
impact_paths:
  - src/surfaces/Build/BuildSurface.tsx
summary: Added file watcher debounce to indexer pipeline.
```

Append a matching row to ARCHITECTURE-CHANGES.md (or X-3 feed in Continuum) only when impact paths are non-empty.

Mental model sync (optional, ≤3 min)

Only when user asks. Pick 3 recent change rows, hide layer names, user guesses layer, reveal mapping. Never block further work on pass/fail.

Constraints

• Markdown first in generic repos — no default web UI, xyflow, or LSIF graph
• No numeric drift scores, leaderboards, or red "failed" gates in the feed
• No regex-parsing framework internals for discovery (use directory conventions)
• Do not edit the plan file if user attached an architecture plan
• Keep stable IDs/path globs when refreshing so change feed links stay valid

Adversarial self-check (before finishing)

• Did I detect repo type and pick X-3 vs markdown correctly?
• Could a tired builder get oriented in <60s from text feed alone?
• Every change row names ≥1 touched path?
• Did I avoid building Continuum IPC when markdown or X-3 already suffices?
• Layer count ≤7 per section?