Architecture snapshots

The architecture-snapshot automation is one of the more invisible pieces of the discipline stack: it runs at session start, produces a structural picture of your repo, diffs it against the prior baseline, and quietly hands the result to the agent so the agent starts the conversation with a current map of what’s been deployed and what changed since last session.

You don’t directly interact with it. The load-bearing dependency is the tapestry-patterns plugin (which holds the canonical snapshot scripts the SessionStart hook runs) plus the output directory under docs/architecture-snapshots/. If the plugin isn’t installed, the agent loses its architecture awareness at session start.

What the diff is for

The diff isn’t an infrastructure-change report for its own sake. Architecture analysis is one of the reinforcement mechanisms Tapestry uses to maintain coordination quality — alongside OTel telemetry (services emit OpenTelemetry → Grafana Cloud), memory, friction analysis, and the rest. The diff’s purpose is to surface structural changes that affect coordination — interfaces appearing or disappearing, memory attachment points moving, coordination pathways relocating, friction-prone shapes emerging.

When you read a snapshot diff, the questions to ask are coordination-shaped, not service-shaped:

• What interfaces appeared in this diff? (A new service usually means a new coordination surface the operator and agent will need to learn.)
• What interfaces disappeared? (A removed service usually means a coordination surface the operator was depending on is gone.)
• What interfaces moved? (Code moving between packages often means a coordination surface relocated — agent’s mental model may now be wrong.)
• What interfaces split or merged? (A package becoming two packages, or two becoming one, almost always reshapes which agent coordinates with which.)
• What memory attachment points changed? (Memory tagged to a path that no longer exists loses discoverability — the coordination that memory was supporting becomes orphaned.)
• What friction patterns became visible? (Some kinds of drift only show up structurally — a duplicate showing up in two places is a friction signal even before the operator notices it.)
• What coordination pathways changed? (Bridge endpoints, MCP servers, webhooks — these are coordination surfaces, and the diff is where their movement is detected.)

The architecture-analyst narrative (<timestamp>-narrative.md) reads the diff and answers these questions in prose. The diff is raw evidence; the narrative is the coordination-shaped interpretation.

What it produces

Every time you start a Claude Code session in a properly-wired project, the SessionStart hook runs the snapshot pipeline. It produces five files under docs/architecture-snapshots/:

File	What’s in it
<timestamp>-snapshot.json	Machine-readable structural snapshot — deployed services, dependencies, MCP servers, env-var keys, runtime configs.
<timestamp>-snapshot.md	Human-readable version of the same snapshot, with an embedded mermaid diagram of the system.
<timestamp>-diff.json	Machine-readable diff against the prior snapshot.
<timestamp>-diff.md	Human-readable diff. **No structural changes detected** when nothing’s changed; otherwise a list of what was added/removed/modified.
<timestamp>-narrative.md	(Sometimes) prose narrative from the architecture-analyst agent explaining what changed and why it matters.

The snapshot pipeline is deterministic and shape-agnostic — it auto-detects whether your repo is a monolith, a monorepo, a multi-service backend, a frontend-only site, or some hybrid, and produces a snapshot appropriate to whichever shape it finds. You don’t configure it; it figures itself out.

Where the work actually happens

The SessionStart hook runs the canonical snapshot scripts straight from the tapestry-patterns plugin — it resolves them in the plugin (cache, sibling checkout, or monorepo) and runs them with your repo root passed as --repo-root. It does not run a per-repo script. The canonical bodies live at:

~/.claude/plugins/cache/tapestry/tapestry-patterns/<version>/scripts/architecture_snapshot.py
~/.claude/plugins/cache/tapestry/tapestry-patterns/<version>/scripts/architecture_diff.py

This is the Pillar 1 discipline (ONE pattern, ONE home): every project shares the same canonical implementation, so when it evolves, every project gets the improvement on next plugin update. A repo may also keep thin scripts/architecture_*.py wrappers for manual or CI runs, but the SessionStart hook does not need or use them — installing tapestry-patterns is the only requirement.

