Skill: Architecture Intel

Overview

Extract and maintain a persistent architectural context scaffold in .claude/context/. Eliminates cold-start context loss across sessions by documenting stack, decisions, patterns, constraints, and conventions — each in its own file so agents load only what's relevant per task.

For backwards compatibility, .claude/architecture.md is maintained as a slimmed summary pointing to the full scaffold.

When to Use

• First session on a new-to-you project
• After major refactors, dependency upgrades, or architectural shifts
• Periodically (every few weeks) to keep context files current
• When onboarding a new stack or sub-project

Do NOT use for: small bug fixes, routine feature work where context files already exist and are current.

Process

Step 1: Detect Mode

Check the state of .claude/context/:

• .claude/context/ROUTER.md does not exist → First Run mode (full analysis, generate entire scaffold)
• ROUTER.md exists but is still an unfilled template → also First Run mode. The installer pre-seeds .claude/context/ with blank templates, so existence alone doesn't mean the scaffold is populated. Telltales: the Last updated header comment still reads YYYY-MM-DD, or the Context Files table shows Status "Template" for every file.
• ROUTER.md is populated → read the Last updated date from each context file's header comment
  • If user passed --full → Full Refresh mode
  • Otherwise → Incremental mode

Backwards compatibility: If .claude/architecture.md exists but .claude/context/ does not, treat as First Run mode. The monolithic file will be preserved as a reference during migration.

Step 2: Check Axon Availability

Run axon_list_repos to check if the current repo is indexed.

• Axon available → use the Axon analysis path (faster, more structural)
• Axon unavailable → use the file-read analysis path (still effective, just more manual)

Inform the user which path you're taking.

Step 3: Analyze the Codebase

With Axon:

1. axon_query with broad concept terms — "authentication", "error handling", "data models", "routing", "middleware" — to identify the major patterns in use
2. axon_context on key entry points (main URL conf, root app component, main router, etc.) to map the layer structure
3. axon_cypher for structural queries when needed — find all classes following a pattern, identify service layers, locate middleware chains
4. Read package manifests (requirements.txt, package.json, pubspec.yaml, go.mod) for stack and decision data

Without Axon:

1. Read CLAUDE.md and any existing project documentation for documented conventions
2. Read package manifests to identify stack and key dependencies
3. Identify entry points — glob for urls.py, app/layout.tsx, main.dart, main.go, index.ts, etc.
4. Read entry point files to understand the top-level structure
5. Glob for structural patterns: **/services.py, **/repositories.py, **/middleware.*, **/serializers.py, **/hooks/use*.ts
6. Read 2-3 representative examples of each discovered pattern
7. Infer decisions from dependency choices and configuration files

Incremental mode — both paths:

1. Run git log --since="[last-updated-date]" --stat --pretty=format:"%H %s" to identify what changed
2. If Axon available, run axon_detect_changes on the range for structural impact
3. Classify changed files to determine which context files need updating:
   • Config/manifest changes → architecture.md + decisions.md
   • New directories or apps → architecture.md + conventions.md
   • New service/pattern files → suggest adding a pattern to patterns/
   • New middleware, validators, exception handlers → architecture.md (constraints) + suggest pattern
   • Dependency additions/removals → decisions.md
4. Re-analyze only the code relevant to affected files
5. Skip context files whose underlying code did not change

Step 4: Extract Architecture

For each category, extract concrete, specific findings — not generic descriptions. Every bullet should be grounded in what the code actually does.

For architecture.md (.claude/context/architecture.md):

For decisions.md (.claude/context/decisions.md):

For conventions.md (.claude/context/conventions.md):

For patterns/ (.claude/context/patterns/):

When a recurring structural pattern is discovered, create a pattern file following the format in patterns/README.md. Only create pattern files for significant, reusable patterns — not every code convention.

Multi-stack projects: Detect multiple sub-projects (look for multiple package manifests at different directory levels, or sub-project directories in CLAUDE.md). Keep Decisions flat (project-wide). Give Conventions and Patterns per-stack subsections:

