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. But two scripts in your scripts/ directory and one output directory under docs/ are load-bearing, and if you delete or move them without knowing what they are, the agent loses its architecture awareness at session start.
What the diff is for
Section titled “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
Section titled “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
Section titled “Where the work actually happens”The thing you have in your repo is NOT the real script. It’s a thin wrapper:
your-project/scripts/architecture_snapshot.py ← thin wrapper (~50 lines)your-project/scripts/architecture_diff.py ← thin wrapper (~50 lines)Each wrapper looks up the canonical implementation in the tapestry-patterns plugin and dispatches to it with your repo root as an argument. 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.pyThis is the Pillar 1 discipline (ONE pattern, ONE home) applied to the snapshot scripts: every project shares the same canonical implementation, so when the canonical evolves, every project gets the improvement on next pull. The per-project wrappers exist only so existing callers (the SessionStart hook, CI, manual python scripts/architecture_snapshot.py invocation) keep working — they’re a routing layer, not a copy.
If the canonical isn’t found, the wrapper writes a clear error pointing you to install the patterns plugin: /plugin install tapestry-patterns@tapestry.
When the snapshot fires
Section titled “When the snapshot fires”The tapestry-discipline plugin’s SessionStart hook does this on every new conversation:
- Looks for
scripts/architecture_snapshot.pyin your repo. - If it’s missing, logs
snapshot_script_absentand silently no-ops on the snapshot piece. Session still proceeds. You lose the architecture context but everything else works. - If it’s present, runs
python scripts/architecture_snapshot.py. If the script errors, logs the error and proceeds without the snapshot. - If the snapshot succeeded, runs
python scripts/architecture_diff.pyagainst the most-recent prior snapshot. Diff failure is non-fatal — the new snapshot still exists. - If both succeeded, the hook bundles the latest
-narrative.md(if present) or the-diff.mdas 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
Section titled “Why it’s load-bearing”Two reasons:
-
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 deletedocs/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.) -
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
Section titled “What fails (silently) if you remove pieces”| If you delete or move | The pipeline… | The session… |
|---|---|---|
scripts/architecture_snapshot.py | Detects absence, logs snapshot_script_absent, no-ops. | Loses snapshot + diff context. Proceeds normally otherwise. |
scripts/architecture_diff.py | Snapshot still runs; diff step is skipped. | Has the snapshot but no diff against prior baseline. |
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 canonical scripts in the tapestry-patterns plugin cache | Wrapper falls through every fallback path and writes an error. | Hook logs the error and proceeds without snapshot context. |
The tapestry-patterns plugin uninstalled entirely | Wrapper can’t find any canonical; errors. | Same as above. Install: /plugin install tapestry-patterns@tapestry. |
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
Section titled “How to set it up”Two thin wrappers + one output directory. Total: under 200 lines, all boilerplate.
The canonical pattern is documented in a real consuming project’s PR (commit 2325e67). Copy the two wrapper files from any existing repo that has them — the reference implementations live in the platform beta repo’s scripts/architecture_*.py — then commit the empty docs/architecture-snapshots/ directory with a .gitkeep.
First run produces the first snapshot. From there, every session adds another and diffs against the prior.
If you don’t have the canonical scripts available (tapestry-patterns plugin not installed): /plugin install tapestry-patterns@tapestry, then restart the project’s Claude Code session.
How to verify it’s working
Section titled “How to verify it’s working”After a fresh session start:
ls docs/architecture-snapshots/ | tail -5You 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:
python scripts/architecture_snapshot.pypython scripts/architecture_diff.pyIf the wrapper exits 127 with “canonical architecture_snapshot.py not found”, install the patterns plugin.
Related
Section titled “Related”- The discipline stack — how the snapshot fits with the other pieces
- The plugins — the SessionStart hook in the
tapestry-disciplineplugin is what runs the pipeline - Load-bearing files — file-by-file reference
- Recover from common failures — symptoms when this breaks