Agent-Skills.md

Agent Skills: Code Atlas Skill

|

UncategorizedID: rysweet/amplihack/code-atlas

Repository

rysweet/amplihack
rysweet
4124

Install this agent skill to your local

pnpm dlx add-skill https://github.com/rysweet/amplihack/tree/HEAD/.claude/skills/code-atlas

Skill Files

Browse the full folder contents for code-atlas.

Download Skill

Loading file tree…

.claude/skills/code-atlas/SKILL.md

Skill Metadata

Name
code-atlas
Description
|

Code Atlas Skill

Purpose

Build exhaustive, regeneratable architecture atlases directly from code truth. A code-atlas is a living document set: diagrams, graphs, and inventory tables that form a navigable map of any codebase. Atlas-building is investigation: structured reasoning about code in graph form reveals structural bugs, API contract mismatches, and architectural drift that linear code review misses.

An atlas is complete when any engineer, given only the atlas and a bug report, can trace the full execution path without opening the source code.

Layer Overview

Layer definitions are the single source of truth in LAYERS.yaml. All references below use slugs from that file.

| Slug | Name | Description | Recommended Diagram Type | |------|------|-------------|--------------------------| | repo-surface | Repository Surface | All source files, project structure, build systems | Mermaid flowchart TD | | ast-lsp-bindings | AST+LSP Symbol Bindings | Cross-file symbol references, dead code, interface mismatches | Mermaid flowchart LR or DOT digraph | | compile-deps | Compile-time Dependencies | Package imports, dependency trees, circular deps | DOT digraph (handles large trees better) | | runtime-topology | Runtime Topology | Services, containers, ports, inter-service connections | DOT digraph with subgraph clusters | | api-contracts | API Contracts | HTTP routes, gRPC, GraphQL, middleware chains | Mermaid flowchart TD | | data-flow | Data Flow | DTO-to-storage chains, transformation steps | Mermaid flowchart LR | | service-components | Service Component Architecture | Per-service internal module/package structure | Mermaid graph TD (one per service) | | user-journeys | User Journey Scenarios | End-to-end paths from entry to outcome | Mermaid sequenceDiagram |

Per-Layer Scope Guidance

| Slug | Scope Target | |------|-------------| | repo-surface | Top-level directories and build entry points. Do not enumerate every file. | | ast-lsp-bindings | Exported symbols and their cross-file references. Focus on public API surface. | | compile-deps | Direct dependencies and one level of transitive. Include version constraints. | | runtime-topology | All deployed services, their ports, and inter-service protocols. | | api-contracts | Every HTTP/gRPC/GraphQL endpoint with auth, DTOs, and middleware. | | data-flow | Primary read/write paths per service. Skip internal caching flows unless relevant. | | service-components | Top-level packages/modules within each service. Show coupling edges. | | user-journeys | Derive from api-contracts routes + pages/CLI entries. Trace 3-8 key journeys. |

Skill Delegation Architecture

code-atlas (this skill)
  Responsibilities:
    - Atlas layer orchestration (all 8 layers)
    - Language-agnostic code exploration
    - Three-pass bug-hunting workflow
    - Staleness detection triggers
    - Density management (split, not prompt)
    - Publication workflow (GitHub Pages, mkdocs, SVG)

  Delegates to:
    code-visualizer skill       Python AST module analysis (compile-deps + service-components fallback)
    mermaid-diagram-generator   Mermaid syntax generation and formatting
    lsp-setup skill             Layer ast-lsp-bindings: LSP-assisted symbol queries (optional)
    visualization-architect     Complex DOT graph rendering and cross-layer layouts
    analyzer agent              Deep codebase investigation and dependency mapping
    reviewer agent              Contradiction hunting (Passes 1, 2, 3)

When to Use This Skill

| Trigger | Use Case | |---------|----------| | Starting work on an unfamiliar codebase | Full atlas build before coding | | Onboarding a new engineer | Share atlas as navigation guide | | Before a major refactor | Map current state; plan changes against topology | | Bug hunt stalled | Pass 1 + Pass 2 bug-hunting through graphs | | Docs feel stale | Staleness check + targeted rebuild | | Adding CI/CD quality gate | Register atlas freshness checks | | Publishing documentation site | GitHub Pages / mkdocs publication workflow | | Reviewing an unfamiliar PR | PR impact view using diff against current atlas |

