map-states

Repository context

The current repository is both the CONSUMER, whose convention home declares where artifacts land, and the DEFAULT SUBJECT, the repository whose tracked source declares the state machine.

Collect with an individual Bash call, one command per call: the project root, git rev-parse --show-toplevel. Treat a failure (not a repository, git unavailable) as an unknown value and carry on; ${CLAUDE_PROJECT_DIR} is the resolver's --root either way. An optional [entity] argument selects one machine when the record holds several.

Purpose

Answer "which states exist, and which transitions leave them" from an explicit transition table. Every transition cites a file. The scripts collect and render. Do not draw a transition the script did not emit. A status assignment scattered through the code is not a transition.

Resolve home

Read ${CLAUDE_PLUGIN_ROOT}/reference/config.md first. This skill writes into architecture_dir. It does not read landscape_dialect and it does not add a dialect key. A state diagram is not a C4 diagram type.

Run bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-convention-home.sh" --root "${CLAUDE_PROJECT_DIR}" and follow the exit code. Never parse the root instruction file yourself. Exit 0 means read <home>/architecture/README.md for architecture_dir. Exit 1, 2, and 3 mean there is no declared home.

Per key, in order: --out <dir> wins for this run alone, then a declared architecture_dir, then one question. architecture_dir has NO default. An undeclared and unconfirmed home, including every non-interactive run, STOPS and points at /architecture:setup. Do not invent a directory.

This skill never writes the consumer's root instruction file or its topic doc.

Build the record

"${CLAUDE_SKILL_DIR}/scripts/collect-states.sh" \
  --repo "<subject-repo>" --generated-on "<YYYY-MM-DD>" \
  --out "<architecture_dir>/states.json"

The record is schema_version 1 in the one-object-per-line layout the script writes. The shipped libraries are XState createMachine and Stateless Configure / Permit / PermitIf / PermitReentry. Confidence is high when every transition came from one of those tables. It is medium when a table is drawn and an ad hoc .Status = assignment elsewhere in the tracked source bypasses it (the record's reason says ad-hoc-status-assignments-beside-table): the diagram omits those transitions. Nothing drawn is refused.