architecture-map

name	architecture-map
description	Use when the user asks to generate or refresh an architecture map, structure diagram, core call flow, local viewer assets, or runs ~map. Produces hello-scholar native architecture-map.json plus compact Markdown and Mermaid companion artifacts.

Architecture Map

Mission

Generate a native hello-scholar architecture map that helps a human understand the codebase. The output is not a decorative diagram and not an exhaustive file tree. It is an evidence-backed, perspective-driven, recursively explorable mental model.

Hard Boundaries

• Write only under hello-scholar/architecture/ unless the user explicitly requests another export destination.
• Use hello-scholar/architecture/architecture-map.json as the source of truth.
• Honor the requested content language from ~map --lang zh|en or the user choice made by ~map. Record it as project.language. In Chinese mode, write human-facing summaries, titles, flow actions, diagnostics, and Markdown prose in Chinese, while keeping stable IDs, paths, commands, APIs, package names, schema enum values, profile IDs, skill IDs, and code symbols in their original English/code form.
• Treat Markdown, Mermaid, and exported HTML as companion or derived artifacts.
• Follow the native architecture boundary in ../references/native-boundaries.md; this skill writes hello-scholar native assets only.
• Do not read .env secrets. Record only safe config shape or .env.example.
• If hello-scholar/ is not initialized, ask the user to run ~init or hello-scholar init before writing project assets.
• Keep CLI boundaries clear: semantic scanning happens in the agent/skill, while hello-scholar map validate/view/export/status only operates on existing map assets.
• Keep ownership clear: subagents may return architecture findings or write temporary drafts under /tmp/hello-scholar-agent-drafts/<task-id>/ when explicitly assigned, but the main agent owns final writes to hello-scholar/architecture/.

Load References

Read these references before generating the map:

• ../references/native-boundaries.md
• references/map-generation-protocol.md
• references/perspective-catalog.md
• references/recursive-analysis-playbook.md
• references/architecture-map-schema.md
• references/diagram-guidelines.md
• references/evidence-guidelines.md
• references/golden-examples.md

Load only the sections needed for the repository type after the initial reconnaissance.

Generation Workflow

1. Establish the repository fingerprint.
   • Inspect high-signal files, manifests, catalogs, entrypoints, tests, and runtime configuration.
   • Identify whether the repo is CLI, web/API, ML/research, data pipeline, plugin/agent, background worker, library, or mixed.
   • Record ignored paths and included source anchors in sources.
   • Populate the optional onboarding block with a project brief, project types, primary entrypoints, run/test/build notes, core flows, and risk tag legend when evidence supports them.
   • For maps intended for human onboarding, also populate an evidence-backed project understanding path when the repository has enough signal: mentalModel, readingPath, conceptGlossary, keyJourneys, architectureLayers, and nextDrilldowns. Keep these compact and link them to existing views, flows, lenses, nodes, or evidence instead of inventing a second source of truth.
   • Create a surface inventory before choosing diagrams. Track important repo surfaces, their evidence paths, and whether each surface will be represented as covered, summarized, missing, or not applicable.
   • For mixed or large repositories, split reconnaissance by independent surfaces and strongly consider parallel architecture-cartographer subagent assignments such as CLI/commands, web/API/UI/TUI, runners/connectors/providers, state/artifacts/tests, plugin/skill/agent workflow, or data/experiment pipeline.
   • Subagent assignments must be read-only or draft-only. They return Surface Coverage Inventory, candidate nodes/edges/flows, unknowns, and suggested drilldowns; the main agent merges, deduplicates IDs, judges confidence, and writes final map assets.
   • For mixed or large repositories, do not treat one high-level node as sufficient coverage for an entire runtime family. If a surface is only summarized, either create a child view or record a coverage gap.