Quick Start

# Build a full atlas
User: Build a complete code atlas for this repository

# Run bug hunting
User: Run code atlas bug hunting passes on this service

# Check freshness
User: Are our architecture diagrams still accurate?

# Publish
User: Publish our code atlas to GitHub Pages

Why Both Mermaid and Graphviz

The skill defaults to building atlas diagrams in both formats because they find different bugs. A controlled experiment across 7 repos showed only ~15% overlap in bugs found -- running both finds ~1.7x the bugs of either alone. The different syntax forces different reasoning paths through the same code. Evidence is documented in PR #3221.

The user can override to a single format:

User: Build a code atlas using only Mermaid
User: Build a code atlas in DOT format only

Diagram Density Policy

There are no hard node/edge limits. Instead:

If a diagram would be unreadably dense, split into sub-diagrams by package or service boundary. In batch mode, auto-group without prompting the user. Each sub-diagram should target 15-40 nodes for readability.

For example, a runtime-topology diagram with 80 services should be split into sub-diagrams by domain (e.g., runtime-topology-payments.mmd, runtime-topology-auth.mmd) plus one high-level overview diagram showing inter-domain connections.

A table is only produced as a companion to a diagram, never as a replacement.

Recipe: 12-Phase Atlas Build

The atlas build follows these phases in order:

  1. Validate Prerequisites -- Check tools (mmdc, dot, kuzu), detect LSP mode
  2. Build Layers 1-4 (structural) -- repo-surface, ast-lsp-bindings, compile-deps, runtime-topology
  3. Build Layers 5-8 (behavioral) -- api-contracts, data-flow, service-components, user-journeys
  4. Verify All 8 Layers -- Hard gate: every slug must have .mmd + .dot + rendered .svg + README with embedded images
  5. Bug Hunt (Mermaid arm) -- 3-pass hunt using only .mmd diagrams
  6. Bug Hunt (Graphviz arm) -- 3-pass hunt using only .dot diagrams (parallel with step 5)
  7. Merge Findings -- Deduplicate across both arms
  8. Multi-Agent Validation -- 3 specialists vote independently; threshold >= 2/3 to confirm
  9. File Issues -- Validated bugs filed as GitHub issues (never stored in atlas)
  10. Kuzu Ingestion + OpenCypher -- Ingest to graph (REQUIRED) + generate standalone .cypher files
  11. Publish Atlas -- Render SVGs, write index, update mkdocs nav
  12. Final Checklist Review -- Independent reviewer verifies completeness of all deliverables

After each build phase, diagrams are written to docs/atlas/{slug}/ with .mmd source, .dot source, rendered *-mermaid.svg and *-dot.svg, and a README.md that embeds the SVGs inline using ![alt](file.svg) syntax.

Bug-Hunting Workflow Overview

The atlas is an active investigation tool. Three passes transform it from a map into a high-confidence bug-detection engine. Each pass runs in a fresh context window to prevent anchoring bias.

  • Pass 1 (Comprehensive Build + Hunt): Build all layers, then systematically hunt contradictions between them. Route/DTO mismatches, orphaned env vars, dead runtime paths, stale doc references.
  • Pass 2 (Fresh-Eyes Cross-Check): A new context window re-examines the atlas independently. Confirms, overturns, or escalates Pass 1 findings.
  • Pass 3 (Scenario Deep-Dive): Every user-journeys journey is traced end-to-end through api-contracts, data-flow, runtime-topology, service-components, and ast-lsp-bindings. Each journey receives a verdict: PASS, FAIL, or NEEDS_ATTENTION.

Full checklists, templates, and output formats: bug-hunt-guide.md

Layer 8: ast-lsp-bindings Operating Modes

Layer ast-lsp-bindings operates in one of two modes, always labelled on line 1 of its README:

| Mode | Trigger | Mechanism | |------|---------|-----------| | lsp-assisted | lsp-setup reports active LSP server | Delegates symbol queries to LSP | | static-approximation | LSP unavailable | ripgrep + code-visualizer AST |

The mode label is never absent, never defaulted silently.

Output Structure

