Skip to content
APEX

Architecture Explorer

The Architecture Explorer is a live map of every moving part in APEX — agents, subagents, skills, instructions, prompts, validators, CI workflows, and MCP servers — with the relationships between them.

The graph is regenerated from source files (.github/agents, .github/skills, .github/instructions, .vscode/mcp.json, package.json, and more) on every site build, so category counts always reflect the current repo state — never hard-coded.

The explorer ships two readable lenses over that data:

  • Workflow Timeline — Step 1 → Step 7 as horizontal cards with the agent, model, primary skills, and gates between them. Best for storytelling and onboarding.
  • Agent Grid — searchable, filterable card grid of every agent, subagent, skill, instruction, validator, and MCP server. Best for reference and deep linking.

Click any card to open a side drawer with the full edge list (skills used, subagents called, hand-off targets, incoming + outgoing edges) and a deep link to the source file on GitHub.

Switch between Workflow Timeline and Agent Grid with the toggle in the top bar. Press / to focus the search box; Esc to close the detail drawer.

Open full screen ↗

How to use the explorer

Section titled “How to use the explorer”

Pick the lens that matches your goal:

  • New contributor — start with the Workflow Timeline to see the Step 1 → 7 flow at a glance, then drill into any agent.
  • Architect / reviewer — switch to the Agent Grid, filter to agent and subagent, and click a card to see exact hand-off and delegation edges.
  • Skill builder — Agent Grid with skill + instruction filters shows the knowledge layer; cross-reference with Skills & Instructions.
  • CI maintainer — Agent Grid with workflow + validator filters shows which hooks back which scripts.

Node categories

Section titled “Node categories”

Colours come straight from the generated graph JSON, so the legend in the explorer is always authoritative. The categories tracked are:

  • Agent, Subagent, Skill, Instruction, Prompt, Validator, CI Workflow, MCP Server.

Edge semantics

Section titled “Edge semantics”

| Edge kind | Meaning | | ------------ | ----------------------------------------------------------- | | handsOff | Workflow hand-off between agents (handoffs: frontmatter). | | delegates | Agent delegates to a subagent (agents: frontmatter). | | usesSkill | Agent uses a primary skill (always loaded). | | usesSkill? | Agent uses a secondary skill (on-demand). | | invokes | Prompt invokes an agent (name-matched). | | appliesTo | Instruction applies to an agent/skill/prompt type. | | runs | CI workflow runs a validator (npm run …). | | usesMcp | Agent uses an MCP server (referenced in body). | | references | Skill references another skill (e.g. routing/delegation). |

Hover any card to see its name and category; click to open the detail drawer with the full edge list.

Data source

Section titled “Data source”

Both explorer views consume site/public/architecture-explorer-graph.json, generated by node tools/scripts/generate-explorer-graph.mjs (wired into the site prebuild hook) and validated by npm run validate:explorer-graph. If the data looks stale, run the generator locally and commit the result.

Next steps

Section titled “Next steps”