2. Select perspectives and optional lenses deliberately.
   • Always create overall-architecture.
   • Add only perspectives with concrete code evidence.
   • Use repo-type signals from perspective-catalog.md; do not force empty perspectives.
   • Add optional lenses[] only when the repository type makes them useful: CLI, web/API, ML/research, data pipeline, library, worker, or plugin/skill/agent.
   • Map repository types to lens families explicitly: CLI -> command lifecycle; Web/API -> request lifecycle; ML/research -> experiment, data, and artifact flow; Library -> public API and dependency boundary; Plugin/Skill/Agent -> skill workflow, agent dispatch, and command routing.
   • For every enabled lens, create at least one useful linked view or flow. A lens without linked evidence-backed views/flows is incomplete.
   • Treat skill workflow, agent dispatch, and command routing as the plugin-skill-agent lens, not as a universal default.
   • When the plugin-skill-agent lens is enabled, create a first-class Project Lens Map experience for the viewer: the lens should render skill workflow, agent dispatch, command routing, and reference loading as a focused graph linked to views and flows such as skill-workflow, skill-system, command-routing, agent-dispatch, and skill-reference-loading when those concepts exist.
   • Keep skill, command, and agent views out of the general Architecture Map canvas. Put them under the Project Lens Map plugin-skill-agent lens so the main map stays useful for ordinary system architecture.
   • Populate optional skillWorkflow.catalog when evidence exists. Use generated skill/agent catalogs when available, and scan command skill directories such as skills/commands/*/SKILL.md when command skills are intentionally excluded from the generated skill catalog.
   • Exclude generated/runtime project asset directories from skillWorkflow.catalog: never record hello-scholar/, .hello-scholar/, hello-scholar/architecture/, .git/, node_modules/, build outputs, caches, or map export directories as skill, command, agent, hook, evidence, or catalog sources.
   • For important individual skills, commands, or agents, summarize their internal workflow as trigger -> boundaries -> context discovery -> reference/script/asset loading -> execution/output -> validation/self-check. Keep this generic for Codex, Claude Code, and other plugin runtimes; do not hard-code hello-scholar unless the target repo is hello-scholar-like.
3. Build an evidence ledger before diagramming.
   • For each candidate node and edge, capture evidence path, optional line span, reason, and confidence.
   • Mark uncertain relationships as inferred or unknown immediately.
   • Use the claim ledger and promotion rules in map-generation-protocol.md.
4. Create the overview mental model.
   • Target 5 to 12 key concepts.
   • Show entrypoints, major modules, storage/config boundaries, and extension surfaces when they matter.
   • Build a newcomer reading path: start with the project purpose, then core concepts, then the most important end-to-end journeys, then lens or flow drilldowns.
   • Add onboarding.conceptGlossary only for concepts needed to understand this project, such as domain objects, runtime roles, artifacts, skill/agent terms, provider families, or state objects. Do not turn it into an API dictionary.
   • Add onboarding.keyJourneys for user-visible or maintainer-visible paths that cross multiple views or flows. Each journey should name the trigger, the outcome, and linked evidence-backed views or flows.
   • Avoid listing every directory.
5. Recurse through complex nodes.
   • For every overview node, decide leaf vs child view.
   • Create a child view when the node contains multiple meaningful internal modules or flows.
   • Treat complex overview nodes as a work queue, not as terminal boxes. Common examples include runner/provider adapters, connectors/channels, daemon route groups, UI workspace/plugin surfaces, data/experiment pipelines, storage/artifact services, public API surfaces, and skill/agent/prompt runtimes.
   • If a complex node is intentionally left as a leaf to preserve overview clarity, record summarized coverage in diagnostics with the exact missing child view candidate.
   • Stop drilling when another view would only restate filenames.
   • Preserve stable IDs so future diffs remain useful.
   • Use the work queue and stop-reason protocol in recursive-analysis-playbook.md.
6. Trace important flows.
   • Generate flows[] only for the most important startup, command, request, experiment, skill, or agent lifecycle present.
   • Keep numbered flow steps as primary facts; Mermaid sequence diagrams are rendering assets.
7. Write native assets.
   • hello-scholar/architecture/architecture-map.json with project.language when a generation language was selected
   • hello-scholar/architecture/views/*.md
   • hello-scholar/architecture/diagrams/*.mmd
   • hello-scholar/architecture/INDEX.md
   • Include evidenceCoverage when possible so the viewer can show confirmed, inferred, unknown, and missing-evidence claims.
   • Follow the deterministic write order in map-generation-protocol.md.
8. Validate and summarize.
   • Run hello-scholar map validate.
   • Run a map-quality self-review before calling the map complete: compare the surface inventory against generated views, lenses, flows, nodes, diagnostics, and any subagent findings that were accepted or rejected.
   • Report validation errors, warnings, unknowns, inferred edges, and suggested next verification.
   • Report important coverage gaps separately from structural validation warnings.
   • Suggest hello-scholar map view for local exploration.

Node And Edge Requirements

Every node must include:

• id, stable English kebab-case
• label, human-readable and concise
• kind, such as entrypoint, module, store, config, external, tool, test, artifact, profile, skill, agent, viewer
• summary, one evidence-backed responsibility statement
• paths, project-relative paths only
• evidence, at least one object unless truly external or unknown
• confidence, one of confirmed, inferred, unknown
• tags, sorted and useful for filtering

Every edge must include:

• id, stable English kebab-case
• from and to, both valid node IDs
• label, a meaningful verb phrase such as dispatches command, loads profile catalog, writes project assets
• kind, such as calls, reads, writes, loads, dispatches, renders, validates, exports, imports, owns
• evidence
• confidence

Quality Gates

Before calling the map done, check:

• overall-architecture explains the repo in 5 to 12 concepts.
• Every view has a clear question it answers.
• The onboarding block answers what the project is, who uses it, what enters it, what it produces, and which 3 to 6 map targets a newcomer should inspect first.
• Every readingPath step has a target object and a reason; avoid empty instructions such as "look at the architecture map" without a specific view, flow, lens, node, or evidence target.
• Every keyJourneys entry is grounded in existing flow/view/node evidence and names both trigger and outcome.
• Every view, lens, and flow summary works as graph-level reading guidance: what the graph answers, where to start, the main path to follow, and boundaries to notice.
• Every edge label explains why the relationship exists.
• Inferred edges include the reason for inference.
• Paths are relative and do not include secrets or absolute user paths.
• Mermaid diagrams render without excessive overlap or arrow spaghetti.
• architecture-map.json is deterministic: stable IDs, sorted arrays, stable diagram paths.
• The viewer can show project overview, run/test/build notes, optional lenses, views, flows, nodes, edges, evidence, confidence, and unknowns.
• For plugin/skill/agent repositories, the viewer can expose a clear Project Lens Map graph for skill workflow, agent dispatch, and command routing instead of hiding these details inside a generic list.
• Surface inventory is accounted for: every important repo surface is covered by a node/view/flow/lens, explicitly summarized with a drilldown candidate, marked missing, or declared not applicable with evidence.
• Complex subsystem nodes have child views when they materially improve onboarding. If they remain summarized, diagnostics explains why and what drilldown should be generated next.
• Map quality self-review has checked coverage, evidence, lens completion, graph readability, user-facing onboarding usefulness, and whether useful subagent findings were incorporated or explicitly rejected.

Failure Modes To Avoid

• Do not produce a shallow list of directories as an architecture map.
• Do not create one giant overview with every file.
• Do not let Mermaid text become the source of truth.
• Do not claim a call relationship without code/config/test evidence.
• Do not skip child views for complex subsystems just because the overview diagram already has a box.
• Do not mistake "mentioned in a node summary" for real coverage when a subsystem has its own entrypoints, lifecycle, state, tests, providers, or external boundary.
• Do not silently omit a detected project surface. Missing or summarized surfaces belong in diagnostics so the user can decide whether to refresh deeper.
• Do not add non-local sharing or account behavior to native architecture assets.
• Do not make the map hello-scholar-specific unless the target repository itself is hello-scholar-like.
• Do not promote plugin/skill/agent workflow visualization to the default model for ordinary CLI, web, ML, or library repositories.
• Do not skip the evidence ledger and write diagrams directly from first impressions.