decision-logic-framework

Quick Reference (30 seconds)

Core Principle: Clear separation between Agents (orchestrators) and Skills (capabilities).

Component	Location	Contains
Agents	.claude/agents/	workflows/ (TOON + MD steps)
Skills	.claude/skills/	scripts/ (UV Python) OR modules/ (single-file MDs)

Decision Tree:

Need external Python packages? → UV Script (.py)
Need system commands?          → UV Script (.py)
Reference/documentation?       → Single-File MD (.md)
Simple data/rules?             → Single-File MD (.md)

Naming (Mandatory Prefixes):

• Scripts: {skill}_{action}.py (underscore)
• Modules: {category}-{topic}.md (hyphen)

---

Architecture Overview

Agents = Orchestrators with Workflows

.claude/agents/{category}/{agent-name}/
├── {agent-name}.md              # Agent definition
└── workflows/                    # Agent-owned workflows
    └── {workflow-name}/
        ├── WORKFLOW.toon        # Structure (TOON tabular)
        ├── instructions.md      # Overall guidance
        ├── checklist.md         # Validation (tier-2+)
        └── steps/
            └── step-NN-{action}.md

Skills = Capabilities with Scripts OR Modules

.claude/skills/{skill-name}/
├── SKILL.md                     # Main entry (REQUIRED)
├── scripts/                     # For complex automation (OPTIONAL)
│   └── {skill}_{action}.py      # UV scripts with prefix
└── modules/                     # For simple reference MDs (OPTIONAL)
    └── {category}-{topic}.md    # Single-file MDs with prefix

---

When to Use This Skill

Use this skill when:

• Creating a new skill and deciding between scripts vs modules
• Choosing workflow complexity tier (0-3)
• Naming new files (scripts or modules)
• Understanding the architecture separation
• Reverse-engineering third-party apps

Load Order: This skill should be loaded FIRST when creating any new skill, agent, or workflow.

---

Available Modules

Module	Purpose	When to Load
rule-script-vs-md.md	Decision logic for script vs MD	Creating new skill content
rule-naming-convention.md	Prefix naming system	Naming any new file
rule-skill-tiers.md	Tier 1-4 skill complexity	Assessing skill scope
rule-workflow-complexity.md	Tier 0-3 workflow selection	Creating workflows
pattern-single-file.md	Universal single-file rules	Reviewing file constraints

Available Schemas

Schema	Purpose	When to Load
workflow-schema.toon	Canonical WORKFLOW.toon format	Creating any workflow
step-schema.md	Template for step-NN-{action}.md	Creating workflow steps

---

Decision Flowcharts

Script vs MD Decision

┌─────────────────────────────────────┐
│     NEW SKILL CONTENT NEEDED        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ Requires external Python packages?  │
│ (httpx, pandas, click, psutil...)   │
├─────────────┬───────────────────────┤
│     YES     │          NO           │
│     ↓       │          ↓            │
│  UV SCRIPT  │  Requires shell/sys?  │
└─────────────┴───────────┬───────────┘
                          │
              ┌───────────┴───────────┐
              │     YES     │    NO   │
              │     ↓       │    ↓    │
              │  UV SCRIPT  │  MD OK  │
              └─────────────┴─────────┘

Workflow Tier Selection

┌─────────────────────────────────────┐
│      WORKFLOW COMPLEXITY            │
└──────────────┬──────────────────────┘
               │
    ┌──────────┼──────────┬───────────┐
    ▼          ▼          ▼           ▼
┌───────┐ ┌───────┐ ┌─────────┐ ┌─────────┐
│Tier 0 │ │Tier 1 │ │ Tier 2  │ │ Tier 3  │
│1 step │ │3-5    │ │ 5-10    │ │ 10+     │
│hotfix │ │simple │ │ medium  │ │ complex │
└───────┘ └───────┘ └─────────┘ └─────────┘

---

Prefix Naming Quick Reference

Scripts (UV Python)

Pattern: {skill-name}_{action}.py
Separator: underscore (_)

Examples:
  kalshi_get-market.py
  kalshi_search-events.py
  system_analyze-cpu.py
  builder_generate-skill.py

Modules (Single-File MDs)

Pattern: {category}-{topic}.md
Separator: hyphen (-)

Categories: api, pattern, rule, guide, schema, example

Examples:
  api-endpoints.md
  pattern-authentication.md
  rule-naming-convention.md
  guide-quick-start.md

---

Works Well With

Agents:

• builder-skill - Skill creation with tier system
• builder-workflow - TOON + MD workflow generation
• builder-agent - Agent with workflows/ generation

Skills:

• moai-library-toon - TOON format reference
• moai-foundation-core - Core execution rules
• builder-skill-uvscript - UV script examples

Commands:

• /moai:1-plan - SPEC generation with decision framework
• /builder:generate-skill - Skill creation workflow

---

Version: 1.0.0 Status: Active Last Updated: 2025-12-02