Architecture Graph Journal Skill

What this skill does

Systematically build an architecture knowledge graph of a software system: a hierarchical component index where every node has a description (what the component IS) and a design document (HOW it works, its security posture, and operational profile). The output is concern-aware — design documents have sections per architectural concern (architecture, security, operations) with structured metadata for filtering.

The process is iterative: explore one level of the tree at a time, running a 6-step pipeline per level, then descend. Branches terminate when agents report STOP (leaf node). The process completes when all branches reach their leaves.

This is a slow, methodical process. Quality comes from systematic steps, not from trying hard in a single pass. Each step has one job. Exploration and editorial judgment are separate. Expect multiple conversations to complete a full knowledge graph.

Invocation

/architecture-graph setup — First-time scaffolding: create the working directory, copy templates, discover the project's architecture and technology landscape, identify level-0 components.
/architecture-graph continue — Resume from where the journal left off. Read _meta/journal.md to determine current level/step, then execute the next step.
/architecture-graph status — Report current progress from the journal without executing anything.

Setup phase

Run this once per project. It creates the scaffolding and does initial discovery.

1. Scaffold the working directory

Create an architecture-graph/ package (or directory) in the project with this structure:

architecture-graph/
├── _meta/
│   ├── pipeline.md       # Copy from ${CLAUDE_SKILL_DIR}/pipeline.md
│   ├── design-spec.md    # Copy from ${CLAUDE_SKILL_DIR}/design-spec.md
│   └── journal.md        # Initialize from template below
├── components/           # All nodes live here
└── index.md              # Entry point (created after level-0 skeleton)

Copy pipeline.md and design-spec.md from the skill directory into _meta/. These are the canonical process definitions — read them before doing anything else.

2. Discover the architecture taxonomy

Investigate the project's technology landscape, infrastructure, and security surface. Search for:

Services: What processes run in production? Look at deployment manifests, Docker/K8s configs, package.json scripts, process managers.
Infrastructure: What backing services exist? Databases, caches, queues, object stores, CDNs.
Tech stack: Frameworks, languages, major libraries. Look at package files, imports, build config.
Security controls: Authentication mechanisms, authorization enforcement, encryption, secrets management. Search for auth middleware, policy engines, TLS config, secret stores.
Protocols: How do components communicate? HTTP, gRPC, WebSocket, message queues, pub/sub.
Data classification: What sensitive data exists? PII, credentials, tokens, financial data.

Record findings in the pipeline.md architecture taxonomy section, replacing the placeholder values with project-specific ones.

3. Discover level-0 components

Launch an Explore agent to identify the top-level architectural domains of the system. Look at:

Monorepo/project structure (what are the major packages/services?)
Deployment topology (what runs where?)
Infrastructure definitions (K8s manifests, IaC, docker-compose)
The system's own documentation or README
Major subsystem boundaries (auth, data pipeline, API layer, worker processes, UI)

Propose 5-12 level-0 components. Each should be a major architectural domain — a service, subsystem, or infrastructure layer, not an individual function or config file. Confirm with the user before proceeding.

4. Initialize the journal

# Architecture Graph Journal

> Process definition: see `pipeline.md`
> Step 4 agent spec: see `design-spec.md`

## Status

**Current level:** 0
**Current step:** 1 (skeleton)
**Step status:** pending

## Level 0 Nodes

| Node | Component | Design | Children |
|------|-----------|--------|----------|

## Next Action

**Step 1:** Create level-0 skeleton.

## Log

- **{date}** - Architecture graph scaffolded. Level 0 components identified.

5. Create level-0 skeleton

Create a folder under components/ for each level-0 component with a minimal component.md:

---
title: {Component Name}
concerns:
  tech_stack: []
  protocols: []
  data_stores: []
  services: []
  infra: []
  security_controls: []
  data_classification: null
  custom: []
  notes: |
    To be determined.
---

# {Component Name}

{One-line description from discovery.}

Create index.md linking to all level-0 components. Update the journal.

The Pipeline (6 steps per level)

Read _meta/pipeline.md for the full specification. Below is the orchestration guide — what YOU do as the orchestrator for each step.

Step 1: Skeleton

You do this directly. Create folders with minimal component.md files from the children listed in parent pages. No agents needed.

Step 2: Draft (exploratory)

Launch Explore agents — one per node, in waves by parent family.

Before each wave:

Read the parent's component.md for context
Launch an Explore agent to find relevant code paths (services, packages, config, infra) for all children in the family
Launch one Explore agent per child with: the step 2 prompt template (from pipeline.md), sibling context, parent description, and investigation hints from the code exploration

Collect all results before moving to the next wave. Agents return text only — they do NOT write to files.

Critical execution rules:

One agent, one node. Never combine multiple nodes into a single agent.
Launch in waves by parent family (all siblings together). Collect results before next wave.
Give each agent specific file paths to investigate, not just directory names.

Step 3: Refactor (convergent)

Phase A — You make editorial decisions. Review ALL drafts together across the entire level:

Deduplicate children that appeared under multiple parents
Merge nodes that describe the same thing differently
Move children to better parents if misplaced
Decide which proposed children are too granular (individual functions, config keys, single files → mark as STOP)
Ensure each node has a clear architectural boundary

Phase B — Write second drafts to files. Either launch agents or write directly based on your editorial decisions. Include proper frontmatter, architecture metadata, wikilinks to related components, and clean boundaries.

Common pattern: Most proposed level-2+ children are too granular. If a child is a single function, a config key, a utility module, or a build step, it's not a component — it belongs in the parent's description. Be aggressive about STOP.

Step 4: Design Document

Launch general-purpose agents — one per node, in waves by parent family.

