Repository context
The current repository is both the CONSUMER, whose convention home declares where artifacts land, and the DEFAULT SUBJECT, whose tracked C# contains the entry point.
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. The <entry point>
argument is required: a route (with an optional leading HTTP verb), Type.Method, or a method name,
not a second repository.
Purpose
Answer "what happens when this entry point runs" from call sites in the tree. Every hop traces to a line in a tracked file. The scripts collect and render. Do not add a hop the script did not emit, and do not bind a call to a class that merely has a method of the same name.
Resolve home
Read ${CLAUDE_PLUGIN_ROOT}/reference/config.md first. This skill writes into architecture_dir
and reads no dialect key: the picture is always a mermaid sequenceDiagram.
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: read
<home>/architecture/README.md for architecture_dir. Exit 1, 2, or 3: no declared home.
In order: --out <dir> wins for this run alone, then a declared topic-doc value, then one
question. architecture_dir has NO default. An undeclared and unconfirmed home, including every
non-interactive run, STOPS and points at /architecture:setup.
This skill never writes the consumer's root instruction file or its topic doc;
/architecture:setup apply owns both.
Build the record
"${CLAUDE_SKILL_DIR}/scripts/collect-flow.sh" \
--repo "<subject-repo>" --entry "<entry point>" --depth N \
--generated-on "<YYYY-MM-DD>" --out "<architecture_dir>/flow.json"
--depth defaults to 5. Keep the ${CLAUDE_SKILL_DIR} anchor;
${CLAUDE_PLUGIN_ROOT}/reference/config.md § Script paths
says why. As of: 2026-10-11. Recheck trigger: that section is renamed or removed, or its
own recheck trigger fires.
Exit 3 is a refusal whose message states the reason; nothing was written. Report the reason and stop. Do not draw a sequence from the files you can see.
The record is schema_version 1, one object per line. Each hop carries file and line of the call
site, resolution (statically-resolved, inferred, or unresolved), mechanism (why a hop is
unresolved), sync (synchronous or asynchronous), and handoff.
The shipped adapter reads tracked *.cs only. The entry is one of:
| Entry | Selects |
|---|---|
/orders/{id} |
the handler whose [Route], [HttpGet]-family attribute, or MapGet-family call carries that exact string; a route entry contains /, so a template without one ([HttpGet("{id}")]) is reached through Type.Method |
GET /orders/{id} |
the same route, where the handler takes that verb: GET, POST, PUT, DELETE or PATCH in any case, read from an Http* attribute beside the route or from the Map* name; a handler that names no verb takes any |
OrdersService.Handle |
the method Handle declared in the class OrdersService (the last two names of a dotted entry) |
Handle |
every declaration named Handle |
A Map* call is traced through the method it names as its handler, MapGet("/x", Handle) or
MapGet("/x", Type.Handle), declared in the class that holds the call, an enclosing class, or
Type. A lambda, or a name that is not exactly one declaration in the tree, is a refusal that
points at Type.Method.
More than one match is a refusal that names every site and lists these forms. Nothing else
narrows a match: overloads and same-named types in different namespaces stay ambiguous. A
[Route(...)] above a class is not composed with the routes of its methods (a limit): it names no
handler, so a route entry matches only a string written whole on one handler. An entry with no
block body (expression-bodied or abstract) is a refusal. A repository with no C# file is a
refusal. That is the result. Do not fill it from another language.
A call is followed only through its receiver's declared type, read from a parameter or local of the
enclosing method, then a field, property or primary-constructor parameter of the enclosing class,
then its in-tree base classes; a type name written at the call (Repository.Save) is its own
evidence. The script follows the call, and walks the callee, only when that type is a class in the
tree that declares the method. Never bind a call by method name alone. resolution records the
evidence:
statically-resolved: the type came from a declaration in the enclosing method or class, or is written at the call. The callee may be in another file.inferred: the type came through a base class or a declaration in another file (a partial class), or the method is declared on a base class.unresolved: anything else, never followed.mechanismsays why:
mechanism |
Cause |
|---|---|
interface |
the receiver's type is an interface: one the tree declares, or a name of I plus an uppercase letter that no class in the tree declares |
dependency-injection |
the call is GetService or GetRequiredService |
reflection |
the call is CreateInstance |
broker |
Publish<T> or Send<T>, a hand-off |
dynamic-publish |
Publish or Send with no type argument, a hand-off |
external-call |
the receiver's type is outside the tree: a declared type no tracked file declares (Dictionary, Logger), or a type name written at the call (Console.WriteLine, string.IsNullOrWhiteSpace) |
receiver-type-unknown |
no declaration of the receiver is in reach (a lambda parameter, a var initialized from a call), or the call is chained on a result (.ToList()) |
callee-not-in-tree |
the receiver's type is a class in the tree, but neither it nor an in-tree base class declares the method (an external base class, an extension method, a delegate, a constructor the class does not declare) |
ambiguous-method |
the type is declared more than once in the tree, or declares the method more than once (overloads) |
Publish and Send are hand-offs to a broker this skill does not read: handoff is yes and
sync is asynchronous whether or not the call is awaited. Every other hop takes sync from
await. Neither hand-off is dropped.
Hops are recorded in call order: a followed callee's hops come right after the call that leads to
it, before the caller's next call. An access modifier marks a declaration only as a whole word at
the start of the line, so _internalService.Run(x) and publicUrl = Build(x) are calls.
subject is the github.com origin repository name when that remote resolves, otherwise the
directory basename. The helper is inline in collect-flow.sh.
Render
"${CLAUDE_SKILL_DIR}/scripts/render-flow.sh" \
--record "<architecture_dir>/flow.json" --out "<architecture_dir>"
Write flow.json first, then render from it. The script writes flow.md: a sequenceDiagram
whose participants are architectural roles (transport, application, domain, infrastructure, or the
directory name), not every class. Asynchronous hops use -->>, synchronous hops ->>. A handoff
names /architecture:map-events.
Consecutive hops that share a role pair, sync, resolution, mechanism, and handoff collapse to one arrow; the artifact says how many collapsed, and the table keeps every cited call.
The script prints one summary line on stdout. Keep it for the report:
flow: entry=<name> hops=<n> truncated=<yes|no> unresolved=<n> external=<n> di=<n> handoffs=<n>.
unresolved counts every unresolved hop. external counts the external-call,
receiver-type-unknown and callee-not-in-tree hops, di the interface and
dependency-injection hops; the rest are ambiguous-method, reflection and broker hops.
When truncated=yes, the artifact names the depth and says the sequence stopped. Do not describe
that picture as the whole path.
Exit 1 means the record is unreadable, not schema_version 1, or not one object per line; nothing was written. Report that message. Do not reformat the record by hand.
Parse flow.md before the report. Stdout is one JSON report with a status of ok or error per
block; exit 1 means a block failed to parse:
node "${CLAUDE_PLUGIN_ROOT}/lib/mermaid-gate.mjs" "<out>/flow.md"
Quote any failing block's line and error. A failing block is a defect in the render script:
report it and do not repair flow.md by hand. Without mmdc the parse is a structural check, so
say that an ok does not prove every syntax error is absent. When node is missing, say the
diagram was not checked.
Close with the report
End every run with this block, in this order, filled from the record and the script exits:
- Artifacts: each path written, or
none writtenwhen the run stopped or refused. - Entry: the string, the file, and the line, or the refusal reason when there was no record.
- Flow:
hops=,unresolved=,external=,di=,handoffs=,truncated=quoted from the summary line. - Depth: the number, and the stopping sentence when truncated.
- Unresolved:
unresolved=split intoexternal=(framework and other calls outside the tree, or on a receiver of unknown type),di=(interface and service-locator hops), and the remainder, and that none were bound to a guessed implementation.
Interactive view
After the report, offer an interactive view of flow.json in one sentence. The markdown and the
record stay authoritative. Build it only with ${CLAUDE_PLUGIN_ROOT}/scripts/build-view.mjs flow,
never hand-written; the shared medium resolver decides the destination, with this plugin's medium
option ${user_config.medium}, or "" when that reads empty or unsubstituted (never put a
${user_config.*} string in a shell command), and its report line is printed. Procedure:
${CLAUDE_PLUGIN_ROOT}/reference/rendered-view.md.
What this skill does NOT do
- Bind an interface, a service locator, or reflection to an implementation, or bind any call by method name alone.
- Import graphs, timing, or an exhaustive call graph of every class.
- Message topology. A
PublishorSendis a hand-off, not a consumer list; that is/architecture:map-events. - Read or add a dialect key.
- Fetch anything, or edit a source file. The only writes are
flow.jsonandflow.mdunder the resolved output directory. - Invent a home. No declared, no
--out, and no confirmedarchitecture_diris a stop, not a default.
Next
- A hop leaves the process at Publish or Send:
/architecture:map-events. - The trace settles a decision worth keeping:
/architecture:record-decision. - The trace shows a hop or contract to redesign:
/planning:design integration.
Gotchas
- A dynamic diagram is one feature, not the structure. The trace covers one entry point. Pointer: when checking a dynamic view's scope or elements, fetch C4 dynamic diagram § Scope, § Primary and supporting elements and C4 diagrams § Supporting diagrams live. As of: 2026-11-10. Recheck trigger: the dynamic-diagram page changes the scope or the element rule, or the diagrams index adds or removes dynamic.
- The picture has no dialect key. The authoring-formats convention keys only data diagrams and
C4 system views, so a traced sequence stays an unkeyed mermaid
sequenceDiagram, as/planning:designdraws its sequence flows. The decision is recorded in${CLAUDE_PLUGIN_ROOT}/reference/config.md. - Participants are roles. A controller directory is transport,
Applicationis application,Domainis domain, andInfrastructureis infrastructure. Other directories keep their own name. The artifact says when consecutive hops inside one role pair were collapsed. - Unresolved is not a search.
IOrders _ordersfollowed by_orders.Placedoes not become thePlacemethod on another class, and_cache.Add(x)does not become the oneAddmethod in the tree: its receiver is aDictionary, so the hop isexternal-calland is not walked. The hop cites the call site and stops. - A truncated trace says so.
--depthcounts followed callees. A callee that still contains a call is whytruncated=yes. Do not narrate the diagram as complete. - A reformatted record reads as empty unless the reader refuses it. Hops are one
{"from_role":object per line, or the array is[]on its key's line.render-flow.shexits 1 on any other shape and writes nothing. - Tracked C# only.
git ls-filesis the file set. The adapter does not read project files, configuration, or other languages. Read: C#. Declined: Node, Go, Python, Rust, JVM, Ruby, and PHP; their files are never read, and a tree with no C# file is refused. A comment is not a call. A declaration line is not a hop. - ASP.NET route attributes are the entry grammar.
[Route("...")]and[HttpGet("...")](and the Post, Put, Delete, and Patch attribute forms) match a route entry, as do the same quoted strings onMapGet/MapPostand the otherMap*methods. Pointer: when checking the route forms the adapter matches, fetch controller routing § Attribute routing with HTTP verb attributes and minimal APIs § Routing live. As of: 2026-11-10. Recheck trigger: either section drops those attribute names or theMap*route-string form. A verb prefix on the entry (GET /orders/{id}) is matched against theHttp*attribute names beside the route, or theMap*name. The script does not compose a class-level[Route(...)]with a method route; that is a limit of this adapter.