ai-tools-architect

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.
2. 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.
3. 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.
4. 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.
5. 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?"