Each agent receives the assembled prompt from _meta/design-spec.md with these variables filled:

{node_name} — the component name
{component_content} — the component.md content
{component_file_path} — path to component.md (for frontmatter update)
{design_file_path} — path to design.md (to write)
{source_paths} — source code directories to investigate
{infra_paths} — infrastructure/deployment files to investigate

Each agent:

Investigates the implementation in the codebase (source code, patterns, data flow, interfaces)
Investigates security posture (auth, validation, encryption, secrets, data handling, trust boundaries)
Investigates operational characteristics (deployment, scaling, config, monitoring, failure modes)
Writes design.md with concern-based sections
Updates component.md frontmatter with refined architecture metadata

This is the most important step. The design agents produce the highest-value content. Give them good investigation hints — the pre-exploration from step 2 should have identified the relevant code paths, config files, and infrastructure definitions.

Step 5: Link

You do this directly. Add [[wikilinks]] to related nodes across the tree. Focus on meaningful relationships: "depends on", "feeds data to", "secured by", "deployed with", "configured by", "see also". Don't over-link. Every node should have at least one cross-reference.

Step 6: Review

Launch general-purpose agents — one per parent family.

Each agent reads ALL files in its family (parent component.md + design.md, all children component.md + design.md) and checks:

Structural consistency (frontmatter format, required fields, sections match H2 headings)
Self-containment (no design section references another section)
Evidence basis (claims cite specific code paths, config, or infrastructure)
Terminology consistency across siblings
No duplication between siblings
Parent bubble-up (update parent if children revealed corrections)
Dependency consistency (if A says it depends on B, B should acknowledge A)
Frontmatter arrays consistent ([] not {})

Agents fix issues directly and report what they changed.

After all 6 steps

Update the journal. If any nodes have children (not STOP), begin the next level at step 1. If all nodes are leaves, the level is complete. If all levels are complete, the architecture graph is done.

Quality Principles

These are the invariants that prevent the most common failure modes:

One agent, one node. Never combine multiple nodes into a single agent. If parallelism is constrained, run sequentially. Quality over speed.
Implementation before opinion. Design agents must investigate actual code, config, and infrastructure before writing architectural descriptions. Document what IS, not what you think should be.
Self-contained sections. Each concern section in a design document must stand on its own. A security reviewer reading the Security section must never need to read the Architecture section. Do not write "as described above" or reference another section's content.
Descriptive metadata. Concern tags are for filtering and audit, not runtime enforcement. Tag every relevant technology, control, service, and protocol. Use the notes field for actual architectural context in natural language.
Draft then refactor. Exploration (step 2) and editorial judgment (step 3) are separate steps. Let agents explore freely, then converge with human judgment.
STOP means leaf. An agent reports STOP when there are no meaningful children. Most nodes at depth 2+ will be leaves. Be aggressive about STOP — individual functions, config keys, utility modules, and build steps are not components.
Sibling context prevents duplication. Always give agents their siblings' titles and descriptions so they don't duplicate content that belongs elsewhere.
The journal is the state. Every step updates the journal. This is how you resume across conversations. Never skip the journal update.

Common Pitfalls

| Pitfall | Symptom | Fix | |---------|---------|-----| | Over-granular children | Agents propose "JWT Validation", "Session Cleanup", "Token Refresh" as separate components | These are implementation details of the parent. Mark STOP. | | Siblings as children | Agent lists "Redis Cache" and "PostgreSQL" as children of "Session Management" | Those are sibling infrastructure components, not children. Remove from children list. | | Cross-references as children | Agent lists "API Gateway" as child of "Authentication" | That's a dependency, not a child. Use a [[wikilink]] instead. | | Shallow investigation | Step 2 agent returns a generic description without referencing specific code | The agent lacked good investigation hints. Pre-explore to find specific file paths. | | Speculative architecture | Design doc describes what "should" be rather than what IS | Implementation before opinion. Cite the code. If something is missing, say so. | | Additive design sections | Security section says "In addition to the architecture described above..." | Self-containment violation. Rewrite to be complete on its own. | | Lost state | "Where were we?" at the start of a new conversation | Read the journal first. It records the current level, step, and status. | | Batching nodes | Combining 3 nodes into one agent "for efficiency" | Violates one-agent-one-node. Each node gets its own dedicated agent. |

File Structure Conventions

components/
├── authentication/
│   ├── component.md          # Component description
│   ├── design.md             # Architecture, security, operations
│   ├── session-management/   # Child of authentication
│   │   ├── component.md
│   │   └── design.md
│   └── ...

Every node is a folder with component.md + design.md.
Children are subfolders. Adding children = add a subfolder. No restructuring.
Frontmatter carries metadata the filesystem can't express: concerns, title, sections map.
[[wikilinks]] are cross-references (graph edges between related components), NOT tree edges (the tree is the folder structure).

Design Document Content Design

Each design document covers the component's architectural concerns, with sections mapping to their primary audiences:

Architecture — How does it work? Data flow, patterns, interfaces, key decisions. (developers)
Security — How is it secured? Controls, data classification, threats, compliance. (security reviewers)
Operations — How is it run? Deployment, monitoring, scaling, failure modes. (operators/SRE)

When to include a section:

Architecture: Always present. Every component has an implementation worth documenting.
Security: Present when the component handles sensitive data, enforces auth, accepts external input, or crosses trust boundaries.
Operations: Present when the component has its own deployment unit, scaling characteristics, or failure modes worth documenting.

When to omit: If a component has no meaningful security or operations concerns (e.g., a shared type definition package), omit those sections. A single Architecture section is fine.

Even single-section documents MUST have an explicit H2 heading (## Architecture).

Agent Skills: Architecture Graph Journal

Install this agent skill to your local

Skill Files