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. Auto-loaded into 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
Section titled “Related”CLAUDE.md priority #8 (origin of this principle) · development-principles.md (SSOT, errors-over-fallbacks, automate-over-manual)