Service Blueprinting

Takes an org from scattered service documentation (or nothing at all) to a deployed, evolving service blueprint: ingest docs, co-create from conversation, translate foreign blueprints, review with hash-bound sign-off, import via a backend adapter (no-DB fallback or Supabase), present with the bundled React template, and update in place. A blueprint touched once is a failure; touched monthly is the product.

Paths resolve against the plugin root (${CLAUDE_PLUGIN_ROOT} in Claude Code) or the workspace root, per AGENTS.md.

The workspace

Everything revolves around one canonical artifact and one state file, both git-tracked in the org's workspace (a clone of this template):

• blueprint/*.json — the IR: human-editable JSON mirroring the data model, validated by references/ir-schema.json. JSON is the supported authoring format (the scripts are stdlib-only; .yaml/.yml is read only if PyYAML happens to be installed). Text fields are locale maps ({en: …, zh: …}); every entity has a stable key that UUIDs derive from, so re-imports are idempotent.
• blueprint-workspace.json — per-scenario status + sign-off hash, per-locale targets, schema_version. Spec: skills/map/references/workspace-state.md.

Pipeline: sources → IR → validate → review/sign-off → import (adapter) → build check → deploy, then the update loop re-enters at ingest or import.

Entry-state detection (do this first)

Inspect the target directory before doing anything: does blueprint-workspace.json exist? A blueprint/ dir? A template clone? What do the statuses say? (The SessionStart hook summarizes this when present.) Then route:

Read the routed playbook before executing its phase; it carries the gates.

Decline early what this isn't for: org charts, gantt charts, non-journey diagrams, real-time multi-user editing — point elsewhere rather than bend the model.

Hard rules

Everything in this skill is guidance you may adapt to the org — except these, which are where the system actually breaks:

• ⚠ REQUIRED — validate before import. Run scripts/validate_ir.py and require exit 0 before any adapter runs. It catches what the DB trigger would abort mid-import (cells without path_steps, a dependency end that names no cell of this service, duplicate columns, a lane role outside the closed eight).
• ⚠ REQUIRED — import only signed scenarios. Import only scenarios whose recorded content_hash matches the current subtree, recorded after the user explicitly approves the preview — skills/map/references/workspace-state.md § Sign-off.
• ⚠ REQUIRED — draft journeys only from journey docs. Manuals and feature inventories describe the system; they route to co-creation as reference material (the ingest playbook's critical branch).
• ⚠ REQUIRED — secrets follow references/adapter-contract.md §7; a pre-write hook enforces the committable-file half.
• ⚠ REQUIRED — confirm the target directory before writing anything (scaffolding, IR files, generated artifacts), and the import target (project ref / output paths) before any import.
• ⚠ REQUIRED — backend choice is the user's: ask, per locale — references/adapter-contract.md §1.

Deterministic exit conditions

Every phase ends at a quantitative stop condition. Check them against blueprint-workspace.json, which is also what makes long unattended runs ("all 6 scenarios signed off") verifiable:

Agents

Pilot document-reader on a few docs before a whole corpus. Per-scenario locale translation fans out to generic subagents.

Updating a deployed blueprint, a chain question ("what else does this edit touch?") goes to impact-tracer, seeded with the edited cells, on the export of the whole service (reach: CONTEXT.md Dependency). An affected cell it reports in another scenario puts that scenario's cells in the delta's review, named with their scenario and path.

References

Correctness-critical steps (validation, seed-SQL/fallback generation, UUIDv5 derivation) live in scripts/ — execute them, never improvise their logic in-context.