docs/atlas/
  index.md
  staleness-map.yaml
  {slug}/
    README.md          (embeds SVG diagrams inline with ![alt](file.svg))
    *-mermaid.svg      (rendered Mermaid diagrams)
    *-dot.svg          (rendered Graphviz diagrams)
    *.mmd              (Mermaid source)
    *.dot              (Graphviz source)
    inventory.md       (where applicable)
  cypher/
    schema.cypher      (CREATE NODE/REL TABLE statements)
    atlas-layers.cypher
    atlas-services.cypher
    atlas-bugs.cypher
    atlas-relationships.cypher
    queries.cypher     (ready-to-run example queries)

Three non-negotiable output rules:

  1. Bug hunt results are never stored in the atlas. All findings are filed as GitHub issues with the code-atlas-bughunt label.
  2. Kuzu ingestion is required, not optional. If Kuzu is unavailable, fail loudly and attempt to fix (install kuzu package). Never silently skip.
  3. OpenCypher .cypher files are always generated alongside Kuzu ingestion for portability to any graph database.

Staleness Detection

Staleness triggers are defined per-layer in LAYERS.yaml as glob patterns. When git diff matches a trigger pattern, the corresponding layer is marked stale.

Full trigger table, rebuild commands, and incremental rebuild strategy: reference.md

CI Integration

Three GitHub Actions patterns are available:

  1. Post-merge staleness gate with auto-commit
  2. PR impact check with layer annotations
  3. Scheduled weekly full rebuild with issue creation on failure

Full workflow YAML and configuration: publication-guide.md

Publication

Outputs GitHub Pages-ready docs/atlas/ structure. Compatible with mkdocs-material and plain GitHub Pages. SVGs are committed so no render step is needed at read time.

SVG generation commands, mkdocs integration, and deployment workflows: publication-guide.md

Diagram Examples

Per-layer Mermaid and DOT examples with recommended diagram types: examples.md

Security Controls

All security controls (SEC-01 through SEC-19) are defined in SECURITY.md. Key controls:

  • Secret values never emitted (env files parsed for key names only)
  • Path traversal prevented via realpath() boundary validation
  • Mermaid/DOT/SVG labels sanitized (XSS prevention)
  • Bug report code quotes redacted of credential patterns
  • All file:line references use relative paths (SEC-16)

API Contracts

Typed contracts for all skill delegations and filesystem layout: API-CONTRACTS.md

Reference

Error codes, Kuzu ingestion schema, staleness trigger table: reference.md

Success Criteria

A complete atlas satisfies:

  • All 8 layers produced with diagrams in docs/atlas/{slug}/
  • Both DOT and Mermaid source files present (unless user requested single format)
  • SVG renders alongside source files
  • Bug hunt findings filed as GitHub issues (never stored in atlas docs)
  • Every filed bug includes: layer reference, file path, line number, code evidence
  • No orphaned nodes in diagrams
  • ast-lsp-bindings README states mode on line 1

Limitations

  • Not a static analysis tool: Uses grep, AST, config parsing -- not a compiler
  • Staleness is heuristic: Git diff pattern matching, not semantic analysis
  • Python AST delegation: Python module graphs delegate to code-visualizer (Python-only)
  • SVG rendering requires Graphviz/Mermaid CLI: CI environments need these installed
  • Bug hunting is probabilistic: Human review required before filing
  • Single-repository focus: Cross-repo deps require manual configuration
  • No runtime instrumentation: Call frequencies and latency require APM tools

Remember

Diagramming is investigation, not just documentation.

The most valuable output of a code atlas is the bugs and contradictions discovered while reasoning about the system in graph form.

Five rules that are never negotiable:

  1. No silent diagram-to-table substitution. If density is high, split into sub-diagrams.
  2. Mode is always visible. ast-lsp-bindings README always states its mode on line 1.
  3. Three-pass bug hunting. Pass 1 hunts. Pass 2 validates. Pass 3 verdicts per journey.
  4. Bugs go to issues, never the atlas. The atlas is a living architecture doc, not a bug report.
  5. Kuzu is required, not optional. Never silently skip graph ingestion. Fail loudly and fix.

Rebuild from code truth. Hunt contradictions. File evidence-backed bugs. Repeat.