olioapps Cartographer
Generate AI-optimized codebase navigation (atlas skills) plus spec-driven development workflows.
Quick Start
# Generate atlas for current codebase
/cartographer:chart
# Use atlas for navigation (auto-invoked)
/atlas
# Spec-driven development
/navigator:plan <task> # Create implementation spec
/navigator:build <spec> # Execute spec with patterns
/navigator:review <spec> # Review against patterns
Core Concepts
Atlas
An atlas is a generated skill (.claude/skills/atlas/) that provides:
- Domain mapping: Where different features/concerns live
- Pattern documentation: How code is structured (controllers, services, etc.)
- Anti-patterns: Codebase-specific mistakes to avoid
- File conventions: Naming and location patterns
Spec-Driven Development
Navigator commands use the atlas to:
- Plan: Generate specs with relevant pattern context
- Build: Implement following documented conventions
- Review: Validate against patterns and anti-patterns
Commands
Cartographer Commands
| Command | Model | Description |
|---|---|---|
/cartographer:chart |
sonnet | Generate complete atlas |
/cartographer:rechart |
sonnet | Incrementally update atlas |
/cartographer:health |
sonnet | Comprehensive atlas health check (drift, structure, quality) |
/cartographer:explore <domain> |
sonnet | Deep-dive into domain |
/cartographer:where <query> |
haiku | Quick path lookup |
/cartographer:capture |
haiku | Capture knowledge to atlas |
/cartographer:orient |
haiku | Set up CLAUDE.md awareness |
/cartographer:embed |
sonnet | Export commands for plugin-free use |
/cartographer:help |
haiku | Display usage guide |
Navigator Commands
| Command | Model | Description |
|---|---|---|
/navigator:plan <task> |
sonnet | Create implementation spec with atlas context |
/navigator:build <spec> |
sonnet | Execute spec with pattern guidance |
/navigator:review <spec> |
sonnet | Review implementation against spec/patterns |
Workflows
New Codebase Setup
/cartographer:chart # Generate atlas (interactive)
/cartographer:orient # Add atlas awareness to CLAUDE.md
Feature Development
/navigator:plan add user profiles # Generate spec
/navigator:build specs/user-profiles.md # Implement
/navigator:review specs/user-profiles.md # Review
Atlas Maintenance
/cartographer:health # Check drift, structure, and quality
/cartographer:rechart # Update stale areas
/cartographer:capture --pattern # Add discovered patterns
Agents
The plugin uses specialized agents for complex tasks:
Analysis Agents
| Agent | Model | Purpose |
|---|---|---|
| surveyor | sonnet | Explores codebase to detect project type, domains, and patterns |
| auditor | sonnet | Validates atlas accuracy against actual codebase state |
| import-analyzer | sonnet | Analyzes import graph for layer boundary detection |
Review Agents
| Agent | Model | Purpose |
|---|---|---|
| pattern-enforcer | sonnet | Validates code against documented patterns |
| architecture-auditor | sonnet | Validates layer boundaries and import rules |
| anti-pattern-detector | sonnet | Scans for codebase-specific anti-patterns |
| convention-checker | haiku | Validates file naming and locations |
| atlas-validator | haiku | Validates atlas document structure |
Files
cartographer/
├── SKILL.md # This file
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── commands/
│ ├── cartographer/ # Atlas management commands
│ └── navigator/ # Spec-driven workflow commands
├── agents/
│ ├── surveyor.md # Codebase analysis
│ ├── auditor.md # Atlas validation
│ ├── import-analyzer.md # Import graph analysis
│ └── review/ # Code review agents
├── assets/
│ ├── atlas-templates/ # Generated atlas templates
│ └── embed-templates/ # Standalone command templates
└── references/
└── atlas-format.md # Atlas schema documentation
Plugin-Free Operation
Export commands for use without the plugin installed:
/cartographer:embed --output .claude/commands/
This creates standalone command files that maintain full fidelity with plugin commands.
Troubleshooting
| Issue | Solution |
|---|---|
| Atlas not found | /cartographer:chart |
| Atlas outdated | /cartographer:health then /cartographer:rechart |
| Pattern violations | Check atlas anti-patterns, update if needed |
| Missing domain | /cartographer:explore <path> to enrich |