Communitygithub.com

xylem

Map a repository from architecture down to named functions and selected decisions, trace scoped user journeys, check the map against source, and build an interactive static site (Explore, Journeys, State map, Code). Use when someone asks to visualize, map, explain or audit a repo's architecture, flows, UX journeys or code paths, or wants "the whole app on one page".

What is xylem?

xylem is a Claude Code agent skill that map a repository from architecture down to named functions and selected decisions, trace scoped user journeys, check the map against source, and build an interactive static site (Explore, Journeys, State map, Code). Use when someone asks to visualize, map, explain or audit a repo's architecture, flows, UX journeys or code paths, or wants "the whole app on one page".

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Iineman2/xylem/tree/HEAD/skills/xylem

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does xylem do?

You will turn a repository into a source-grounded map. It has four views, in a static two-file site (index.html and deep-view.json):

ViewShows
ExploreComponents (the parts of the system) and the connections between them, grouped in layers
Customer journeysEach journey a user can take, animated over the architecture: requests, replies and labelled hand-offs
State mapEvery declared state dimension in the mapped scope, its states, and the transitions that journeys actually take
CodeEvery mapped function as a tile in its region, with its decisions, calls and callers, and journey paths traced at function level

The method matters more than the page. Every claim is tied to file:line. Every connection is real. Where the code cannot settle something, the map says so instead of guessing.

Ground rules (apply in every phase)

  1. Evidence or nothing. Every component, unit, decision, edge, state and action should cite file:line. If you cannot cite it, mark it UNVERIFIED or leave it out. This is an author/reviewer obligation: automated gates enforce architecture evidence and deep source locations, not every state/action citation or explanation?s meaning.
  2. Assign IDs; never invent entities or connections. Use the scaffold?s file-position IDs; manually authored IDs must also be unique and stable. Cross-region edges must ride a declared architecture connection. If one is missing, record a diagram_gap and verify it in code before adding it, with evidence.
  3. Honest gaps beat impossible paths. If a journey outcome cannot be traced distinctly from the source, write {"unavailable": "<specific reason>"}. Never copy the success path into a failure outcome. Never chain branches that cannot both be true.
  4. Say what it is. Traces are static source paths, not recordings of real runs. Label them that way in the page.
  5. Read-only. Never edit the target repo. Write everything to .xylem/ (or a folder the user names).
  6. Privacy. Do not send repo content to any outside service unless the user asks. The site makes only same-origin requests for its data and optional videos. It makes no external requests; serve it on loopback for offline use.

Output layout

.xylem/
  census.json        # every definition found in the code (scripts/census.py)
  architecture.json  # phase 1
  journeys.json      # phase 2
  deep.json          # phase 3 (function-level map)
  validation.json    # scripts/validate.py output
  reviews/           # cross-review reports (phase 6)
  site/              # index.html + deep-view.json (+ videos/)   (scripts/build_site.py)

Formats for every file are in references/schemas.md. Read it before writing any JSON.

Phases and gates

Do the phases in order. Each phase ends with a gate. Do not continue until the gate passes, or the user accepts a documented gap. In an explicitly authorized trial, retain failing artifacts and logs unchanged and continue only within that trial scope; label subsequent outputs provisional. A structural pass does not establish full semantic coverage.

Phase 0: Census (deterministic)

python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]

This inventories named definitions with Python AST, a standard-library JS/TS token walker, and approximate regexes for other supported languages. scannedFiles includes zero-definition source files. JS/TS covers generic arrows, concrete multiline/computed methods, overload signatures, lexical function/class owners, regex literals and template interpolations; anonymous callbacks are not census units. It is a measured inventory, not a proof of all language syntax. Qualify it with an independent parser or source sample before claiming completeness. Later percentages describe this inventory only.

Gate: the census counts look plausible against the repo size. Excluded paths are justified, for example generated code or node_modules.

Phase 1: Architecture

Read the entry points, build files, main modules and process boundaries. Then write architecture.json:

  • layers: for example shell, UI, server, domain, storage, workers, external;
  • components: each with id, layer, files[], a plain responsibility, and processType;
  • connections: each {from, to, label, kind}, where kind is spawn, ipc, http, file, data or uses;
  • flows: the main end-to-end flows as ordered component steps.

Gate: python scripts/validate.py .xylem --only architecture passes. Every scannedFiles entry belongs to a component, or has a reasoned architecture.meta.fileExclusions entry. Evidence paths and lines must exist under the evidence root.

Phase 2: Journeys and states

Write journeys.json. Work these out from the UI, routes, CLI commands, jobs and error paths:

  • stateDimensions: every independent state machine;
  • screens: every screen;
  • actions: each user action and system transition, with its outcomes, the exact text the user sees, and undo;
  • journeys: start states plus steps.

Every action carries an ordered architecture trace (alternating component and connection). Return legs use {"connection": [a, b], "direction": "reply"}. When the next step does not start where the last one ended, the step carries transition.handoff, with a type and label: user, timer, queue, continuation, lifecycle or download. Cover happy, unhappy, recovery and edge journeys.

Gate: validate.py --only journeys passes:

  • every journey replays through valid outcomes;
  • zero silent jumps (each light-up is reached by a wire, a reply or a labelled hand-off);
  • no orphan states.

