name	decision-logic-framework
description	Decision rules for Claude Code skills, scripts, MDs, and workflows - project-agnostic patterns
version	1.0.0
modularized	true
last_updated	Tue Dec 02 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
compliance_score	100
auto_trigger_keywords	skill creation, script vs md, naming convention, workflow decision, tier selection, single file rule, prefix naming, when to use script, when to use markdown
color	blue

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

Install Skill

SKILL.md