git:20260408.7834abc to git:20260409.df814ae

16 added, 15 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: template-library
- description: Bundled agents, commands, hooks, and settings that users install via `aspens add` and `aspens doc init` into their .claude/ directories
+ description: Bundled agents, commands, hooks, and settings that users install via `aspens add`, `aspens doc init`, and `aspens save-tokens` into their .claude/ directories
---
## Activation
This skill triggers when editing template-library files:
- `src/commands/add.js`
- `src/templates/**/*`
Keywords: template, add agent, add command, add hook, add skill
---
You are working on the **template library** — bundled agents, slash commands, hooks, and settings that users browse and install into their repos.
## Key Files
- `src/commands/add.js` — Core `aspens add <type> [name]` command; copies templates to `.claude/` dirs, scaffolds/generates custom skills
- `src/templates/agents/*.md` — Agent persona templates (11 bundled)
- - `src/templates/commands/*.md` — Slash command templates (2 bundled)
- - `src/templates/hooks/` — Hook scripts (5 bundled): `skill-activation-prompt.sh/mjs`, `graph-context-prompt.sh/mjs`, `post-tool-use-tracker.sh`
+ - `src/templates/commands/*.md` — Slash command templates (5 bundled: save-handoff, resume-handoff, resume-handoff-latest, plus 2 original)
+ - `src/templates/hooks/` — Hook scripts: `skill-activation-prompt.sh/mjs`, `graph-context-prompt.sh/mjs`, `post-tool-use-tracker.sh`, `save-tokens.mjs`, `save-tokens-statusline.sh`, `save-tokens-prompt-guard.sh`, `save-tokens-precompact.sh`
- `src/templates/settings/settings.json` — Default settings with hook configuration (commands are double-quoted for shell safety)
- `src/prompts/add-skill.md` — System prompt for LLM-powered skill generation from reference docs
## Key Concepts
- **Four resource types for `add`:** `agent` → `.claude/agents`, `command` → `.claude/commands`, `hook` → `.claude/hooks`. A fourth type `skill` is handled separately (not template-based).
- - **Codex-only restriction:** `add agent`, `add command`, and `add hook` throw `CliError` for Codex-only repos (checked via `readConfig()`). Skills work with both targets — `add skill` is always available.
- - **Target-aware skill commands:** `addSkillCommand` and `generateSkillFromDoc` resolve the active target via `resolveSkillTarget(config)`. Skill paths use `target.skillsDir` and `target.skillFilename` (not hardcoded `.claude/.agents/skills/skills/SKILL.md`).
- - **Backend-aware generation:** `generateSkillFromDoc` uses `runLLM()` imported from `runner.js` to dispatch to Claude or Codex based on config. `getAllowedPaths([target])` provides path safety for `parseFileOutput`.
- - **Skill subcommand:** `aspens add skill <name>` scaffolds a blank skill template. `--from <file>` generates a skill from a reference doc using the configured backend. `--list` shows installed skills.
- - **Hook templates (monorepo-aware):** Shell hooks (`skill-activation-prompt.sh`, `graph-context-prompt.sh`, `post-tool-use-tracker.sh`) compute `PROJECT_DIR` from the script's own location (`cd "$SCRIPT_DIR/../.." && pwd`) and pass it as `ASPENS_PROJECT_DIR` to the `.mjs` counterparts. The `.mjs` scripts prefer `ASPENS_PROJECT_DIR` over `CLAUDE_PROJECT_DIR`, enabling correct operation in monorepo subdirectories where `CLAUDE_PROJECT_DIR` points to git root.
- - **Settings template quoting:** Hook commands in `settings.json` are wrapped in double quotes (`"\"$CLAUDE_PROJECT_DIR/.claude/hooks/...\""`), ensuring paths with spaces or special characters are handled correctly by the shell.
- - **`doc init` hook installation (step 13):** Generates `skill-rules.json` from skills, copies hook files, generates `post-tool-use-tracker.sh` with domain patterns (via `BEGIN/END` markers), merges `settings.json` with backup. `createHookSettings()` adjusts hook command paths for subdirectory projects — matches `$CLAUDE_PROJECT_DIR` anywhere in the command string (not just at the start) to handle quoted paths.
+ - **Save-tokens templates:** `save-tokens.mjs` is the runtime entry point for all three hook entry points (statusline, prompt-guard, precompact). Shell wrappers (`save-tokens-*.sh`) resolve project dir and delegate to the `.mjs` file. Slash commands (`save-handoff.md`, `resume-handoff.md`, `resume-handoff-latest.md`) provide user-invokable handoff management. These are installed by `aspens save-tokens` or `aspens doc init --recommended`, not by `aspens add`.
+ - **Codex-only restriction:** `add agent`, `add command`, and `add hook` throw `CliError` for Codex-only repos. Skills work with both targets.
+ - **Target-aware skill commands:** `addSkillCommand` and `generateSkillFromDoc` resolve the active target via `resolveSkillTarget(config)`. Skill paths use `target.skillsDir` and `target.skillFilename`.
+ - **Backend-aware generation:** `generateSkillFromDoc` uses `runLLM()` to dispatch to Claude or Codex based on config.
+ - **Hook templates (monorepo-aware):** Shell hooks compute `PROJECT_DIR` from the script's own location (`cd "$SCRIPT_DIR/../.." && pwd`) and pass it as `ASPENS_PROJECT_DIR` to `.mjs` counterparts. Save-tokens shell hooks follow the same pattern.
+ - **Settings template quoting:** Hook commands in `settings.json` are wrapped in double quotes for shell safety.
+ - **`doc init` hook installation (step 13):** Generates `skill-rules.json`, copies hook files, generates `post-tool-use-tracker.sh` with domain patterns, merges `settings.json` with backup.
+ - **`doc init --recommended` extras (step 15):** Copies all bundled agent templates to `.claude/agents/` (skips existing), adds `dev/` to `.gitignore`.
- **Template discovery:** `listAvailable()` reads template dir, filters `.md`/`.sh` files, regex-parses `name:` and `description:`.
- - **No-overwrite policy:** `addResource()` skips files that already exist via `existsSync` check. Same for `addSkillCommand`.
- - **Plan/execute gitignore:** Adding `plan` or `execute` agents auto-adds `dev/` to `.gitignore` for plan storage.
- - **Conditional post-add tips:** Skill rules update and `--hooks-only` tip only shown for Claude target. Codex target gets no hook-related messaging.
+ - **No-overwrite policy:** `addResource()` skips files that already exist. Same for `addSkillCommand`.
+ - **Plan/execute gitignore:** Adding `plan` or `execute` agents auto-adds `dev/` to `.gitignore` for plan storage. `doc init --recommended` also ensures `dev/` in `.gitignore`.
## Critical Rules
- Template files **must** contain `name: <value>` and `description: <value>` lines parseable by regex.
- - Only `.md` and `.sh` extensions are discovered by `listAvailable()`. `.mjs` files are copied by `doc init` directly, not by `add`.
+ - Only `.md` and `.sh` extensions are discovered by `listAvailable()`. `.mjs` files are copied by `doc init` and `save-tokens` directly, not by `add`.
- The templates dir resolves from `src/commands/` via `join(__dirname, '..', 'templates')` — moving `add.js` breaks template resolution.
- Skill names are sanitized to lowercase alphanumeric + hyphens. Invalid names throw `CliError`.
- Commands throw `CliError` for expected failures instead of calling `process.exit()`.
## References
- **Customize flow:** `.agents/skills/agent-customization/SKILL.md`
+ - **Save-tokens install:** `.agents/skills/save-tokens/SKILL.md`
---
- **Last Updated:** 2026-04-08
+ **Last Updated:** 2026-04-09