## Naming
### Backend (server/)
- ...
### Frontend (web/)
- ...

Step 5: Write or Update Context Files

First Run:

1. Ensure the .claude/context/ structure exists. The installer usually pre-seeds it with blank templates (ROUTER.md, decisions.md, conventions.md, patterns/README.md) — fill those in place. If a file is missing, create it using the formats in Step 4 with a <!-- Generated by /intel. Last updated: YYYY-MM-DD --> header comment and a ## Manual Notes section at the bottom.
   • Create architecture.md with extracted Stack, Architecture Overview, Constraints, Key Entry Points
   • Fill decisions.md with extracted decisions (replace placeholder entries)
   • Fill conventions.md with extracted conventions by category
   • Create any patterns/*.md files for significant patterns discovered
2. Set the Last updated date to today in each file's header comment
3. Generate ROUTER.md (see Step 5b)
4. Write .claude/architecture.md as a slimmed summary — same Stack/Overview/Constraints/Entry Points sections plus a pointer to context/ — this maintains backwards compatibility

Full Refresh (--full):

1. Re-analyze the entire codebase (same as First Run analysis)
2. Rewrite all context files with fresh findings
3. Preserve the ## Manual Notes section and everything below it in each file that has one
4. Regenerate ROUTER.md (see Step 5b)
5. Update .claude/architecture.md summary
6. Update Last updated dates

Incremental:

1. Read all existing context files in .claude/context/
2. Update only the files identified in Step 3 as affected by recent changes
3. Do NOT rewrite files whose underlying code hasn't changed
4. NEVER modify ## Manual Notes sections or anything below them
5. If a new pattern is discovered, create a new patterns/*.md file and regenerate ROUTER.md
6. Update Last updated dates only on files that were modified
7. Update .claude/architecture.md if the architecture summary changed

Step 5b: Generate ROUTER.md

After writing or updating context files, rebuild ROUTER.md:

1. Read the current ROUTER.md (or use the template for first run)
2. Update the Context Files table:
   • List every file in .claude/context/ (except ROUTER.md itself)
   • List every patterns/*.md file individually
   • Set Status to "Populated" for files with content, "Template" for empty ones
3. Update the Task Routing table if new pattern files warrant specific routing (e.g., a "Testing Pattern" file should be listed under Debugging/Fixing tasks)
4. Keep ROUTER.md under 50 lines — it's a dispatch table, not a knowledge base

Step 6: Wrap Up

After writing/updating the files:

1. Summarize what was found or changed, listing which context files were created/updated
2. Note if anything looks unusual or worth the user's attention
3. Mention the drift detector: "You can check recent changes against these conventions by loading agents/drift-detector.md as a subagent."
4. Mention memory commands: "Use /remember to capture additional decisions, conventions, or patterns. Use /recall at the start of future sessions to load relevant context."

Quick Reference

Total token budget: The scaffold should be smaller in aggregate than the old monolithic architecture.md when only relevant files are loaded per task. ROUTER.md + one context file should be under 100 lines.

Common Mistakes

• Overwriting Manual Notes — never modify content after the ## Manual Notes heading in any context file
• Rewriting unchanged files — in incremental mode, only touch files affected by recent changes
• Generic descriptions — "uses a service layer" is useless. "Business logic in apps/*/services.py, views call service functions, never access ORM directly" is useful
• Too long — if any single context file exceeds its size target, trim aggressively. The point of the scaffold is to load less, not more
• Missing rationale in Decisions — "uses JWT" isn't a decision. "JWT over sessions: needed stateless auth for mobile clients" is
• Forgetting backwards compat — always update .claude/architecture.md alongside the scaffold so projects that haven't migrated still get a useful summary
• Bloated ROUTER.md — the router is a dispatch table. If it exceeds 50 lines, you're putting content in it that belongs in the context files