v0.5.0 — Token Optimizer & Plan/Execute Agents

What's New

• Token optimizer — reduces prompt token usage across all skill and agent templates while preserving semantic content. Discovery, generation, and sync prompts are all trimmed automatically.
• Plan + execute agent pair — two new agent templates (plan.md, execute.md) for structured plan-then-execute workflows. Install with aspens add agent plan / aspens add agent execute.
• doc graph --remove — cleanly remove graph artifacts (graph.json, graph-index.json, code-map.md) from a repo.
• Refreshed dev docs commands — updated dev-docs and dev-docs-update command templates.

Other Changes

• Improved code-running rule in generated CLAUDE.md files
• Security: bumped picomatch to 4.0.4 (fixes method injection + ReDoS)

Upgrade

npm install -g aspens@latest
# or
npx aspens@latest --version

Existing users: run aspens doc init --hooks-only to update hooks with the latest templates.

Full Changelog: v0.4.0...v0.5.0

v0.4.0 — Refresh Mode, Custom Skills, & Module Split

What's New

• doc sync --refresh — review and update all skills against the current codebase without needing a git diff. Great for periodic full refreshes.
• add skill command — scaffold custom skills (aspens add skill my-convention) or generate from reference docs (aspens add skill release --from dev/release.md).
• Interactive file picker — large diffs (>80k chars) now prompt you to select which files Claude should analyze, with skill-relevant files pre-selected.
• Diff prioritization — skill-relevant files get 60k of the 80k char budget so important changes survive truncation.

Improvements

• Module split — doc-sync.js split from 813 → 540 lines into focused modules (git-helpers.js, diff-helpers.js, git-hook.js).
• Shared activation matching — deduplicated 3 copies of file-to-skill matching into getActivationBlock() / fileMatchesActivation(), fixing an inconsistent regex.
• Security hardening — all git commands use execFileSync (no shell interpolation), chmodSync replaces shell chmod, input guards on activation matching.
• Git hook hardening — 5-min cooldown, skip aspens-only commits, log rotation, stale lock cleanup, POSIX-compatible find.
• Skill rules regeneration — doc sync now regenerates skill-rules.json after every write, not just in refresh mode.
• Consistent timeout warnings — all commands now surface warnings for invalid ASPENS_TIMEOUT values.
• 35 new tests (162 → 197) covering timeout resolution, activation matching, skill scaffolding.

Bug Fixes

• Empty file selection in interactive picker no longer silently sends the full diff.
• truncateDiff falls back to newline boundary instead of mid-line cut.
• Gitignore entry matching uses exact line comparison instead of substring includes().

Upgrade

npm install -g aspens@latest
aspens doc init --hooks-only   # update hooks to latest version

Existing skills are fully compatible — no migration needed.

v0.3.0 — Import Graph + Windows Support

What's new

Import graph persistence (aspens doc graph)

aspens now builds and persists a structural map of your codebase across sessions. Run aspens doc graph to analyze the import graph and save three artifacts to .claude/:

• graph.json — full serialized import graph (hub files, clusters, edges, hotspots, rankings)
• graph-index.json — tiny pre-computed lookup index (~1–3KB) for fast matching
• code-map.md — human-readable codebase overview loaded into every Claude prompt

aspens doc sync now rebuilds the graph on every sync automatically — no separate command needed after the first run.

Graph context hook

Install aspens add hook graph-context-prompt to get smart prompt injection. On every Claude prompt, the hook checks if you mentioned any file names, export names, or domain keywords — and if so, injects a compact navigation context: which files are hubs, what depends on what, which cluster it belongs to. Claude gets structural awareness without you having to explain the codebase.

--domains flag for targeted retries

When a domain skill fails to generate (rate limit, timeout, etc.), aspens now tells you exactly how to retry just that domain:

aspens doc init --mode chunked --domains "auth,payments" /path/to/repo

