generate-flow-diagram

What this skill does

# Generate Flow Diagram

Generate Flow Diagram turns workflow descriptions into auditable Markdown
documents with Mermaid flowcharts. The orchestrator is a routing layer: it keeps
normalized inputs, approvals, verdicts, and the final passing candidate in
context while subagents handle analysis, building, and review.

Bundled references are the offline execution contract. External links are
optional just-in-time sources for current Mermaid syntax or design rationale.

## Inputs

| Input | Required | Example |
| ----- | -------- | ------- |
| `PROCESS_SPEC` | Yes for new diagrams; optional for refinements | `Create a deployment-review flow: the deployment reviewer decides whether a release candidate is safe; inputs are PRs, CI, changelogs, and rollback plans; outputs are readiness comments; allowed actions are reading artifacts, summarizing risks, and posting comments; boundaries are no deploy or CI bypass; sensitive actions are deploy and rollback; HUMAN_CONFIRMATION_REQUIREMENTS is approval before recommending deploy; evidence comes from CI, runbooks, and incident history; completion states are ready, blocked, needs validation, or escalated.` |
| `EXISTING_FLOW_OR_DIAGRAM` | Yes for refinements | Existing Mermaid block, file, or process description |
| `REFINEMENT_REQUEST` | No | `Improve the current diagram without changing scope` |
| `APPROVED_REFINEMENT_GAPS` | No | `G1 and G3 only` or `none` |
| `DIAGRAM_SCOPE` | No | `orchestrator`, `subagent`, or `whole` (default) |
| `SCOPE_SUBAGENT_NAME` | Conditional | Required when `DIAGRAM_SCOPE=subagent` |
| `PACKAGE_PATH` | Yes for `RUN_MODE=decompose` | `skills/example-skill` |
| `SUBAGENT_REGISTRY` | Yes for `RUN_MODE=decompose` | Name plus path per subagent |
| `ROOT_DIAGRAM_PATH` | No | Optional root diagram path for `RUN_MODE=decompose`; defaults to `<PACKAGE_PATH>/flow-diagram.md` |
| `SCOPE_LIMITS` | No | Explicit user-approved mutation expansion for `RUN_MODE=decompose`, such as `also update docs/foo.md` |

`DIAGRAM_SCOPE` defaults to `whole` and reproduces current whole-diagram
behavior; `orchestrator` and `subagent` constrain a generated diagram to one
scope and activate the scope checks. `RUN_MODE=decompose` is a package-level
operation over `PACKAGE_PATH` and `SUBAGENT_REGISTRY`. Load
`./references/input-contract.md` for the scope and decompose-mode field details.

## Default Mutation Limits

`RUN_MODE=decompose` is the only mutating mode. During intake, derive a single
`MUTATION_LIMITS` contract and pass it to every dispatched subagent. Unless the
user explicitly expands scope with `SCOPE_LIMITS`, use these defaults:

- Write only inside the resolved `PACKAGE_PATH` skill package after every diagram
  candidate passes `REVIEW: PASS`.
- Allowed write targets are the planner-resolved root diagram, localized
  `subagents/<subagent-name>-flow-diagram.md` files, and the load-instruction
  lines in the package `SKILL.md` and EARNED subagent files.
- Preserve package directory name, frontmatter names, runtime targets, and
  user-facing purpose unless the user explicitly approves changing them.
- Out of scope: sibling packages, `.agents/skills/`, `.claude/skills/`,
  `skills-lock.json`, repository-level docs, private configuration, `.git`, and
  `.handoffs/` files this run did not create.
- During repair cycles, intersect `MUTATION_LIMITS` with the failed review
  findings: change only files tied to the specific `REVIEW_FEEDBACK`, original
  plan, and approved scope.

All other modes are read-only and emit content only. Runtime mapping: Claude Code
uses Write and Edit tools only inside `MUTATION_LIMITS`; OpenCode uses `edit`
permission scoped to the same target package.

