Roadmap

Roadmap

Completed (v0.8.0)

Activation Rules in YAML Frontmatter

• Skill activation rules now live in triggers: frontmatter (files / keywords / alwaysActivate) instead of a free-form ## Activation section
• Activation hook reads frontmatter first; legacy ## Activation sections still parse for backwards compatibility
• New skills generated by doc init / doc sync emit the frontmatter form

Language-Agnostic Code Map

• Domain clusters block in .claude/code-map.md renders for any language (was Next.js-only)
• Single-file clusters dropped; same-label clusters merged at render time
• code-map.md is now churn-stable — removed file counts, edge counts, hub-file rankings, hotspots, totals/date footer, and "+N more" suffixes. Only clusters and framework entries survive on disk; raw counts live in .claude/graph.json for programmatic access.

Next.js Entry-Point Detection

• src/lib/frameworks/nextjs.js recognizes App Router files (page, layout, route, loading, error, not-found, template, default, global-error)
• Pages Router files and special top-level files (middleware, instrumentation) detected
• Entry points surface in code-map.md under Framework entry points
• Pages Router walker no longer recurses into hidden directories (.next/, .vercel/)

Python and TypeScript Parser Split

• src/lib/parsers/python.js — line-anchored top-level imports + def/class extraction
• src/lib/parsers/typescript.js — es-module-lexer wrapper with default-export name resolution + export * from '...' re-exports
• src/lib/path-resolver.js — tsconfig.json / jsconfig.json paths: alias resolution with extends chain support
• .cjs / .mjs treated as first-class source extensions across the graph, import parser, and alias resolver
• Path-traversal in resolveAliasImport() blocked (crafted paths: entries with ../../../ are rejected)

Churn-Stable Doc Sync

• src/lib/diff-classifier.js — isNoOpDiff() short-circuits the LLM call entirely on lockfile-only / non-code diffs
• repairDeterministicSections() re-injects the ## Skills and ## Behavior sections from on-disk state on every sync, including the no-op path
• syncSkillsSection is idempotent — fresh inserts place the Skills section before any existing ## heading instead of immediately after the H1

Target-Transform Chokepoints

• collectSkillsForList() — overlays in-flight skills onto on-disk skills before building the root instructions file's Skills section; fixes the v0.7.x AGENTS.md truncation bug where a partial sync silently dropped unchanged skills
• sanitizePublishedContent() — defense-in-depth sanitizer that strips ## Activation, ## Key Files, and count-bearing graph data from every disk write
• assertTargetParity() — throws when configured targets diverge on logical file slots
• sanitizeCodexInstructions no longer drops CLAUDE.md-mentioning lines (substitution downstream handles them)

Completed (v0.7.x)

v0.7.3 — Sync Resilience

• doc sync treats unstructured LLM responses as "no updates needed" instead of crashing
• Codex AGENTS.md loads CLAUDE.md from disk when not in the canonical files (fixes near-empty AGENTS.md output during --strategy skip-existing and incremental syncs)

v0.7.2 — Nested Source Roots

• findSourceRoot() promotes the inner directory for layouts like .NET's ~/apps/MyApp/MyApp/MyApp.csproj
• scan pretty-printer shows Domains (by filesystem) for non-JS/TS/Python projects when the graph has no clusters

v0.7.1 — Multi-Language Domain Discovery

• Source-extension set widened: .cs, .java, .swift, .php, .ex, .exs, .mjs, .cjs, plus Kotlin (.kt/.kts) and F# (.fs/.fsx) counted as source
• Domain detection skips bin/, obj/, target/ so .NET / Java / Rust build artifacts no longer pollute module lists

v0.7.0 — Save-Tokens + Impact

• aspens doc impact — context-health report (freshness, coverage, drift, hook status, recommended repairs)
• aspens save-tokens — installable session-optimization settings (statusline, prompt guards, precompact handoffs, handoff commands)
• Chunked generation is durable — doc init --mode chunked writes generated files incrementally so successful chunks survive later failures
• runCodex() detects whether the installed Codex CLI supports --ask-for-approval instead of assuming an older flag contract
• Subdirectory-monorepo support across config and impact flows

Completed (v0.6.0)

Codex Support Hardening

• Shared backend routing now goes through a single runLLM path across commands
• Codex execution runs in read-only sandbox mode with approval disabled instead of --full-auto
• Multi-target publishing forwards graph data into target transforms so Codex architecture output is emitted when graph artifacts exist

Config and Path Safety

• .aspens.json parsing validates schema before use and falls back to inference for malformed configs
• Recovered multi-target configs are rewritten safely
• Target path allowlisting is stricter for transformed writes and parsed output

Sync and Skill Quality

• doc sync now errors on non-empty unparseable model output instead of reporting a false success
• Single-file fallback wrapping is limited to true single-file prompts
• Reusable-domain loading falls back to skill rules and key-file extraction when Codex-transformed skills omit activation sections

Security and Tests

• Vitest upgraded to 4.1.3, pulling in Vite 8.0.7 to clear the current advisory set
• Added config validation coverage for invalid but parseable .aspens.json files

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: ✅ shipped in v0.8.0 (App Router / Pages Router / middleware entry-point detection); deeper probing (server/client component classification, route counting) still pending
• 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