Skip to content

TidyFactor Skill Architect — Master Governance & Methodology Engine v2.0.2

Master Architecture & Governance Engine for AI Coding Agent Skills
Enforces the 12 Structural Rules of TidyFactor Skills across Google Antigravity, Claude Code, Cursor, OpenAI Codex, and Windsurf.

tidyfactor-skill-architect is the foundational governance layer that enforces strict structural discipline, deterministic quality bars, and behavioral parity across all AI coding agent skills.

🎯 Core Value Propositions

  1. Dispatcher Discipline (Rule 1): Constrains SKILL.md to a lightweight router (~350 tokens) declaring commands and loads without in-line execution slop or context bloat.
  2. One Workflow = One Outcome (Rule 2): Mandates that every workflow has exactly one single deliverable with an explicit, verifiable ## Validation checklist.
  3. Operational Memory Architecture (Rule 3): Pure schemas, code patterns, and technical rules—zero narrative filler or marketing commentary.
  4. 12 Non-Negotiable Structural Rules: Enforces zero empty structures, trigger-justified growth, strict YAML frontmatter parsing, memory freshness, and native compiler-wrapping tooling across the entire ecosystem.

🚀 Installation & Agent Setup

# Direct NPM Skill Scaffolding
npx @tidyfactor/cli-skill-architect add-skill

# Or install globally via NPM
npm install -g @tidyfactor/skill-architect

⚡ Slash Commands Reference

Command Lifecycle Trigger Description
/init INIT Scaffold a new compliant skill directory following the 4-layer topology
/audit IMPROVE Audit an existing skill against the 12 structural rules and quantify compliance score (X/12)
/test TEST Generate \(\ge 3\) realistic test scenarios (happy-path, edge-case, negative) in tests/scenarios.md
/grow IMPROVE Evaluate whether a skill should grow a new file based on quantifiable size/branch triggers

🏛️ The 12 Structural Rules of TidyFactor Skills

1. Dispatcher Discipline        → SKILL.md is a lean router (~350 tokens)
2. One Workflow = One Outcome    → Single deliverable with validation checklist
3. Operational Memory Only       → Technical patterns and schemas, zero slop
4. No Empty Structures           → Clean, flattened directory topology
5. Philosophy Isolation          → Technical execution separated from brand voice
6. Trigger-Justified Growth      → New files added strictly per lifecycle triggers
7. Native Toolchain Wrapping     → Wraps tsc, node, python, git, OS APIs
8. Behavioral Parity & SemVer    → Identical cross-agent execution and SSOT releases
9. Platform Compatibility & YAML → Valid YAML parsing (yaml.safe_load()), description <= 1024 chars, mandatory double quotes "..."
10. Tool Permission Scope        → Declare languages, mutations, and network in SKILL.md
11. Memory Freshness Gate        → Required <!-- last-verified: YYYY-MM-DD --> (<= 180 days)
12. Skill vs MCP Boundary        → Static prompt logic in skills; dynamic APIs in MCP

🧠 The Contextual Decision Layer (CDL Pattern)

For complex skills where execution depends on high-impact architectural choices prior to code generation (such as tidyfactor-styler or tidyfactor-next):

  1. Thin Arbitration Protocol (memory/decision-points.md): Defines triggers, boolean skip conditions, and references existing memory catalogs without duplicating options.
  2. Pre-Flight Discovery & Brief (/brief): Runs an interactive discovery interview and caches project baselines in .tidyfactor/<skill>-brief.md for silent downstream runs.
  3. Single-Round Batching & Priority: Batches unresolved ambiguities into a single round (maximum 3 questions) with strict priority resolution (D1 > D3 > D2 > D4 > D5).
  4. Direct Invocation vs. Redesign Invariants: Direct command calls always present full options; redesign workflows silently preserve established project baselines.
  5. Decision Alignment Critique: Expands pre-emit quality self-critique with Axis 7 (D) to score alignment against the confirmed brief before emission.

🛠️ Automated Integrity Validation Engine

The skill repository includes an automated 11-point validation engine:

# Run the automated integrity suite
python tools/validate_skill.py

Checks SemVer synchronization across all metadata files, YAML frontmatter syntax via yaml.safe_load(), token budgets, memory freshness timestamps, and test scenario coverage.