feat(docs): autonomous structured expansion on AI Agent Task Decomposition Patterns

_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)

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.
+
+<br>
+
+[Back to Top](#-ai-agent-task-decomposition-patterns-best-practices)