Use when analyzing existing codebases to generate architecture documentation - coordinates subagent-driven exploration with mandatory workspace structure, validation gates, and pressure-resistant workflows
Coordinates subagent-driven exploration to generate comprehensive architecture documentation with mandatory workspace structure, validation gates, and pressure-resistant workflows. Use when analyzing existing codebases to produce C4 diagrams, subsystem catalogs, and architectural assessments.
/plugin marketplace add tachyon-beep/skillpacks/plugin install axiom-system-archaeologist@foundryside-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
analyzing-dependencies.mdanalyzing-test-infrastructure.mdanalyzing-unknown-codebases.mdassessing-code-quality.mdcreating-architect-handover.mddeliverable-options.mddocumenting-system-architecture.mdgenerating-architecture-diagrams.mdincremental-analysis.mdlanguage-framework-patterns.mdmapping-security-surface.mdspecialist-integration.mdvalidating-architecture-analysis.mdAnalyze existing codebases through coordinated subagent exploration to produce comprehensive architecture documentation with C4 diagrams, subsystem catalogs, and architectural assessments.
Core principle: Systematic archaeological process with quality gates prevents rushed, incomplete analysis.
You are a COORDINATOR, not an analyst. Your primary context is precious - preserve it for orchestration decisions, not detailed code reading.
| Task Type | Your Role | Subagent Role |
|---|---|---|
| Subsystem analysis | Spawn codebase-explorer | Read files, produce catalog entries |
| Validation | Spawn analysis-validator | Check contracts, produce reports |
| Diagram generation | Spawn diagram subagent | Generate Mermaid/PlantUML |
| Quality assessment | Spawn quality subagent | Analyze patterns, produce assessment |
| Security surface | Spawn security subagent | Map boundaries, flag concerns |
| Thought | Reality |
|---|---|
| "I'll just quickly read this file" | Spawn subagent. Your context is for coordination. |
| "It's faster if I do it myself" | Subagents preserve your context for later decisions. |
| "Only a few files to check" | "Few" files become many. Delegate from the start. |
| "I need to understand the code" | You need to understand the STRUCTURE. Subagents report findings. |
| "Spawning overhead isn't worth it" | Context exhaustion is worse. Always delegate detailed work. |
IMPORTANT: All reference sheets are located in the SAME DIRECTORY as this SKILL.md file.
When this skill is loaded from:
skills/using-system-archaeologist/SKILL.md
Reference sheets like subsystem-discovery.md are at:
skills/using-system-archaeologist/subsystem-discovery.md
NOT at:
skills/subsystem-discovery.md ← WRONG PATH
Before any analysis:
mkdir -p docs/arch-analysis-$(date +%Y-%m-%d-%H%M)/temp
Why this is mandatory:
Common rationalization: "This feels like overhead when I'm pressured"
Reality: 10 seconds to create workspace saves hours of file hunting and context loss.
After workspace creation, present deliverable options using AskUserQuestion tool.
See deliverable-options.md for the complete menu (Options A-G).
Key options:
Common rationalization: "User didn't specify, so I'll default to full analysis"
Reality: Always offer choice explicitly. Different needs require different outputs.
After documenting deliverable choice, write 00-coordination.md:
## Analysis Plan
- Scope: [directories to analyze]
- Strategy: [Sequential/Parallel with reasoning]
- Time constraint: [if any, with scoping plan]
- Complexity estimate: [Low/Medium/High]
## Execution Log
- [timestamp] Created workspace
- [timestamp] [Next action]
Common rationalization: "I'll just do the work, documentation is overhead"
Reality: Undocumented work is unreviewable and non-reproducible.
Before diving into details, perform systematic scan:
Write findings to 01-discovery-findings.md
Common rationalization: "I can see the structure, no need to document it formally"
Reality: What's obvious to you now is forgotten in 30 minutes.
Decision point: Sequential vs Parallel
Use SEQUENTIAL when:
Use PARALLEL when:
Common rationalization: "Solo work is faster than coordination overhead"
Reality: For large systems, orchestration overhead (5 min) saves hours of sequential work.
When spawning subagents for analysis:
Create task specification in temp/task-[subagent-name].md:
## Task: Analyze [specific scope]
## Context
- Workspace: docs/arch-analysis-YYYY-MM-DD-HHMM/
- Read: 01-discovery-findings.md
- Write to: 02-subsystem-catalog.md (append your section)
## Expected Output
Follow contract in documentation-contracts.md:
- Subsystem name, location, responsibility
- Key components (3-5 files/classes)
- Dependencies (inbound/outbound)
- Patterns observed
- Confidence level
## Validation Criteria
- [ ] All contract sections complete
- [ ] Confidence level marked
- [ ] Dependencies bidirectional (if A depends on B, B shows A as inbound)
After EVERY major document is produced, validate before proceeding.
temp/validation-[document].mdSelf-validation ONLY permitted when ALL conditions met:
If ANY condition is not met → SPAWN VALIDATION SUBAGENT. No exceptions.
| Excuse | Reality |
|---|---|
| "We have 45 minutes, no time for validation" | Validation takes 5-10 minutes. Spawn validator. |
| "I already reviewed it while writing" | Self-review ≠ validation. Spawn validator. |
| "I'll do systematic self-validation" | Multiple subsystems require independent validator. Spawn validator. |
| "Most work is already done" | Prior work must be validated. Spawn validator. |
| "Time pressure - I'll document limitations instead" | Documented limitations don't excuse skipping validation. Spawn validator. |
| "It's a simple codebase" | Simple ≠ correct. Spawn validator. |
When validator returns NEEDS_REVISION with CRITICAL issues:
DO NOT:
WRONG response: Skip workspace, skip validation, rush deliverables
RIGHT response: Scope appropriately while maintaining process
Example scoping for 3-hour deadline:
## Coordination Plan
- Time constraint: 3 hours until stakeholder presentation
- Strategy: SCOPED ANALYSIS with quality gates maintained
- Timeline:
- 0:00-0:05: Create workspace, write coordination plan
- 0:05-0:35: Holistic scan, identify all subsystems
- 0:35-2:05: Focus on 3 highest-value subsystems (parallel analysis)
- 2:05-2:35: Generate minimal viable diagrams (Context + Component only)
- 2:35-2:50: Validate outputs
- 2:50-3:00: Write executive summary with EXPLICIT limitations section
## Limitations Acknowledged
- Only 3/14 subsystems analyzed in depth
- No module-level dependency diagrams
- Confidence: Medium (time-constrained analysis)
- Recommend: Full analysis post-presentation
Key principle: Scoped analysis with documented limitations > complete analysis done wrong.
If user requests something genuinely impossible (e.g., "Complete 15-plugin analysis in 1 hour"):
Provide scoped alternatives:
A) Quick overview (1 hour): Holistic scan, plugin inventory, high-level diagram B) Focused deep-dive (1 hour): Pick 2-3 critical plugins, full analysis of those C) Use existing docs (15 min): Synthesize existing README.md, CLAUDE.md D) Reschedule (recommended): Full analysis takes 4-6 hours for this scale
DO NOT refuse entirely. Provide realistic scoped alternatives.
If you catch yourself thinking ANY of these, STOP:
| Excuse | Reality |
|---|---|
| "Time pressure makes trade-offs appropriate" | Process prevents rework. Skipping process costs MORE time. |
| "This feels like overhead" | 5 minutes of structure saves hours of chaos. |
| "Working solo is faster" | Solo works for small tasks. Orchestration scales for large systems. |
| "I'll just write outputs directly" | Uncoordinated work creates inconsistent artifacts. |
| "Validation slows me down" | Validation catches errors before they cascade. |
| "I already checked it" | Self-review misses what fresh eyes catch. |
| "I can't do this properly in [short time]" | You can do SCOPED analysis properly. Document limitations. |
| "Rather than duplicate, I'll synthesize" | Existing docs ≠ systematic analysis. Do the work. |
| "Meeting-ready outputs" justify shortcuts | Stakeholders deserve accurate info, not rushed guesses. |
For complex codebases, leverage specialist subagents from other skillpacks.
See specialist-integration.md for:
1. Create workspace (docs/arch-analysis-YYYY-MM-DD-HHMM/)
1.5. Offer deliverable menu (A/B/C/D/E/F/G) - user chooses scope
2. Write coordination plan (00-coordination.md) with deliverable choice
3. Holistic assessment → 01-discovery-findings.md
4. Decide: Sequential or Parallel? (document reasoning)
5. Spawn subagents for analysis → 02-subsystem-catalog.md
6. VALIDATE subsystem catalog (mandatory gate)
6.5. (Optional) Code quality assessment → 05-quality-assessment.md
6.6. (Optional) Security surface mapping → 07-security-surface.md
6.7. (Optional) Test infrastructure analysis → 09-test-infrastructure.md
6.8. (Optional) Dependency analysis → 10-dependency-analysis.md
7. Spawn diagram generation → 03-diagrams.md
8. VALIDATE diagrams (mandatory gate)
9. Synthesize final report → 04-final-report.md
10. VALIDATE final report (mandatory gate)
11. (Optional) Generate architect handover → 06-architect-handover.md
12. Provide cleanup recommendations for temp/
Every step is mandatory except optional steps (6.5-6.8, 11). No exceptions.
You have succeeded when:
You have failed when:
❌ Skip workspace creation "I'll just write files to project root"
❌ No coordination logging "I'll just do the work without documenting strategy"
❌ Work solo despite scale "Orchestration overhead isn't worth it"
❌ Skip validation subagent "I already reviewed it myself" / "I'll do systematic self-validation"
❌ Self-validate multi-subsystem work "Time constraints mean self-validation is acceptable" (NO - spawn validator)
❌ Bypass BLOCK status "The validation is too strict, I'll proceed anyway"
❌ Complete refusal under pressure "I can't do this properly in 3 hours, so I won't do it" (Should: Provide scoped alternative)
See individual skill files for detailed contracts:
01-discovery-findings.md contract → analyzing-unknown-codebases.md02-subsystem-catalog.md contract → analyzing-unknown-codebases.md03-diagrams.md contract → generating-architecture-diagrams.md04-final-report.md contract → documenting-system-architecture.md05-quality-assessment.md contract → assessing-code-quality.md06-architect-handover.md contract → creating-architect-handover.md07-security-surface.md contract → mapping-security-surface.md08-incremental-report.md contract → incremental-analysis.md09-test-infrastructure.md contract → analyzing-test-infrastructure.md10-dependency-analysis.md contract → analyzing-dependencies.mdCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.