/system-flow-mapper

name: system-flow-mapper
description: >-
  Produces three grounded deliverables for ANY codebase by reading it (source
  unchanged), written into the project under docs/system-flow/:
  SYSTEM_FLOW.md (deep technical reference),
  system-flow.html (jargon-free offline companion for non-technical readers), and
  system-flow-technical.html (interactive offline reference for engineers: searchable
  endpoint cards, actor
  sidebar, sequence diagrams, light/dark toggle). Detects
  project type first and routes to the right playbook (backend/API, frontend/SPA,
  full-stack/monorepo, Pulumi, Flux/GitOps, or generic IaC). Use this whenever the
  user wants to "map the flow", "understand how this project works", "document the
  system", "draw the request/response flow", "diagram the architecture", "trace how
  data moves", "explain the request lifecycle", "show what each user/role can do",
  or "onboard me to this codebase" — across frontend, backend, full-stack, or
  infrastructure-as-code repositories, even if they don't name these files
  explicitly. Prefer this skill over ad-hoc exploration whenever the goal is a
  durable architecture/flow document plus a plain-language companion. Not for
  modifying code (it is read-only — it only writes docs under docs/system-flow/)
  and not a substitute for runtime profiling or live debugging.

System Flow Mapper

Reproduce, on any project, a three-part deliverable:

1. **`$DOCS_DIR/SYSTEM_FLOW.md`** — the source-of-truth technical map (how data moves, what each actor can do, the data model, async paths, and a tech-debt list). 2. **`$DOCS_DIR/system-flow.html`** — a self-contained, fully-offline, jargon-free visual companion for non-technical readers. 3. **`$DOCS_DIR/system-flow-technical.html`** — a self-contained, fully-offline, interactive technical reference: searchable endpoint cards with method badges and role chips, actor-scoped sidebar navigation, sequence diagrams, and a light/dark toggle. For engineers and reviewers.

`$DOCS_DIR` is `docs/system-flow/` inside the analyzed project (computed in Step 0c).

This is a **read-only analysis of the project's source** — never change application, config, or source files. The only files you create are this skill's own deliverables under `$DOCS_DIR/` (the three docs, per-section fragments, and `state.json`). The one project file you may touch is `.gitignore`, and only with the user's say-so (see Step 0c).

The bar: deep, **grounded** (every claim cites a real `path:line`), and honest (anything you can't confirm is tagged `VERIFY`, never guessed). The companion HTML must read like a friendly explainer with zero jargon.

---

Data sources: files by default; live infra reads only on opt-in

**Default — and ALWAYS in non-interactive / benchmark / automated runs:** work **strictly from committed files, read-only.** Derive everything from what's in the repo. Do **not** invoke project CLIs (`pulumi`, `flux`, `kubectl`, etc.), and do not contact any live cluster, cloud account, or state backend. Any live-only state that can't be read from files is tagged **`VERIFY`** rather than guessed.

**Optional live-read mode (infra projects only, opt-in per run):** if — and only if — the user explicitly opts in for this run (e.g. *"run in live mode"* / *"you can use the cluster"*), the Pulumi/Flux/IaC playbooks may run **read-only** introspection commands to fill in live state. The infra playbooks **offer** this during Phase 1 and list the prerequisites; never assume it. Live mode is governed by these rules (details and exact command allow/deny lists live in the infra playbooks):

• **Read-only commands ONLY.** Never run anything that mutates infrastructure, state,

or the repo (no `apply/create/delete/patch/edit/scale/exec/port-forward`, `reconcile/suspend/resume/bootstrap`, `up/destroy/import/config set/state`, `git commit/push/checkout/clean`).

• **Confirm the target before any cluster command.** Print the active kube context +

namespace (or Pulumi stack) and confirm with the user it's the intended environment, so production is never touched by accident.

• **Fail-stop, never fall back blindly.** If a command fails on access (wrong/no

context, not authenticated, missing passphrase), STOP and tell the user exactly what to set up. Don't retry blindly or silently revert.

• **Never reveal secret VALUES.** Even in live mode, never retrieve, decrypt, or

display plaintext secret material, and never write a secret value into either deliverable. No `kubectl get secret -o yaml|json` (existence + metadata only), no `pulumi stack export` of secret material, no `--show-secrets` flags. Prefer non-secret reads. Record *that* a secret exists and *where* it's referenced — never its plaintext.

• Anything still unreadable stays **`VERIFY`**. Live mode never modifies the repo or

the infrastructure — it only *reads*.

---

The workflow (every run)

Phase 0  Read intent docs → detect project type → announce the playbook
Phase 1  Read-only INVENTORY  → STOP, present it, wait for confirmation   ← mandatory gate
Phase 2  Build all three deliverables, sliced by the Phase-0 axis
Phase 3  Self-verify (spot-check citations + headless-render both HTMLs)

Track these as TODOs so the gate isn't skipped.

---

Phase 0 — Detect the project type

Step 0a — Read intent & convention docs first (when present)

Before scanning for project-type markers, read any of the following files that exist in the repo. They provide **intent and convention context** — domain vocabulary, module boundaries, known decisions — that sharpens the inventory in Phase 1 and the diagrams in Phase 2.

Files to look for (not all will exist — skip gracefully if absent):

| File / path | What to extract | |---|---| | `CLAUDE.md`, `AGENTS.md`, `.cursorrules` | Coding conventions, off-limit areas, project vocabulary | | `README.md` (root or per-package) | Purpose, entry points, how to run | | `ARCHITECTURE.md` | Modul