architecture

Architecture — Pech

Every file in this directory is auto-generated. Do not hand-edit.

The generator at generate.py reads the source-of-truth (plugins/*/.claude-plugin/plugin.json, plugins/*/hooks/hooks.json, plugins/*/skills/*/SKILL.md, plugins/*/agents/*.md) and writes:

File	Purpose
highlevel.mmd	System diagram — Pech's 5 sub-plugins + data flow
hooks.mmd	Hook lifecycle per sub-plugin (SessionStart / PostToolUse / PreCompact / Stop)
lifecycle.mmd	Session flow — SessionStart rate-card load → PostToolUse ledger/budget → Stop finalization
dataflow.mmd	Cross-plugin flow via enchanted-mcp events (emu → pech → peer degradation)
index.html	Dark-themed single-page explorer combining all four

When to regenerate

Every time you change any of:

• A sub-plugin's .claude-plugin/plugin.json
• A sub-plugin's hooks/hooks.json
• A skill's SKILL.md frontmatter
• An agent's agents/*.md frontmatter

Run:

python docs/architecture/generate.py

Commit the regenerated *.mmd and index.html in the same commit that changed the source. Diagram drift is a code-review red flag.

Why generation, not hand-edit

The 5-sibling consensus (emu + wixie + crow + hydra + sylph) treats this as a brand invariant: diagrams never go stale. Every sibling's generate.py reads the same source shapes and produces the same diagram types. Hand-editing a .mmd means the next generate.py run silently overwrites your work.

Optional: SVG renders

If mermaid-cli is available (cd docs/assets && npm install), generate.py will produce SVG renders alongside the .mmd files. Pair this with docs/assets/apply-blueprint.js for the blueprint-style dark theme.

Troubleshooting

• .mmd file is a one-line placeholder: you haven't run generate.py yet. Run it after your first sub-plugin is configured.
• generate.py raises KeyError: a sub-plugin's plugin.json is missing a required field. Compare against any sibling (enchanter-ai/wixie/plugins/prompt-crafter/.claude-plugin/plugin.json).
• index.html renders blank: the four .mmd files are stale or empty. Regenerate.
• Anomaly narrative in /pech-report PDF looks wrong: that's generated by Opus at report-time, not by generate.py. File the issue against cost-query sub-plugin.