TenerifeProp/.kilo/rules/atomic-tasks.md

Atomic Task Decomposition Rules

CRITICAL: Agents must execute ONE small task per invocation. Never assign broad multi-step tasks.

Problem

Agents frequently hang or produce incomplete results when given large, complex tasks. Token budgets are exhausted before completion.

Solution: Atomic Task Principle

1 agent invocation = 1 atomic task = 1 clear outcome = 1 verification

Atomic Task Definition

An atomic task meets ALL criteria:

• Completable in under 5 minutes
• Has a single clear deliverable
• Can be verified independently (test, lint, build)
• Produces at most 3-5 files
• No more than 100 lines changed per file

Decomposition Rules

Before Delegating

1. Decompose first: Break any task into 3-5 atomic subtasks
2. Order by dependency: Subtasks that depend on others come later
3. Each subtask gets its own agent invocation

Task Sizing Guide

Task Type	Max Scope	Max Files	Max Lines
Model/Entity creation	1 model + 1 migration	2	80
API endpoint	1 endpoint + 1 test	2	100
Service method	1 method + 1 test	2	60
UI Component	1 component + 1 test	2	80
Bug fix	1 fix + 1 test	2	50
Config change	1 config file	1	30

Violation Examples (DON'T)

❌ "Implement the entire e-commerce backend"
❌ "Create all models, controllers, and services for the product module"
❌ "Build the admin panel with all CRUD operations"
❌ "Fix all failing tests"

Correct Examples (DO)

✅ "Create Product model with migration and factory"
✅ "Add POST /api/products endpoint with validation and test"
✅ "Build ProductCard.vue component with props and unit test"
✅ "Fix TypeError in OrderService::calculateTotal - add null check"

Orchestrator Decomposition Protocol

When orchestrator receives a task:

1. Count atomic subtasks: How many minimal units?
2. If > 5 subtasks: Create sub-milestone issues in Gitea for tracking
3. Delegate one subtask at a time via Task tool
4. Wait for completion before delegating next
5. Verify output after each subtask
6. Update Gitea issue with progress after each subtask

Agent Self-Regulation

Each agent must:

1. Check task size: If too broad, split it and report back
2. Focus on one deliverable: Don't expand scope
3. Complete before extending: Finish the assigned task, don't add extras
4. Report precisely: "Done: X" not "I also did Y and Z"

Token Budget per Atomic Task

Task Complexity	Token Budget	Time Budget
Simple (config, fix)	5,000	2 min
Medium (endpoint, component)	10,000	5 min
Complex (multi-service flow)	20,000	10 min

If approaching budget, STOP and report progress. Delegate continuation to next invocation.

Pipeline Step Granularity

Pipeline steps must be fine-grained:

❌ Step 3: "Implement Backend" (too broad)
✅ Step 3a: "Create Product model + migration"
✅ Step 3b: "Add GET /api/products endpoint"
✅ Step 3c: "Add POST /api/products endpoint"
✅ Step 3d: "Create ProductService with list() and create()"
✅ Step 3e: "Add ProductRepository with filtering"

Each sub-step is its own agent invocation with its own Gitea comment.