aspens

Skills

• .agents/skills/base/SKILL.md — Base repo skill; load whenever working in this repo.
• .agents/skills/agent-customization/SKILL.md — LLM-powered injection of project context into installed agent templates via aspens customize agents
• .agents/skills/claude-runner/SKILL.md — Claude/Codex CLI execution layer — prompt loading, stream-json parsing, file output extraction, path sanitization, skill file writing, and skill rule generation
• .agents/skills/cli-shell/SKILL.md — Top-level Commander wiring, welcome screen, missing-hook warning, CliError exit handling, and the public programmatic API surface
• .agents/skills/codex-support/SKILL.md — Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets
• .agents/skills/doc-impact/SKILL.md — Context health analysis — freshness, domain coverage, hub surfacing, drift detection, LLM-powered interpretation, and auto-repair for generated agent context
• .agents/skills/doc-sync/SKILL.md — Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook
• .agents/skills/import-graph/SKILL.md — Static import analysis that builds dependency graphs, domain clusters, hub files, git churn hotspots, and file priority rankings
• .agents/skills/repo-scanning/SKILL.md — Deterministic repo analysis — language/framework detection, structure mapping, domain discovery, health checks, and import graph integration
• .agents/skills/save-tokens/SKILL.md — Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
• .agents/skills/skill-generation/SKILL.md — LLM-powered generation pipeline for Claude Code skills and CLAUDE.md — doc-init command, prompt system, context building, and output parsing
• .agents/skills/template-library/SKILL.md — Bundled agents, commands, hooks, and settings that users install via aspens add, aspens doc init, and aspens save-tokens into their .claude/ directories
• .agents/skills/architecture/SKILL.md — Import graph and code-map reference for structural changes.

Commands

• npm test — run Vitest (vitest run)
• npm start — run the CLI (node bin/cli.js)
• npm run lint — no-op check (echo 'No linter configured yet' && exit 0)
• aspens scan [path] — deterministic repo scan
• aspens doc init [path] — generate skills, hooks, and instructions file (--target claude|codex|all, --recommended for full recommended setup including save-tokens, agents, and doc-sync hook)
• aspens doc impact [path] — show freshness, coverage, drift, and LLM interpretation of generated context (interactive apply for repairs)
• aspens doc sync [path] — update docs from recent diffs
• aspens doc graph [path] — rebuild .agents/skills/architecture/references/code-map.md
• aspens add <type> [name] — install bundled templates
• aspens save-tokens [path] — install token-saving session settings (--recommended, --remove)

Release

• Release workflow: /Users/MV/aspenkit/dev/release.md

Conventions

• ESM only: use import/export; never require().
• Prefer CliError from command handlers; top-level handling lives in bin/cli.js.
• es-module-lexer must be initialized before parse().
• Keep target/backend semantics straight: target is output format/location; backend is the generating CLI. Persist config in .aspens.json.
• Do not duplicate base-skill guidance here; consult .agents/skills/base/SKILL.md for deeper repo context.

Behavior

• Verify before claiming — Never state that something is configured, running, scheduled, or complete without confirming it first. If you haven't verified it in this session, say so rather than assuming.
• Make sure code is running — If you suggest code changes, ensure the code is running and tested before claiming the task is done.
• Ask clarifying questions — If the task is ambiguous, ask for clarification rather than making assumptions. Don't imply or guess at requirements or constraints that aren't explicitly stated.
• Simplicity first — Write the minimum code that solves the problem. No speculative features, abstractions for single-use code, or error handling for impossible scenarios.
• Surgical changes — Touch only what the task requires. Don't refactor adjacent code, fix unrelated formatting, or "improve" things that aren't broken.

aspens

Your CLAUDE.md stopped working. Here's why.

You started with 50 clean lines. Three months later it's 200, and Claude ignores half of them. Adding more rules doesn't fix it. The file got too big for the agent to follow, and it goes stale every time the code changes.

aspens replaces the monolith with scoped skill files (~35 lines each) generated from your actual import graph. Each skill activates only when the agent touches that part of the codebase. A post-commit hook keeps them in sync automatically. The agent reads 35 focused lines instead of 200 sprawling ones, and actually follows them.

Works with Claude Code, Codex, or both.

Install

npm install -g aspens

Then in your project:

aspens doc init --recommended

Verify what it generated:

aspens doc impact

Or run without installing:

npx aspens doc init --recommended

Before / After

Before aspens — one file tries to cover everything:

• Agent starts cold, spends 10-20 tool calls exploring your codebase every session
• CLAUDE.md grows until the agent stops following it
• Documentation drifts out of date within days of any refactor
• Agent misses conventions, duplicates existing code, ignores architectural boundaries

After aspens — scoped skills generated from your import graph:

• Agent loads only the skill for the domain it's working in (~35 lines, 100% followed)
• doc sync updates affected skills automatically on every commit
• doc impact proves freshness and coverage so you know context matches the code
• Agent reuses existing code because skills surface the right key files

What Are Skills?

Skills are short markdown files that give coding agents the repo context they actually need: key files, conventions, patterns, and critical rules. They activate when the agent works in that part of the codebase.

---
name: billing
description: Stripe billing integration — subscriptions, usage tracking, webhooks
---

## Activation

This skill triggers when editing billing/payment-related files:
- `**/billing*.ts`
- `**/stripe*.ts`

---

You are working on **billing, Stripe integration, and usage limits**.

