spec-kit-ascii-diagram

A Spec Kit extension that adds one command — speckit.ascii-diagram.render — which draws a text-based diagram (state machine, architecture, flow, dependency graph, or coverage map) for the feature you're currently working on, using plain Unicode box-drawing characters.

Why

Spec Kit's core workflow (specify → plan → tasks → analyze → implement) produces prose and tables. That's precise, but not always legible at a glance — a small diagram next to the paragraph it summarizes often clarifies structure that text buries. This extension hooks into after_specify, after_plan, after_tasks, and after_analyze (all optional — it asks before drawing) so a diagram gets offered automatically at the point in the workflow where it's most useful, without you having to remember to ask for one.

Hook	Diagrams	Where it goes
after_specify	State machine / flow, from spec.md	Appended to spec.md
after_plan	Architecture / components, from plan.md	Appended to plan.md
after_tasks	Dependency graph, from tasks.md	Appended to tasks.md
after_analyze	Requirement↔task coverage map, from the analysis report	Printed inline only — analyze is strictly read-only, so this hook never writes a file

What this is not

This does not parse your source code or compute a real call graph / dependency graph. It's the model's best-effort sketch of what the spec/plan/tasks document already says, drawn by hand at generation time — a comprehension aid, not a verified structural analysis. If you need a diagram derived from actual code, use a static-analysis tool instead.

Related extensions

The community catalog already has a diagram extension ("Spec Diagram") — it renders Mermaid diagrams of SDD workflow state and progress (which phase you're in, task dependencies as a process view). This extension is a different, complementary angle: it diagrams the content of what a given spec.md/plan.md/tasks.md describes (a state machine, an architecture, a flow), in plain Unicode text rather than Mermaid, so it renders anywhere without a Mermaid-capable viewer.

Install

# from the published release (not yet in the official community catalog —
# see below), pinned to a specific tag:
specify extension add ascii-diagram \
  --from https://github.com/MRZHUH/spec-kit-ascii-diagram/archive/refs/tags/v1.1.0.zip

# or from a local clone, for development
specify extension add --dev /path/to/spec-kit-ascii-diagram

Once this extension is accepted into the official community catalog, installing will simplify to specify extension add ascii-diagram with no --from needed.

Use

It runs automatically (with a yes/no prompt) after /speckit.specify, /speckit.plan, /speckit.tasks, and /speckit.analyze. You can also invoke it manually at any time:

/speckit.ascii-diagram.render
/speckit.ascii-diagram.render plan       # target a specific artifact
/speckit.ascii-diagram.render analyze    # coverage map from the last analysis report (inline only)

Example output

Appended to the end of plan.md:

## Diagram (generated by speckit.ascii-diagram.render)

_This is a hand-drawn sketch of the structure described above, not a
static-analysis output. Re-run `/speckit.ascii-diagram.render` after material
changes to this document — it will not update itself._

```text
Client ──▶ API Gateway ──▶ Service A ──▶ Datastore
                     │
                     └──▶ Service B
```

Printed inline after an /speckit.analyze report (nothing written to disk):

FR-001 ──▶ T003, T004
FR-002 ──▶ ⚠ uncovered
FR-003 ──▶ T007
           T009 ──▶ ⚠ unmapped task

License

MIT — see LICENSE.