AGENTS.md

1# aspens
2 
3## Skills
4 
5- `.agents/skills/base/SKILL.md` — Base repo skill; load whenever working in this repo.
6- `.agents/skills/agent-customization/SKILL.md` — LLM-powered injection of project context into installed agent templates via `aspens customize agents`
7- `.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
8- `.agents/skills/cli-shell/SKILL.md` — Top-level Commander wiring, welcome screen, missing-hook warning, CliError exit handling, and the public programmatic API surface
9- `.agents/skills/codex-support/SKILL.md` — Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets
10- `.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
11- `.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
12- `.agents/skills/import-graph/SKILL.md` — Static import analysis that builds dependency graphs, domain clusters, hub files, git churn hotspots, and file priority rankings
13- `.agents/skills/repo-scanning/SKILL.md` — Deterministic repo analysis — language/framework detection, structure mapping, domain discovery, health checks, and import graph integration
14- `.agents/skills/save-tokens/SKILL.md` — Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
15- `.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
16- `.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
17- `.agents/skills/architecture/SKILL.md` — Import graph and code-map reference for structural changes.
18 
19## Commands
20 
21- `npm test` — run Vitest (`vitest run`)
22- `npm start` — run the CLI (`node bin/cli.js`)
23- `npm run lint` — no-op check (`echo 'No linter configured yet' && exit 0`)
24- `aspens scan [path]` — deterministic repo scan
25- `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)
26- `aspens doc impact [path]` — show freshness, coverage, drift, and LLM interpretation of generated context (interactive apply for repairs)
27- `aspens doc sync [path]` — update docs from recent diffs
28- `aspens doc graph [path]` — rebuild `.agents/skills/architecture/references/code-map.md`
29- `aspens add <type> [name]` — install bundled templates
30- `aspens save-tokens [path]` — install token-saving session settings (`--recommended`, `--remove`)
31 
32## Release
33 
34- Release workflow: `/Users/MV/aspenkit/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 `.agents/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