version: "1.0.1" name: ai-tools-architect description: AI-tool architecture for instructions, prompts, rules, agents, commands, skills, hooks, and provider context. Use for setup, refactoring, or audits needing clear boundaries, deterministic automation, reproducibility, or lean context. Use software-engineering for application architecture.

AI Tools Architecture Playbook

Enforce progressive disclosure and deterministic execution boundaries for this project's AI setup. Keep model context focused on judgment while routing exact, repeatable mechanics through tools or bundled scripts.

For an existing AI configuration tree, run the structural audit before manual review:

python3 <skill-dir>/scripts/audit_ai_tools.py <ai-tools-root> --format markdown

The audit is read-only. Treat errors as objective structural failures and warnings as review candidates; architecture decisions remain with the agent. Review implicit and explicit-only skill counts before adding another automatic trigger. Treat the description budget as advisory because host limits vary. After changing canonical skills, run every bundled unit suite with:

python3 <skill-dir>/scripts/run_skill_tests.py <canonical-skills-root>

Treat root AGENTS.md as registry and keep detailed workflow or domain guidance in gated leaf nodes.

Core Doctrine: Nudges, Not Documentation

Apply these tests to every AGENTS.md, rule, skill, and agent file you design or review, in any repository:

1. Human docs are canon. If the project documents a convention for all

contributors (CONTRIBUTING.md, docs/, style guides), agent files must point there; never paraphrase or fork it. The root registry should instruct reading the canon doc before making changes. Duplicating canon into agent files costs little context (they rarely co-load) but guarantees drift.

1. Models know the technology. Never spend agent-file lines teaching the

language, framework, OS, or tool itself (syntax, standard commands, well-known APIs). The model already knows systemd units, flake syntax, git. Cut any content a competent engineer new to _this repo_ would not need.

1. Keep only the nudges. Agent files exist solely for what neither canon

docs nor model knowledge covers: project-specific layout and naming, policy choices among valid alternatives, environment quirks, and corrections for behaviors models repeatedly get wrong here.

1. Dedupe across co-loading files. Duplication only costs tokens when both

copies load together (sibling path-gated rules, registry + rule). State shared guidance once in the file with the widest matching gate.

1. Encode mechanics; explain judgment. Prefer parameterized scripts or CLIs

for fragile or repeated queries, transformations, validation, and mutations. Keep selection, ambiguity resolution, and result interpretation in the playbook unless those decisions also have an exact contract.

Execution Routing

Do not guess or hallucinate architectural standards. For advice about a specific AI-configuration component, read its reference in refs/ before responding:

• For Subagents (Specialized tool/context boundaries): Read

refs/AGENTS.md

• For Path-Gated Rules (Domain/Directory guidelines): Read

refs/RULES.md

• For Skills (Multi-step, repeatable workflows): Read

refs/SKILLS.md

• For Commands (Single-file, atomic prompts): Read

refs/COMMANDS.md

• For agent-facing instructions and skill prose: Read

refs/writing-for-agents/REFERENCE.md

• For skill, workflow, or model-route evaluation: Read

refs/workflow-evaluation.md

• For repository instruction initialization or full-surface audits: Read

refs/INITIALIZATION.md, then only the component references it selects.

If AI-configuration scope remains broad, ask which component fits the need. Example: "How should I structure this new agent workflow?"