gh-rsmdt-the-startup-plugins-start/skills/agent-delegation/examples/file-coordination.md

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