Initial commit

skills/agent-delegation/examples/file-coordination.md

@@ -0,0 +1,495 @@
+# Example: File Coordination for Parallel Agents
+
+This example shows how to prevent file path collisions when multiple agents create documentation in parallel.
+
+## Scenario
+
+**User Request:** "Document our codebase patterns for authentication, caching, and error handling"
+
+## Initial Decomposition (Incorrect)
+
+```
+❌ WRONG APPROACH
+
+Activities:
+1. Document authentication patterns
+2. Document caching patterns
+3. Document error handling patterns
+
+All parallel, all OUTPUT: "docs/patterns/[pattern-name].md"
+
+Problem: What if agents choose same filename?
+- Agent 1 might create: docs/patterns/auth.md
+- Agent 2 might create: docs/patterns/cache.md
+- Agent 3 might create: docs/patterns/error.md
+
+OR worse:
+- Agent 1: docs/patterns/authentication.md
+- Agent 2: docs/patterns/authentication-patterns.md
+- Both trying to document auth? Collision!
+
+Result: Ambiguous, potential collisions, inconsistent naming
+```
+
+## Correct Decomposition (File Coordination)
+
+```
+✅ CORRECT APPROACH
+
+Activities:
+1. Document authentication patterns
+   - OUTPUT: docs/patterns/authentication-flow.md (EXPLICIT PATH)
+
+2. Document caching patterns
+   - OUTPUT: docs/patterns/caching-strategy.md (EXPLICIT PATH)
+
+3. Document error handling patterns
+   - OUTPUT: docs/patterns/error-handling.md (EXPLICIT PATH)
+
+File Coordination Check:
+✅ All paths explicit and unique
+✅ No ambiguity in naming
+✅ No collision risk
+
+Status: SAFE FOR PARALLEL EXECUTION
+```
+
+## Agent Prompts with File Coordination
+
+### Agent 1: Authentication Pattern
+
+```
+DISCOVERY_FIRST: Before starting, check existing documentation:
+    - List docs/patterns/ directory
+    - Search for existing auth-related files
+    - Note naming conventions used
+    - Check if authentication-flow.md already exists
+
+FOCUS: Document authentication patterns discovered in codebase
+    - JWT token generation and validation
+    - Password hashing (bcrypt usage)
+    - Session management approach
+    - Protected route patterns
+    - Error responses for auth failures
+
+EXCLUDE:
+    - Don't document caching (Agent 2 handles this)
+    - Don't document error handling generally (Agent 3 handles this)
+    - Don't create multiple files (single document)
+    - Don't modify existing authentication files if they exist
+
+CONTEXT: Documenting patterns found in src/middleware/auth.*, src/routes/auth.*
+    - Focus on how authentication works, not implementation details
+    - Use pattern template: docs/templates/pattern-template.md
+    - Follow existing documentation style
+
+OUTPUT: EXACTLY this path: docs/patterns/authentication-flow.md
+    - If file exists: STOP and report (don't overwrite)
+    - If file doesn't exist: Create new
+    - Use pattern template structure
+    - Include code examples from codebase
+
+SUCCESS: Authentication patterns documented
+    - File created at exact path specified
+    - Follows pattern template
+    - Includes JWT, bcrypt, and session patterns
+    - Code examples are accurate
+    - No collision with other agents
+
+TERMINATION:
+    - Documentation complete at specified path
+    - File already exists (report to user)
+    - No authentication patterns found in codebase
+```
+
+### Agent 2: Caching Pattern
+
+```
+DISCOVERY_FIRST: Before starting, check existing documentation:
+    - List docs/patterns/ directory
+    - Search for existing cache-related files
+    - Note naming conventions
+    - Check if caching-strategy.md already exists
+
+FOCUS: Document caching patterns discovered in codebase
+    - Redis usage patterns
+    - Cache key naming conventions
+    - TTL (time-to-live) strategies
+    - Cache invalidation approaches
+    - What gets cached and why
+
+EXCLUDE:
+    - Don't document authentication (Agent 1 handles this)
+    - Don't document error handling (Agent 3 handles this)
+    - Don't create multiple files (single document)
+    - Don't overlap with Agent 1's work
+
+CONTEXT: Documenting patterns found in src/cache/*, src/services/*
+    - Focus on caching strategy, not Redis API details
+    - Use pattern template
+    - Follow existing documentation style
+
+OUTPUT: EXACTLY this path: docs/patterns/caching-strategy.md
+    - If file exists: STOP and report (don't overwrite)
+    - If file doesn't exist: Create new
+    - Use pattern template structure
+    - Include code examples from codebase
+
+SUCCESS: Caching patterns documented
+    - File created at exact path specified
+    - Follows pattern template
+    - Includes Redis patterns and cache strategies
+    - No collision with other agents
+
+TERMINATION:
+    - Documentation complete at specified path
+    - File already exists (report)
+    - No caching patterns found
+```
+
+### Agent 3: Error Handling Pattern
+
+```
+DISCOVERY_FIRST: Before starting, check existing documentation:
+    - List docs/patterns/ directory
+    - Search for existing error-related files
+    - Note naming conventions
+    - Check if error-handling.md already exists
+
+FOCUS: Document error handling patterns discovered in codebase
+    - Error class hierarchy
+    - HTTP status code mapping
+    - Error response format
+    - Logging strategy for errors
+    - Recovery patterns
+
+EXCLUDE:
+    - Don't document authentication (Agent 1's domain)
+    - Don't document caching (Agent 2's domain)
+    - Don't create multiple files
+    - Don't overlap with other agents
+
+CONTEXT: Documenting patterns found in src/errors/*, src/middleware/error.*
+    - Focus on error handling strategy and patterns
+    - Use pattern template
+    - Follow existing documentation style
+
+OUTPUT: EXACTLY this path: docs/patterns/error-handling.md
+    - If file exists: STOP and report (don't overwrite)
+    - If file doesn't exist: Create new
+    - Use pattern template structure
+    - Include code examples
+
+SUCCESS: Error handling patterns documented
+    - File created at exact path specified
+    - Follows pattern template
+    - Includes error classes and response patterns
+    - No collision with other agents
+
+TERMINATION:
+    - Documentation complete at specified path
+    - File already exists (report)
+    - No error handling patterns found
+```
+
+## File Coordination Checklist
+
+Before launching these agents:
+
+```
+📋 File Coordination Pre-Flight Check
+
+Agent 1 OUTPUT: docs/patterns/authentication-flow.md
+Agent 2 OUTPUT: docs/patterns/caching-strategy.md
+Agent 3 OUTPUT: docs/patterns/error-handling.md
+
+✅ All paths are explicit (no ambiguity)
+✅ All paths are unique (no two agents write same file)
+✅ All paths follow convention (docs/patterns/[name].md)
+✅ All agents instructed to check if file exists first
+✅ All agents instructed to STOP if collision detected
+
+File Collision Risk: NONE
+Safe to launch in parallel: YES
+```
+
+## Execution Flow
+
+### Launch All Three Agents in Parallel
+
+```
+🚀 Launching 3 parallel documentation agents
+
+Agent 1: Authentication Pattern → RUNNING
+  TARGET: docs/patterns/authentication-flow.md
+
+Agent 2: Caching Pattern → RUNNING
+  TARGET: docs/patterns/caching-strategy.md
+
+Agent 3: Error Handling Pattern → RUNNING
+  TARGET: docs/patterns/error-handling.md
+
+File coordination: ✅ All unique paths
+Collision risk: ✅ None
+Parallel safety: ✅ Confirmed
+```
+
+### Monitoring for Collisions
+
+```
+⏳ Agents running...
+
+[Agent 1] Checking: docs/patterns/authentication-flow.md → NOT EXISTS
+[Agent 1] Safe to create → PROCEEDING
+
+[Agent 2] Checking: docs/patterns/caching-strategy.md → NOT EXISTS
+[Agent 2] Safe to create → PROCEEDING
+
+[Agent 3] Checking: docs/patterns/error-handling.md → NOT EXISTS
+[Agent 3] Safe to create → PROCEEDING
+
+No collisions detected. All agents proceeding independently.
+```
+
+### Completion
+
+```
+Agent 1: COMPLETE ✅ (22 minutes)
+  Created: docs/patterns/authentication-flow.md (3.2 KB)
+
+Agent 2: COMPLETE ✅ (18 minutes)
+  Created: docs/patterns/caching-strategy.md (2.8 KB)
+
+Agent 3: COMPLETE ✅ (25 minutes)
+  Created: docs/patterns/error-handling.md (4.1 KB)
+
+All agents complete. No collisions occurred.
+```
+
+## Results
+
+```
+📁 docs/patterns/
+├── authentication-flow.md    ✅ Created by Agent 1
+├── caching-strategy.md        ✅ Created by Agent 2
+└── error-handling.md          ✅ Created by Agent 3
+```
+
+**Total time:** 25 minutes (parallel)
+**Sequential would take:** 65 minutes
+**Time saved:** 40 minutes (61% faster)
+
+## Alternative Coordination Strategies
+
+### Strategy 1: Directory Separation
+
+If agents might create multiple files:
+
+```
+Agent 1 OUTPUT: docs/patterns/authentication/
+  - flow.md
+  - jwt-tokens.md
+  - session-management.md
+
+Agent 2 OUTPUT: docs/patterns/caching/
+  - redis-usage.md
+  - invalidation.md
+  - key-naming.md
+
+Agent 3 OUTPUT: docs/patterns/error-handling/
+  - error-classes.md
+  - response-format.md
+  - recovery-patterns.md
+```
+
+**Result:** Each agent owns a directory, no file collisions possible.
+
+### Strategy 2: Timestamp-Based Naming
+
+For logs or reports that accumulate:
+
+```
+Agent 1 OUTPUT: logs/auth-analysis-2025-01-24-10-30-00.md
+Agent 2 OUTPUT: logs/cache-analysis-2025-01-24-10-30-00.md
+Agent 3 OUTPUT: logs/error-analysis-2025-01-24-10-30-00.md
+```
+
+**Result:** Timestamps ensure uniqueness even if same topic.
+
+### Strategy 3: Agent ID Namespacing
+
+When dynamic number of agents:
+
+```
+For each module in [moduleA, moduleB, moduleC, moduleD]:
+  Launch agent with OUTPUT: analysis/module-${MODULE_NAME}.md
+
+Results:
+- analysis/module-moduleA.md
+- analysis/module-moduleB.md
+- analysis/module-moduleC.md
+- analysis/module-moduleD.md
+```
+
+**Result:** Template-based naming prevents collisions.
+
+## What Could Go Wrong (Anti-Patterns)
+
+### ❌ Anti-Pattern 1: Ambiguous Paths
+
+```
+BAD:
+Agent 1 OUTPUT: "Create pattern documentation"
+Agent 2 OUTPUT: "Document caching patterns"
+
+Problem: Where exactly? What filename?
+Result: Agents might choose same name or wrong location
+```
+
+### ❌ Anti-Pattern 2: Overlapping Domains
+
+```
+BAD:
+Agent 1 FOCUS: "Document authentication and security"
+Agent 2 FOCUS: "Document security patterns"
+
+Problem: Both might document auth security!
+Result: Duplicate or conflicting documentation
+```
+
+**Fix:** Clear FOCUS boundaries, explicit EXCLUDE
+
+### ❌ Anti-Pattern 3: No Existence Check
+
+```
+BAD:
+OUTPUT: docs/patterns/auth.md
+(No instruction to check if exists)
+
+Problem: If file exists, agent might overwrite
+Result: Lost documentation
+```
+
+**Fix:** Always include existence check in FOCUS or OUTPUT
+
+### ❌ Anti-Pattern 4: Generic Filenames
+
+```
+BAD:
+Agent 1 OUTPUT: docs/patterns/pattern.md
+Agent 2 OUTPUT: docs/patterns/patterns.md
+Agent 3 OUTPUT: docs/patterns/pattern-doc.md
+
+Problem: All similar, confusing, might collide
+Result: Unclear which agent created what
+```
+
+**Fix:** Descriptive, specific filenames
+
+## File Coordination Best Practices
+
+### 1. Explicit Paths
+
+✅ **Always specify exact OUTPUT path:**
+```
+OUTPUT: docs/patterns/authentication-flow.md
+NOT: "Document authentication patterns"
+```
+
+### 2. Unique Names
+
+✅ **Ensure all agents have unique filenames:**
+```
+Before launching:
+- Agent 1: authentication-flow.md
+- Agent 2: caching-strategy.md
+- Agent 3: error-handling.md
+✅ All unique → SAFE
+```
+
+### 3. Existence Checks
+
+✅ **Instruct agents to check before creating:**
+```
+OUTPUT: docs/patterns/authentication-flow.md
+- If file exists: STOP and report (don't overwrite)
+- If file doesn't exist: Create new
+```
+
+### 4. Clear Boundaries
+
+✅ **Use EXCLUDE to prevent overlap:**
+```
+Agent 1:
+FOCUS: Document authentication
+EXCLUDE: Don't document caching (Agent 2) or errors (Agent 3)
+
+Agent 2:
+FOCUS: Document caching
+EXCLUDE: Don't document auth (Agent 1) or errors (Agent 3)
+```
+
+### 5. Validation
+
+✅ **Check coordination before launching:**
+```
+Checklist:
+- [ ] All paths explicit
+- [ ] All paths unique
+- [ ] All agents have existence checks
+- [ ] Clear FOCUS boundaries
+- [ ] No overlap in domains
+```
+
+## Integration with Documentation Skill
+
+When these agents complete, documentation skill may activate:
+
+```
+Agent 1 completes → Creates authentication-flow.md
+  ↓
+Documentation skill notices "pattern" created
+  ↓
+Checks: Is this in correct location? (docs/patterns/ ✅)
+Checks: Does it follow template? (✅)
+Checks: Should it be cross-referenced? (Yes)
+  ↓
+Documentation skill adds cross-references:
+- Links to related authentication interfaces
+- Links to domain rules about user permissions
+```
+
+**Coordination:** Agent-delegation ensures unique paths, documentation skill ensures quality and linking.
+
+## Lessons Learned
+
+### What Worked
+
+✅ **Explicit paths:** Zero ambiguity, zero collisions
+✅ **Existence checks:** Prevented accidental overwrites
+✅ **Clear boundaries:** No domain overlap
+✅ **Parallel execution:** 61% time savings
+
+### What to Watch For
+
+⚠️ **Naming conventions:** Ensure consistency (kebab-case vs snake_case)
+⚠️ **Template usage:** All agents should use same template
+⚠️ **Directory structure:** Verify docs/patterns/ exists before launching
+
+## Reusable Coordination Template
+
+For any parallel file creation:
+
+```
+1. List all files to be created
+2. Verify all paths are unique
+3. Add existence checks to OUTPUT
+4. Use EXCLUDE to prevent overlap
+5. Launch in parallel with confidence
+```
+
+**This prevents:**
+- File path collisions
+- Accidental overwrites
+- Domain overlap
+- Naming inconsistencies