Phase 3: Function-level map (final resolution)

  1. Generate a draft map from the census:
python scripts/scaffold_deep.py .xylem

It writes deep.json. The draft contains assigned census units, Python decisions from AST, and heuristic JS/TS if, while, for, switch and parenthesized catch points. JS/TS does not claim a complete inventory of ternaries, calculations or short-circuit decisions. Comments, literal contents and child declarations are excluded from each body. Generic calls retain distinct callsite positions. Call edges use source: heuristic and confidence: name-resolved; unresolved names are not invented links. Refine against source; name resolution is not type resolution. 2. Refine the draft by reading the code:

  • business-readable summary per unit, written from the body, not the name;
  • for every decision, a plain question ("Is this file larger than 16 MiB?") plus the exact code test, a kind (branch, calculation, loop or unconditional) and correct successors. A return or raise ends the path. A try block's normal and error continuations are separate, and a pending exception runs finally and then propagates. When you are unsure, mark the successor unresolved; never verified;
  • risk tags only on decisions that directly implement a known defect.
  1. Write actionTraces: for each journey action and outcome, the ordered execution events {component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.
    • event is one of call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally or resume. See schemas for activation frames, terminal events and supported replay limits.
    • Start at the real initiator, such as a UI handler, route or job.
    • Follow calls, returns and process boundaries. A refusal must follow the real error path back to the user. It must never continue to "saved" or "success".
    • Where the path is unknowable, emit {"event": "unknown", "note": "..."}, or mark the whole outcome unavailable.

Large repos: split phase 3 by code area across several agents, each writing deep-<part>.json in the same format, then merge them with scripts/merge_deep.py. Reconcile IDs by file and definition line, never by name similarity.

Gate: validate.py passes the full set:

  • every census definition emitted or explicitly excluded with a reason; emitted coverage and exclusion accounting are separate counters;
  • every edge endpoint resolves;
  • every cross-region edge rides a connection;
  • decision successors resolve;
  • trace references are valid;
  • selector consistency: no activation takes mutually exclusive choices for unchanged values. Source writes can change a value; an iteration label alone cannot reset constraints. Supported grammar and limits are in the schema. For example, x==='a' yes and then x==='b' yes, or a value excluded and then required by includes(). Fix the trace, or withdraw it to unavailable, naming the conflict.

Phase 4: Build the page

python scripts/build_site.py .xylem

This writes site/index.html and site/deep-view.json. Videos are optional: drop videos/<journeyId>.mp4 plus videos/manifest.json into .xylem/ first (see the schemas). Serve site/ over HTTP to view it, for example python -m http.server -d .xylem/site. A file:// page cannot load the Code view's data.

Gate: open the page and check each mode once:

  • no console errors;
  • phone width (420 px) has no horizontal scroll;
  • keyboard and dark mode work.

Phase 5: Optional real-screen recordings

If the app has a UI you can run locally, record journeys with Playwright. A starter is scripts/record_journey.example.mjs. Rules for recordings:

  • drive the real UI, with no mocked responses;
  • add a caption per step;
  • speed up idle waits, and caption the speed-up;
  • record per-step atSec in manifest.json;
  • mark partial recordings as partial.

The viewer syncs a video to the map, so the video becomes the clock.

Phase 6: Cross-review council

Use two independent reviewers where possible: two different models or agents, or at least a fresh context with no access to the author's reasoning. Follow references/protocol.md:

  • the author never grades their own work;
  • the reviewer receives files and code, never the author's conclusions;
  • the reviewer runs the independent checker and samples claims against source: the single sampling rule in protocol.md (all available items below its minima);
  • findings go to reviews/<reviewer>-<round>.md with severity, evidence and a concrete fix;
  • acceptance gate: an explicit ACCEPT, REJECT or BLOCKED for architecture, journeys, deep, page/data and the frozen bundle. Only material defects justify REJECT: a wrong conclusion, an impossible path, or a blocked core task. Declared limits, honest unavailable markers and the static nature of traces are not grounds for rejection;
  • use a bounded review budget; stop with REJECT/BLOCKED and retained evidence if unresolved. Re-review the exact built artifact, not a description of it.

Gate: all frozen bundle artifacts are accepted by independent review. Never manufacture paths to meet a sampling quota.

Phase 7: Publish and report

Tell the user what is in the page, with real counts:

  • functions, decisions, journeys and traced outcomes;
  • how many outcomes are unavailable, and why;
  • what was cross-reviewed.

Report limits plainly.

Scripts

ScriptPurpose
census.pyMulti-language definition census (the coverage denominator)
scaffold_deep.pyDraft function-level map from the census and the architecture
merge_deep.pyMerge part maps; reconcile IDs by file and line
validate.pyEvery gate: schema, references, coverage, silent jumps, successors, selector consistency
build_site.pyExport the compact Code view data and build the single-page site
record_journey.example.mjsPlaywright starter for real-screen journey videos

The Python scripts require Python 3.9+ and only the standard library. Optional .mjs browser/recording helpers require a separately available Playwright. The page uses no frameworks or external requests.

Related Skills