Skips discovery, skips base skill, skips CLAUDE.md — regenerates only the domains you specify.

---

Fixed

• Windows spawn ENOENT — aspens doc init (and all commands invoking Claude) now work on Windows. Node's spawn() couldn't find claude.cmd without shell: true — scoped to win32 only so Mac/Linux behavior is unchanged. (Reported by @ckwich, #25)
• Windows timeout kill — on timeout, the full process tree is now killed via taskkill /t /f instead of just the shell wrapper
• base-only mode skipping base skill — a logic bug caused --mode base-only to also skip base skill generation. Fixed by splitting the internal skipDiscovery flag into two explicit booleans
• Graph hook portability — timeout 5s in the shell wrapper required GNU coreutils (not available on macOS by default). Timeout is now a portable setTimeout inside the Node script
• Silent graph failures in doc sync — graph errors were silently swallowed; now warns the user so they know graph context was skipped
• Wrong output path in doc graph outro — the success message referenced .claude/skills/code-map/skill.md which doesn't exist; corrected to .claude/code-map.md
• Node 18/20 test compatibility — replaced import.meta.dirname (Node 21+ only) with portable fileURLToPath + dirname

---

Upgrade steps

Existing users: No breaking changes. Run aspens doc sync in your repos to rebuild the graph and get the code-map.

To enable the graph context hook:

aspens add hook graph-context-prompt
aspens doc graph .

v0.2.2 — Skill Auto-Activation

⚡ Skills now auto-activate on every prompt

This is the most important update since launch. Previously, skills were generated but Claude Code had no way to know when to load them. Now aspens doc init generates a complete activation system — hooks, rules, and settings — so skills load automatically based on what you're working on.

What's new

Skill activation hooks — doc init now generates:

• skill-rules.json — maps keywords, file patterns, and intent patterns to each skill
• skill-activation-prompt.sh + .mjs — a UserPromptSubmit hook that matches every prompt against your skills and injects the relevant ones into Claude's context
• post-tool-use-tracker.sh — a PostToolUse hook that watches which files you edit and activates the corresponding domain skill for the rest of the session (session-sticky)
• settings.json entries — registers the hooks with Claude Code automatically

Session-sticky skills — when you edit a file in a domain (e.g., src/services/billing/stripe.ts), that domain's skill stays active for the rest of the session, even if your next prompt doesn't mention billing.

New CLI flags:

• --hooks-only — install/update hooks without regenerating skills
• --no-hooks — skip hook installation during doc init

Missing hooks warning — if you have skills but no hooks, the CLI now warns you with the fix command.

---

⚠️ If you already have skills (upgrading from 0.2.0 or 0.2.1)

Your existing skills work fine, but they won't auto-activate without hooks. Run:

npx aspens doc init --hooks-only

This installs the activation hooks + rules without touching your existing skills. Takes ~1 second, no LLM calls.

Without this step, your skills sit in .claude/skills/ but Claude Code doesn't know they exist — you'd have to manually tell Claude to read them every session.

---

Bug fixes

• Hook settings merge uses order-independent duplicate detection
• Bash pattern injection validated against safe character whitelist
• Keyword normalization trims punctuation and preserves original casing
• --dry-run no longer creates directories as a side effect
• Path containment checks use path.relative() (platform-aware)
• Session files use TMPDIR env var to match Node's os.tmpdir()
• parseFileOutput skips <file> tags inside fenced code blocks
• Portable hash fallback (shasum → sha1sum → md5sum) in git hook
• Windows-aware path lookup in resolveAspensPath

Full changelog

See CHANGELOG.md for the complete list.

v0.2.1

v0.2.1 — Reliability Fixes

CLAUDE.md and base skill generation now retry automatically if Claude doesn't wrap output in the expected format. Previously these essential files could silently fail to generate.

Fixed

• CLAUDE.md retry logic — detects missing <file> tags, retries up to 2 times with a format reminder
• Base skill retry logic — same retry mechanism
• Circular self-dependency — package.json was listing itself as a dependency
• Skill file truncation — 4 skill files had incomplete content (sentences cut off mid-word, missing Critical Rules sections)
• Python import regex — now handles 4+ dot relative imports
• Regex injection — domain names with metacharacters no longer break findings extraction
• Hardcoded line numbers in repo-scanning skill replaced with stable identifiers

Added

• Subdirectory tsconfig resolution — @/ aliases now resolved from tsconfigs in frontend/, apps/*, packages/*
• Vendored/generated code exclusion — skips *.min.js, *_generated.*, lock files, generated-code markers
• Logo in README
• Wiki: 9 documentation pages
• Wiki: Common Recipes + Release Process pages

Install

npx aspens@0.2.1 scan .

Full Changelog: v0.2.0...v0.2.1

v0.2.0

v0.2.0 — Import Graph + Parallel Agents

The scanner got a brain. aspens now builds an import graph, runs parallel Claude agents to discover your architecture, and generates skills in parallel batches.

What's new

Import graph engine

• Parses JS/TS imports via es-module-lexer, Python imports via regex
• Resolves @/ path aliases from tsconfig.json (including monorepo subdirectories like frontend/tsconfig.json)
• Resolves Python absolute imports from multiple roots (backend/, src/, etc.)
• Builds dependency DAG with fan-in/fan-out, file priority ranking, connected component clustering
• Inter-domain coupling matrix shows how domains depend on each other

Git intelligence

• File churn analysis (6-month window)
• Hotspot detection — files with high churn + high complexity

Parallel discovery (Layer 2)

• 2 Claude agents run simultaneously: one discovers feature domains, the other analyzes architecture
• Domains are real product features (auth, billing, courses) — not just directory names

Parallel skill generation (Layer 3)

• Up to 3 domain skills generated concurrently
• Base skill first (sequential), domain skills in batches, CLAUDE.md last

Vendored/generated code exclusion

• Skips *.min.js, *_generated.*, *_pb2.py, lock files
• First-line content check for generated markers

Rich scan output

• Hub files with fan-in counts
• Domains by import clustering with dependency arrows
• Coupling matrix
• Hotspots
• Health checks (gitignore, .env leak detection)

Install

npx aspens scan .
npx aspens doc init .

Full Changelog: v0.1.0...v0.2.0

v0.1.0 — First Release

aspens v0.1.0

Generate and maintain AI-ready documentation for any codebase. Aspens scans your repo, uses Claude to produce structured skill files, and keeps them updated on every commit.

Install

npm install -g aspens

Requires Node.js 18+ and Claude Code.

What's included

Core commands

• aspens scan — Detect tech stack, frameworks, structure, and domains (no LLM, instant)
• aspens doc init — Generate skills + CLAUDE.md by having Claude explore your code
• aspens doc sync — Update skills from git diffs, installable as post-commit hook
• aspens add — Install agents, hooks, and slash commands from the bundled library
• aspens customize agents — Inject your project's tech stack and conventions into agents

Bundled components

• 9 AI agents (code reviewer, refactorer, planner, doc architect, and more)
• 2 hooks (skill activation prompt, post-tool-use tracker)
• 2 slash commands (dev-docs, dev-docs-update)

Features

• Chunked generation mode for large repos
• Auto-scaling timeout based on repo size
• --model flag for choosing Claude model (sonnet, opus, haiku)
• --verbose mode to watch Claude explore your codebase in real time
• Token usage summary after generation
• Existing docs strategy: improve, rewrite, or skip
• Git hook with 5-minute cooldown to prevent rapid re-syncs
• 69 tests (vitest)

Quick start

aspens scan .                    # See your repo's tech stack
aspens doc init .                # Generate skills + CLAUDE.md
aspens doc sync --install-hook   # Auto-update on every commit
aspens add agent all             # Add AI agents
aspens customize agents          # Tailor agents to your project