Every run produces `PROCESS_INPUTS` before `RUN_MODE` routing. For new diagrams,
normalize `PROCESS_SPEC`. For refinements, derive `PROCESS_INPUTS` from
`EXISTING_FLOW_OR_DIAGRAM`, `REFINEMENT_REQUEST`, any supplied `PROCESS_SPEC`,
and explicit assumptions. For `RUN_MODE=decompose`, derive `PROCESS_INPUTS` from
the package-level inputs and mutation boundary: `PACKAGE_PATH`,
`SUBAGENT_REGISTRY`, the resolved `ROOT_DIAGRAM_PATH`, `MUTATION_LIMITS`, allowed
write targets, and explicit assumptions. Load `./references/input-contract.md` only when
field-level checks, missing-field handling, or a clarification question are
needed. Ask one concise question only when a missing value would change the
diagram contract; otherwise mark safe assumptions explicitly.

## Progressive Loading Map

| Need | Load |
| ---- | ---- |
| Missing-field checks, scoped input contract, mutation limits, or clarification policy | `./references/input-contract.md` |
| Refinement gap inventory and confirmation gate | Dispatch `./subagents/refinement-analyst.md`; load `./references/output-templates.md` only to format the user-facing confirmation request |
| Package decomposition plan (bloat map, earned decision, coverage audit) | Dispatch `./subagents/decomposition-planner.md`; it loads `./references/input-contract.md` for path-boundary checks and `./references/flow-design-playbook.md` for classification |
| Candidate diagram creation or repair | Dispatch `./subagents/diagram-builder.md`; it loads `./references/flow-design-playbook.md`, `./references/mermaid-style-guide.md`, and `./references/output-templates.md` only as needed, including the scoped templates for `orchestrator` and `subagent` scopes |
| Quality gate and fix loop | Dispatch `./subagents/diagram-quality-reviewer.md`; it loads `./references/quality-gate-checklist.md`, including the scope checks for scoped or decompose runs |
| Source-backed rationale or current Mermaid guidance | `./references/external-sources.md`, then fetch the smallest relevant URL |

## Subagent Registry

| Subagent | Path | Purpose |
| -------- | ---- | ------- |
| `refinement-analyst` | `./subagents/refinement-analyst.md` | Inspects an existing flow and returns proposed improvement gaps plus a confirmation question |
| `decomposition-planner` | `./subagents/decomposition-planner.md` | Inspects a whole package and returns a bloat map, an earned-or-no-op decision per subagent, and a localized-diagram coverage audit |
| `diagram-builder` | `./subagents/diagram-builder.md` | Creates or revises the Markdown plus Mermaid candidate from approved scope and bundled references |
| `diagram-quality-reviewer` | `./subagents/diagram-quality-reviewer.md` | Reviews the candidate for Mermaid validity, prompt compliance, approved refinement scope, and scope separation |

Read a subagent file only when dispatching that subagent. Keep raw diagrams,
candidate drafts, and detailed findings inside subagents except for the final
candidate that must be returned to the user.

## Execution

1. Capture all inputs, default `DIAGRAM_SCOPE` to `whole` when absent, derive `MUTATION_LIMITS` for `RUN_MODE=decompose`, and normalize the available source into `PROCESS_INPUTS` before `RUN_MODE` classification. Use `PROCESS_SPEC` for new diagrams; use `EXISTING_FLOW_OR_DIAGRAM`, `REFINEMENT_REQUEST`, any supplied `PROCESS_SPEC`, and explicit assumptions for refinements; use `PACKAGE_PATH`, `SUBAGENT_REGISTRY`, the resolved `ROOT_DIAGRAM_PATH`, `MUTATION_LIMITS`, allowed write targets, and mutation-boundary assumptions for decompose runs. Load `./references/input-contract.md` when the field checklist, path checks, scoped input contract, or missing-field policy is needed.
2. Classify the current pass as `RUN_MODE=new`, `RUN_MODE=refinement`, `RUN_MODE=repair`, or `RUN_MODE=decompose`. For `RUN_MODE=decompose`, follow the Decompose Mode steps below; steps 3-9 cover `new`, `refinement`, and `repair` and are unchanged.
3. For `RUN_MODE=refinement`, dispatch `refinement-analyst` before generating a revised diagram, including `EXISTING_FLOW_OR_DIAGRAM`, `PROCESS_INPUTS`, `REFINEMENT_REQUEST`, and `APPROVED_REFINEMENT_GAPS` when supplied. Consume its return as `PREFLIGHT_VERDICT`: continue only on `PREFLIGHT: PASS`; on `PREFLIGHT: NEEDS_CONFIRMATION`, ask the confirmation q