Roadmap

Roadmap

Completed (v0.5.0)

Token Optimizer

• Reduced prompt token usage across all skill and agent templates while preserving semantic content
• Streamlined discovery, generation, sync, and customization prompts
• Compressed skill-format and examples partials

Plan + Execute Agent Pair

• plan agent — structured task planning with phased breakdown and acceptance criteria
• execute agent — iterative execution with verification per phase
• Install via aspens add agent plan / aspens add agent execute

Graph Removal

• aspens doc graph --remove — cleanly remove graph artifacts from a repo

Dev Docs Commands Refresh

• Updated dev-docs and dev-docs-update command templates

Security

• picomatch bump to 4.0.4 (method injection + ReDoS fix)

Completed (v0.4.0)

Doc Sync Hardening

• doc sync --refresh — review all skills against current codebase (no git diff)
• Interactive file picker for large diffs (>80k chars)
• Diff prioritization — skill-relevant files get 60k of the 80k char budget
• Git hook hardening — 5-min cooldown, skip aspens-only commits, log rotation
• skill-rules.json regenerated on every sync write
• Module split — doc-sync.js into git-helpers.js, diff-helpers.js, git-hook.js

Custom Skills

• aspens add skill <name> — scaffold blank skills
• aspens add skill <name> --from <file> — generate skills from reference docs
• aspens add skill --list — list existing skills

Security & Quality

• All git commands use execFileSync (no shell interpolation)
• fileMatchesActivation() shared helper with input guards
• 35 new tests (162 → 197)
• CliError cause chain for better debugging

Completed (v0.3.0)

Import Graph Persistence

• aspens doc graph — standalone command to build and persist the import graph
• .claude/graph.json, .claude/graph-index.json, .claude/code-map.md persisted across sessions
• Graph context hook — injects navigation context into Claude prompts
• Graph-aware doc sync — uses import graph for better skill change detection
• Graph artifacts auto-gitignored to prevent sync loops

Skill Auto-Activation (v0.2.2)

• skill-rules.json generation from skill file patterns
• Shell + Node.js hooks for auto-triggering skills
• Session-sticky skills via PostToolUse tracking
• --hooks-only flag for updating hooks without regenerating skills

Completed (v0.2.0)

Step 1: Import Graph

• es-module-lexer for JS/TS import/export extraction
• Regex-based Python import parsing (strips docstrings)
• Path alias resolution from tsconfig.json (including subdirectory tsconfigs for monorepos)
• Python multi-root resolution (backend/, src/, etc.)
• File priority ranking (fan-in, exports, entry points, git churn, depth)
• Connected component domain clustering
• Inter-domain coupling matrix

Step 4: Git Intelligence

• File churn analysis (6-month window)
• Hotspot detection (high churn × high lines)
• Churn integrated into priority scoring

Step 5 (partial): Vendored/Generated Code Exclusion

• Skip vendored directories (vendor/, third_party/, bower_components/, etc.)
• Skip generated files (*.min.js, _generated., *_pb2.py, etc.)
• First-line content check for generated markers (// Code generated by, etc.)
• Lock files excluded (package-lock.json, yarn.lock, etc.)

Step 7: Layer 2 — Agentic Discovery

• Two parallel Claude agents (domain discovery + architecture analysis)
• Structured findings output ( tags)
• Discovered domains override scanner directory-based domains

Step 8: Layer 3 — Parallel Skill Generation

• Base skill (sequential first)
• Domain skills in parallel batches of 3
• CLAUDE.md last (depends on all skills)
• Discovery findings fed into generation prompts

Next Up

Step 2: Framework Architecture Probing

• Next.js: App Router vs Pages Router, route counting, server/client component detection, middleware
• Django: app detection (apps.py), model/view/serializer counting, DRF detection
• Rails: MVC structure mapping, service objects, migration history
• Spring Boot: Controller/Service/Repository naming patterns
• Laravel: MVC structure, route types, job/event patterns
• Expose as structured frameworkArchitecture in scan results

Step 3: Infrastructure Detection

• CI/CD platform detection (GitHub Actions, GitLab CI, CircleCI, Jenkins, etc.)
• Database migration tool detection (Prisma, Drizzle, Alembic, ActiveRecord, etc.)
• API spec detection (OpenAPI, GraphQL, protobuf)
• IaC detection (Terraform, Pulumi, CDK, Serverless)

Step 5: Symbol Extraction + Repo Map

• web-tree-sitter with JS/TS grammar WASMs
• Extract function/class/type signatures from every file
• Aider-style repo map format (ranked by importance)
• Token-budget-aware formatting (binary search for max signatures that fit)
• Falls back to regex for Python (def, class, @decorator)

Step 6: Graph Analysis Improvements

• Louvain community detection (better clusters than connected components)
• Temporal coupling from git (files that co-change = hidden dependencies)
• PageRank on the import graph (more nuanced than fan-in counting)

Step 9: Caching + Prompt Overhaul

• Content-addressed flat JSON cache in .aspens/cache/
• aspens doc sync only re-analyzes changed files
• Prompt rewrites: multi-stack examples, anti-patterns section, "when NOT to update" rules

Step 10: Additional Languages + Monorepo

• Python/Go/Rust tree-sitter grammars for symbol extraction
• Monorepo workspace detection (pnpm, npm, yarn, nx, turbo, lerna)
• Package dependency graph from cross-referencing package.json
• Package classification (apps vs libraries)

Future (v0.3.0+)

Direct API Mode

• --runner api flag for users without Claude Code
• Direct Anthropic API calls with API key
• Model choice: Haiku ($0.02/sync) for cheap, Sonnet ($0.30/sync) for quality
• Works in CI/CD environments

Embedding-Based Search (maybe)

• aspens doc search "authentication flow" — semantic code search
• Local vector store (LanceDB) for offline operation
• Function-level chunking via tree-sitter
• Useful for interactive exploration, not needed for doc generation