CLAUDE.md

1# aspens
2 
3## Skills
4 
5- `.claude/skills/base/skill.md` — Base repo skill; load whenever working in this repo.
6- `.claude/skills/agent-customization/skill.md` — LLM-powered injection of project context into installed agent templates via `aspens customize agents`
7- `.claude/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
8- `.claude/skills/cli-shell/skill.md` — Top-level Commander wiring, welcome screen, missing-hook warning, CliError exit handling, and the public programmatic API surface
9- `.claude/skills/codex-support/skill.md` — Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets
10- `.claude/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
11- `.claude/skills/doc-sync/skill.md` — Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook
12- `.claude/skills/import-graph/skill.md` — Static import analysis that builds dependency graphs, domain clusters, hub files, git churn hotspots, and file priority rankings
13- `.claude/skills/repo-scanning/skill.md` — Deterministic repo analysis — language/framework detection, structure mapping, domain discovery, health checks, and import graph integration
14- `.claude/skills/save-tokens/skill.md` — Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
15- `.claude/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
16- `.claude/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
17 
18## Commands
19 
20- `npm test` — run Vitest (`vitest run`)
21- `npm start` — run the CLI (`node bin/cli.js`)
22- `npm run lint` — no-op check (`echo 'No linter configured yet' && exit 0`)
23- `aspens scan [path]` — deterministic repo scan
24- `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)
25- `aspens doc impact [path]` — show freshness, coverage, drift, and LLM interpretation of generated context (interactive apply for repairs)
26- `aspens doc sync [path]` — update docs from recent diffs
27- `aspens doc graph [path]` — rebuild `.claude/graph.json`
28- `aspens add <type> [name]` — install bundled templates
29- `aspens customize agents` — inject project context into installed agents
30- `aspens save-tokens [path]` — install token-saving session settings (`--recommended`, `--remove`)
31 
32## Release
33 
34- Release workflow: `../dev/release.md`
35 
36## Conventions
37 
38- ESM only: use `import`/`export`; never `require()`.
39- Prefer `CliError` from command handlers; top-level handling lives in `bin/cli.js`.
40- `es-module-lexer` must be initialized before `parse()`.
41- Keep target/backend semantics straight: target is output format/location; backend is the generating CLI. Persist config in `.aspens.json`.
42- Do not duplicate base-skill guidance here; consult `.claude/skills/base/skill.md` for deeper repo context.
43 
44## Behavior
45 
46- **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.
47- **Make sure code is running** — If you suggest code changes, ensure the code is running and tested before claiming the task is done.
48- **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.
49- **Simplicity first** — Write the minimum code that solves the problem. No speculative features, abstractions for single-use code, or error handling for impossible scenarios.
50- **Surgical changes** — Touch only what the task requires. Don't refactor adjacent code, fix unrelated formatting, or "improve" things that aren't broken.
51