git:20260407.185e870 to git:20260511.125144f

33 added, 26 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: agent-customization
description: LLM-powered injection of project context into installed agent templates via `aspens customize agents`
+ triggers:
+ files:
+ - src/commands/customize.js
+ - src/prompts/customize-agents.md
+ keywords:
+ - customize
+ - agents
+ - subagent
+ - agent customization
---
- ## Activation
-
- This skill triggers when editing agent-customization files:
- - `src/commands/customize.js`
- - `src/prompts/customize-agents.md`
+ You are working on **agent customization** — the feature that reads a project's skills and AGENTS.md, then uses Claude CLI to inject project-specific context into generic agent files in `.claude/agents/`.
- ---
+ ## Domain purpose
+ `aspens customize agents` makes generic, bundled agent templates project-aware. It pulls the repo's skills + AGENTS.md as ground truth and asks Claude to add a tech-stack line, 3-5 project conventions, and real commands into each agent — without touching the agent's core logic.
- You are working on **agent customization** — the feature that reads a project's skills and AGENTS.md, then uses Claude CLI to inject project-specific context into generic agent files in `.claude/agents/`.
+ ## Business rules / invariants
+ - **Claude-only feature.** Throws `CliError` for Codex-only repos (`config.targets === ['codex']`). Codex CLI has no agent concept.
+ - **Base skill is required.** Pre-flight throws `CliError("Run 'aspens doc init' first — base skill is required for agent context.")` if `.agents/skills/base/SKILL.md` is missing.
+ - **Skills (`.claude/skills/**`) are the single source of truth** for project context. The prompt must not invent other context directories.
+ - **Read-only tools only.** Claude is invoked with `allowedTools: ['Read', 'Glob', 'Grep']` — no edits/writes from the LLM itself.
+ - **Output paths restricted to `.claude/`.** `parseFileOutput()` rejects anything else; `writeSkillFiles(..., { force: true })` does the actual write.
- ## Key Files
- - `src/commands/customize.js` — Main command: finds agents, gathers context, calls Claude, writes results
- - `src/prompts/customize-agents.md` — System prompt telling Claude how to customize agents
- - `src/lib/runner.js` — `runClaude()`, `loadPrompt()`, `parseFileOutput()` shared across commands
- - `src/lib/skill-writer.js` — `writeSkillFiles()` writes parsed output to disk
- - `src/lib/timeout.js` — `resolveTimeout()` for timeout handling (default 300s)
+ ## Non-obvious behaviors
+ - **Frontmatter preservation is split across LLM + code.** The prompt instructs Claude to preserve YAML frontmatter verbatim (including NOT adding a `skills:` line). Then `maybeInjectBaseSkill()` post-processes each returned file to add `skills: [base]` into the frontmatter — this keeps agents valid even when installed via `aspens add agent` without a prior `doc init`.
+ - **`--reset` semantics:** without `--reset`, agents that already declare `skills:` are left alone; with `--reset`, any existing `skills:` line is overwritten to `skills: [base]`. Used to roll out v0.8 upgrades to previously-customized agents.
+ - **`## Project context` block is verbatim-preserved** by the prompt — it carries conditional read instructions for code-map / domain skills.
+ - **AGENTS.md is truncated at 3000 chars** in `gatherProjectContext()`; skills are passed in full.
+ - **Agent discovery:** `findAgents()` recursively walks `.claude/agents/`, extracts `name:` via regex, falls back to filename if missing.
+ - **Default timeout 300s** via `resolveTimeout(options.timeout, 300)`; `ASPENS_TIMEOUT` env var honored with warning on invalid value.
- ## Key Concepts
- - **Claude-only feature:** Customize command reads `.aspens.json` and throws `CliError` if repo is configured for Codex-only (`targets: ['codex']`). Codex CLI has no agent concept.
- - **Context gathering:** `gatherProjectContext()` reads AGENTS.md (truncated at 3000 chars), all `.claude/skills/**/*.md` in full, and lists `.claude/guidelines/` paths without reading their contents.
- - **Agent discovery:** `findAgents()` recursively walks `.claude/agents/`, reads `.md` files, extracts `name:` via regex — falls back to filename if no frontmatter match.
- - **Read-only tools:** Claude is invoked with `allowedTools: ['Read', 'Glob', 'Grep']` and no maxTokens cap (unlike doc-init which sets per-call limits).
- - **Output parsing:** Claude returns `<file path="...">content</file>` XML tags, parsed by `parseFileOutput()`. Only `.claude/` paths are allowed.
+ ## Critical files (purpose, not inventory)
+ - `src/commands/customize.js` — orchestrator: preflight, agent discovery, context gathering, per-agent Claude calls, post-LLM `skills: [base]` injection, write.
+ - `src/prompts/customize-agents.md` — system prompt; enforces frontmatter + `## Project context` preservation and bans file-inventory / hub-ranking output.
## Critical Rules
- - **Claude-only** — throws `CliError` for Codex-only repos. Checks `readConfig(repoPath)` for target config.
- - **Read-only tools only** — Claude agents never get write tools. All output goes through `parseFileOutput()` → `writeSkillFiles()`.
- - **Context truncation** — AGENTS.md is capped at 3000 chars to avoid blowing up prompt size. Skills are read in full.
- - **Path safety** — `parseFileOutput()` only allows writes to `.claude/` prefixed paths. Customized agents stay in `.claude/agents/`.
- - **Dry-run support** — `--dry-run` flag previews output without writing. Confirmation prompt shown before writes.
- - **Model override** — `--model` flag passed through to `runClaude()` for model selection.
+ - **Never let the LLM emit a `skills:` line** — the prompt forbids it and the code adds it. If you change one, change both.
+ - **Never weaken path sanitization** — only `.claude/` paths may be written.
+ - **Never duplicate file-inventory or hub-ranking output** in customized agents — the graph hook supplies that dynamically.
+ - **Do not bypass the base-skill preflight** — agents without base context regress to generic behavior.
---
- **Last Updated:** 2026-04-02
+ **Last Updated:** 2026-05-11