diff --git a/_sidebar.md b/_sidebar.md index 17acc05..27c6471 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -128,22 +128,28 @@ * [Ai agent context injection pipelines](docs/ai-agent-context-injection-pipelines.md) * [Ai agent context pruning](docs/ai-agent-context-pruning.md) * [Ai agent dynamic context pruning](docs/ai-agent-dynamic-context-pruning.md) + * [Ai agent event driven orchestration](docs/ai-agent-event-driven-orchestration.md) + * [Ai agent fault tolerance patterns](docs/ai-agent-fault-tolerance-patterns.md) * [Ai agent memory architectures](docs/ai-agent-memory-architectures.md) * [Ai agent multi model consensus](docs/ai-agent-multi-model-consensus.md) * [Ai agent orchestration patterns](docs/ai-agent-orchestration-patterns.md) * [Ai agent orchestration](docs/ai-agent-orchestration.md) * [Ai agent self healing architectures](docs/ai-agent-self-healing-architectures.md) * [Ai agent semantic routing](docs/ai-agent-semantic-routing.md) + * [Ai agent task decomposition patterns](docs/ai-agent-task-decomposition-patterns.md) * [Ai agent tool calling architectures](docs/ai-agent-tool-calling-architectures.md) * [Ai agent vibe coding state machines](docs/ai-agent-vibe-coding-state-machines.md) + * [Ai agent zero trust security boundaries](docs/ai-agent-zero-trust-security-boundaries.md) * [Antigravity ide vibe coding](docs/antigravity-ide-vibe-coding.md) * [Cursor memory structures](docs/cursor-memory-structures.md) * [Vibe coding agents](docs/vibe-coding-agents.md) * [Vibe coding autonomous testing patterns](docs/vibe-coding-autonomous-testing-patterns.md) + * [Vibe coding cognitive load balancing](docs/vibe-coding-cognitive-load-balancing.md) * [Vibe coding deterministic patterns](docs/vibe-coding-deterministic-patterns.md) * [Vibe coding dynamic context pruning](docs/vibe-coding-dynamic-context-pruning.md) * [Vibe coding multi agent state sync](docs/vibe-coding-multi-agent-state-sync.md) * [Vibe coding predictive context orchestration](docs/vibe-coding-predictive-context-orchestration.md) + * [Vibe coding self reflection loops](docs/vibe-coding-self-reflection-loops.md) * [Vibe coding swarm intelligence patterns](docs/vibe-coding-swarm-intelligence-patterns.md) * [Vibe coding telemetry patterns](docs/vibe-coding-telemetry-patterns.md) * [Vibe coding zero approval workflows](docs/vibe-coding-zero-approval-workflows.md) diff --git a/docs/ai-agent-task-decomposition-patterns.md b/docs/ai-agent-task-decomposition-patterns.md new file mode 100644 index 0000000..cc31ffe --- /dev/null +++ b/docs/ai-agent-task-decomposition-patterns.md @@ -0,0 +1,157 @@ +--- +technology: Agnostic +domain: AI Agent Orchestration +level: Senior/Architect +version: 2026-v1.0 +tags: [ai agent orchestration, task decomposition, vibe coding, best practices, multi-agent systems] +ai_role: Autonomous Knowledge Evangelist +last_updated: 2026-10-15 +--- + +> 📦 [best-practise](../README.md) / 📄 [docs](./) + +# 🤖 AI Agent Task Decomposition Patterns Best Practices + +In 2026 **Vibe Coding** environments, monolithic task assignments are a primary source of AI hallucinations and non-deterministic behavior. High-performing autonomous agents operate on strict boundaries. "Task Decomposition Patterns" provide the framework for breaking complex instructions into bounded, verifiable, and executable atomic operations. + +This document outlines the architectural standard for structuring deterministic task decomposition within multi-agent orchestration systems. + +--- + +## 🧩 The Decomposition Hierarchy + +> [!IMPORTANT] +> Never prompt an agent with a complex, multi-step goal (e.g., "Refactor the authentication module"). Instructions MUST be split into a hierarchy of granular operations (e.g., "Analyze dependencies", "Extract auth guard", "Verify token strategy"). + +### Decomposition Layers + +1. **Strategic Intent (User Request):** The high-level objective provided by the user. +2. **Orchestrator Planning:** Decomposing the intent into sequential or parallel phases. +3. **Atomic Sub-tasks:** Isolated tasks with explicit input/output contracts. +4. **Agent Execution:** Deterministic code generation or verification based on a single sub-task context. + +> [!NOTE] +> Bounding tasks explicitly allows for targeted context injection, significantly improving code quality and agent reliability. + +--- + +## 🔄 The Pattern Lifecycle + +We enforce a strict four-step deterministic lifecycle for task orchestration to maintain repository fidelity. + +### ❌ Bad Practice + +```typescript +// Assigning a monolithic, unstructured task to an agent +async function processUserRequest(prompt: string, context: unknown) { + const result = await llm.generate({ + instruction: \`Execute this request completely: \${prompt}\`, + context: context + }); + + return executeCode(result.code); +} +``` + +### ⚠️ Problem + +Providing an open-ended request to a single LLM call overwhelms its context window and reasoning capacity. The agent attempts to solve architecture, implementation, and testing simultaneously, leading to incomplete code, architectural drift, and a high probability of syntax errors. Furthermore, there is no intermediate state to verify or debug. + +### ✅ Best Practice + +```typescript +// Deterministic Task Decomposition & Phased Execution +import { TaskPlanner, SubTaskSchema } from '@orchestration/planner'; +import { AgentRunner } from '@orchestration/runner'; +import { z } from 'zod'; + +const PlanSchema = z.object({ + id: z.string().uuid(), + subTasks: z.array(SubTaskSchema) +}); + +async function processUserRequest(prompt: string, context: unknown) { + // 1. Orchestrator decomposes intent into bounded sub-tasks + const rawPlan = await TaskPlanner.decompose(prompt, context); + const plan = PlanSchema.parse(rawPlan); + + const executionResults = []; + + // 2. Sequential execution of atomic tasks + for (const task of plan.subTasks) { + // Retrieve bounded context specific to this sub-task + const taskContext = await fetchBoundedContext(task); + + const result = await AgentRunner.executeAtomicTask({ + instruction: task.directive, + boundedContext: taskContext + }); + + // 3. Verification gate before proceeding + if (!result.success) { + throw new Error(\`Sub-task failed: \${task.id}. Halting execution.\`); + } + + executionResults.push(result); + } + + return combineResults(executionResults); +} +``` + +### 🚀 Solution + +By formalizing a planning stage, we decompose the request into an array of strictly typed sub-tasks validated against a Zod schema. Iterating over these sub-tasks allows for dynamic, targeted context injection (`fetchBoundedContext`). Importantly, execution is gated: if a sub-task fails, the workflow halts, preventing cascading failures. This ensures a deterministic, verifiable, and highly stable agent workflow. + +--- + +## 📊 Task Execution Topology + +Decomposition strategy dictates how tasks are scheduled and resolved within the agent swarm. + +| Task Category | Execution Strategy | Context Boundary | Verification Gate | +| :--- | :--- | :--- | :--- | +| **Analysis & Planning** | Single Orchestrator | Broad Repository Map | Schema Validation | +| **Refactoring/Implementation** | Sequential Agents | Single Module/File | Unit/AST Tests | +| **Code Review/Security** | Parallel Agents | Specific Diffs | Rule Heuristics | + +--- + +## 🧠 Decomposition Data Flow + +The following visualizes how a monolithic intent is shattered into executable components. + +```mermaid +graph TD + A[User Intent: "Migrate DB to new schema"] --> B{Orchestrator Planner} + + B --> C[Sub-task 1: Read current schema] + B --> D[Sub-task 2: Generate migration script] + B --> E[Sub-task 3: Update entity models] + + C --> F{Sequential Execution Engine} + D --> F + E --> F + + F -->|Bounded Context 1| G[Agent: Read File] + G --> H{Verification Gate} + + H -->|Success| I[Proceed to Sub-task 2] + H -->|Fail| J[Halt & Report] +``` + +--- + +## 📝 Actionable Checklist for Task Decomposition + +To implement effective task decomposition, verify these constraints: + +- [ ] Ensure the orchestration pipeline explicitly separates planning from execution. +- [ ] Define precise Zod schemas for all sub-task inputs and outputs to replace `any` with validated `unknown`. +- [ ] Verify that context is fetched dynamically per sub-task, rather than globally for the entire request. +- [ ] Implement explicit "Verification Gates" between sequential tasks to halt execution on failure. +- [ ] Confirm adherence to the Bad -> Problem -> Best -> Solution lifecycle in all implemented rules. + +
+ +[Back to Top](#-ai-agent-task-decomposition-patterns-best-practices)