Agent Customization

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.

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.

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.

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

• 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-05-11