If the plugin can’t be resolved, the hook logs patterns_scripts_unresolved and proceeds without a snapshot. Install it with /plugin install tapestry-patterns@tapestry.

When the snapshot fires

The tapestry-discipline plugin’s SessionStart hook does this on every new conversation:

1. Resolves the canonical snapshot script from the tapestry-patterns plugin.
2. If the plugin can’t be resolved, logs patterns_scripts_unresolved (or canonical_snapshot_script_absent if the plugin is present but the script is missing) and no-ops on the snapshot piece. Session still proceeds. You lose the architecture context but everything else works.
3. Otherwise runs python <canonical_snapshot> --repo-root <your repo>. On error it logs snapshot_script_error and proceeds without the snapshot.
4. If the snapshot succeeded, runs the canonical diff script (also with --repo-root) against the most-recent prior snapshot. Diff failure is non-fatal — the new snapshot still exists.
5. If both succeeded, the hook bundles the latest -narrative.md (if present) or the -diff.md as additional context for the conversation.

The whole pipeline takes 1-3 seconds on a typical repo. It’s bounded by a timeout in the hook so it can’t hang your session indefinitely.

Why it’s load-bearing

Two reasons:

1. The agent’s architecture awareness compounds over time. Each session adds another snapshot to docs/architecture-snapshots/. The next session’s diff has a baseline to compare against. If you delete docs/architecture-snapshots/ to clean up the directory, the next snapshot has no prior baseline — the diff is empty, and the agent loses the change-detection context. (It still works going forward; you just lose the historical record.)

2. Drift detection is silent without it. When you add a new Render service, change a build command, swap an env-var key, or modify the MCP config in .mcp.json, the snapshot picks it up automatically and the next session’s diff surfaces it. Without the pipeline, those changes happen and the agent has no idea — you’re responsible for telling the agent every time. The pipeline is a built-in delta detector that runs without you having to remember.

What fails (silently) if you remove pieces

If you delete or move	The pipeline…	The session…
docs/architecture-snapshots/ directory	First post-deletion snapshot recreates the directory. Diff has nothing to compare against (treated as “first ever snapshot”).	Loses historical record. Going forward, the system rebuilds.
The tapestry-patterns plugin uninstalled (or its cache scripts deleted)	Hook can’t resolve the canonical; logs patterns_scripts_unresolved / canonical_snapshot_script_absent.	Loses snapshot + diff context. Install: /plugin install tapestry-patterns@tapestry, then restart.
Per-repo scripts/architecture_*.py wrappers (if you keep any)	No effect on the SessionStart hook (it uses the plugin canonical); only manual/CI calls to the wrapper break.	Session snapshot unaffected.

Each of these is a one-line silent loss. The agent doesn’t crash. It just stops seeing the architecture.

How to set it up

There’s nothing to add to your repo. Install the tapestry-patterns plugin (/plugin install tapestry-patterns@tapestry), enable tapestry-discipline, and restart — the SessionStart hook runs the canonical snapshot from the plugin against your repo root. Commit an empty docs/architecture-snapshots/ (with a .gitkeep) if you want the output tracked from the first run.

First run produces the first snapshot. From there, every session adds another and diffs against the prior.

How to verify it’s working

After a fresh session start:

ls docs/architecture-snapshots/ | tail -5

You should see at least one set of <timestamp>-snapshot.json/md files dated to your current session. If they’re missing, the SessionStart hook isn’t running the pipeline. See Recover from common failures for the diagnosis.

You can also run the snapshot manually any time — if your repo keeps the optional wrappers:

python scripts/architecture_snapshot.py
python scripts/architecture_diff.py

If the wrapper reports “canonical architecture_snapshot.py not found”, install the tapestry-patterns plugin. (The SessionStart hook doesn’t use these wrappers — it runs the plugin’s canonical directly.)

Related

• The discipline stack — how the snapshot fits with the other pieces
• The plugins — the SessionStart hook in the tapestry-discipline plugin is what runs the pipeline
• Load-bearing files — file-by-file reference
• Recover from common failures — symptoms when this breaks