ai-driven-design
AI-Driven Design — Tools as Foundation
Section titled “AI-Driven Design — Tools as Foundation”Universal architectural principle for every TheOneKit skill, agent, and hook script. Loaded
on-demand when a session reads or edits a .claude/** file (paths: above) — not every session.
Default to AI-driven solutions. CLI/hooks/scripts emit facts (machine-parseable JSON + file excerpts); Claude (skills + agents) reasons over those facts, decides policy, and explains rationale. Never put decision logic in pure-CLI code when AI can add semantic context.
Exceptions — pure-CLI logic IS correct for: deterministic invariants (CI gates, doctor checks, schema validators with no judgment component) · performance-critical paths (watchers, bulk transforms, releases) · side-effects with safety constraints (destructive ops, secret handling), where AI advice is gated behind explicit user approval before any CLI execution.
How to apply: for each decision point in a new skill, agent, or hook ask “judgment, or deterministic?” Judgment → skill body. Deterministic → a .cjs script under .claude/scripts/ or a hook. Hybrid → script emits structured facts; skill body reads + reasons + acts.
Worked examples per exception, and why CLI-embedded policy logic is brittle: docs/ai-driven-design.md.
Related rules and full detail: docs/ai-driven-design.md.