## Key Files
- `src/services/billing/stripe.ts` — Stripe SDK wrapper
- `src/services/billing/usage.ts` — Usage counters and limit checks

## Key Concepts
- **Webhook-driven:** Subscription state changes come from Stripe webhooks, not API calls
- **Usage gating:** `checkLimit(userId, type)` returns structured 429 error data

## Critical Rules
- Webhook endpoint has NO auth middleware — verified by Stripe signature only
- Cancel = `cancel_at_period_end: true` (user keeps access until period end)

Target Support

Aspens supports multiple agent environments through output targets:

• claude: CLAUDE.md + .claude/skills + Claude hooks
• codex: AGENTS.md + .agents/skills + directory AGENTS.md
• all: generate both sets together
• we are working on adding more agents and tools - ask or contribute!

Commands

aspens doc init

Generate agent context from the repo. Scans the codebase, discovers architecture and feature domains, then writes instructions and skills.

--recommended is the fastest path to automatically generate the default settings but you can also do it manually:

$ aspens doc init

  ◇ Scanned my-app (fullstack)
    Languages: typescript, javascript
    Frameworks: nextjs, react, tailwind, prisma
    Import graph: 247 files, 892 edges

  ◇ Discovered 8 feature domains:
      auth, courses, billing, profile, ...

  + .claude/skills/base/skill.md
  + .claude/skills/auth/skill.md
  + .claude/skills/billing/skill.md
  ...

  10 created | 4m 32s

Option	Description
--recommended	Use recommended target, strategy, and generation mode
--dry-run	Preview without writing files
--force	Overwrite existing skills
--timeout <seconds>	Backend timeout (default: 300)
--mode <mode>	all, chunked, or base-only (skips interactive prompt)
--strategy <strategy>	improve, rewrite, or skip for existing docs
--domains <list>	Additional domains to include (comma-separated)
--no-graph	Skip import graph analysis
--model <model>	Model for the selected backend
--verbose	Show backend reads/activity in real time
--target <target>	Output target: claude, codex, or all
--backend <backend>	Generation backend: claude or codex

aspens doc impact

Check your context's health and coverage, keeping up with the codebase. Checks for:

• Instructions and skills present per target
• Domain coverage vs detected repo domains
• Top hub files surfaced in root guidance
• Whether generated context is older than the newest source changes

aspens doc sync

This may be the most important command. Keeps generated context from drifting. Reads recent git changes, maps them to affected skills, and updates only what changed.

$ aspens doc sync

  ◆ aspens doc sync

  ◇ 4 files changed

    src/services/billing/stripe.ts
    src/services/billing/usage.ts
    src/components/billing/PricingPage.tsx
    package.json

  ℹ Skills that may need updates: billing, base

  ◇ Analyzing changes and updating skills...
  ◇ 1 file(s) to update

  ~ .claude/skills/billing/skill.md

  1 file(s) updated

Option	Description
--commits <n>	Number of commits to analyze (default: 1)
--refresh	Review all skills against current codebase (no git diff needed)
--install-hook	Install git post-commit auto-sync
--remove-hook	Remove the git post-commit auto-sync hook
--dry-run	Preview without writing files
--no-graph	Skip import graph analysis
--timeout <seconds>	Backend timeout (default: 300)
--model <model>	Model for the selected backend
--verbose	Show backend reads/activity in real time

aspens doc graph

Rebuild the import graph cache. Runs automatically during doc init and doc sync, but you can trigger it manually.

aspens doc graph

aspens add <type> [name]

Add individual components from the bundled library, or create custom skills.

aspens add agent all              # Add all 11 AI agents
aspens add agent code-reviewer    # Add a specific agent
aspens add agent --list           # Browse available agents
aspens add hook skill-activation  # Add auto-triggering hooks
aspens add command dev-docs       # Add slash commands
aspens add skill my-convention    # Scaffold a custom skill
aspens add skill release --from dev/release.md  # Generate from a reference doc
aspens add skill --list           # Show existing skills

Option	Description
--list	Browse available components
--from <file>	Generate a skill from a reference document (skills only)
--force	Overwrite existing skills

aspens customize agents

Inject your project's tech stack, conventions, and file paths into installed Claude agents.

aspens customize agents
aspens customize agents --dry-run

Option	Description
--dry-run	Preview without writing files
--timeout <seconds>	Claude timeout (default: 300)
--model <model>	Claude model (e.g., sonnet, opus, haiku)
--verbose	Show what Claude is doing

aspens save-tokens

Install token-saving session settings — statusline telemetry, prompt guards, precompact handoffs, and session rotation.

aspens save-tokens               # Interactive install
aspens save-tokens --recommended # No-prompt install
aspens save-tokens --remove      # Uninstall

How It Works

1. Scanner — detects tech stack, frameworks, structure, and domains. Deterministic, no LLM, instant.
2. Import Graph — parses imports across JS/TS/Python, resolves aliases, finds hub files and coupling.
3. Discovery — 2 parallel LLM passes explore the codebase: one finds feature domains, the other analyzes architecture.
4. Generation — writes concise skills guided by the graph + discovery findings. Up to 3 domains in parallel.
5. Sync — on each commit, reads the diff, identifies affected skills, and updates only what changed.

Requirements

• Node.js 20+
• At least one supported agent CLI:
  • Claude Code CLI — npm install -g @anthropic-ai/claude-code
  • Codex CLI

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md.