@syntesseraai/opencode-feature-factory 0.2.13 → 0.2.15

package/skills/ff-delegation/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: ff-delegation
+description: Enables agents to parallelize work by delegating tasks to specialized sub-agents. Use this skill to identify parallelization opportunities, select appropriate agents, coordinate multiple agents working simultaneously, and manage shared context through the .feature-factory/agents/ directory.
+license: MIT
+compatibility: opencode
+metadata:
+  audience: agents
+  category: orchestration
+---
+
+# Delegation Skill
+
+Use this skill to parallelize work across multiple specialized agents using UUID-based context tracking.
+
+## When to Use
+
+You MUST delegate when:
+
+- **Multiple independent tasks** can be worked on simultaneously
+- **Specialized expertise** is needed (security, architecture, research)
+- **Validation** is required from multiple perspectives
+- **Information gathering** can happen in parallel with planning
+
+## Core Concepts
+
+### UUID-Based Tracking
+
+Every agent instance gets a unique UUID:
+
+- **Your UUID**: Generated when you start working
+- **Child UUIDs**: Generated for each delegated agent
+- **Parent-Child Links**: Track delegation chains
+- **Context Files**: Stored in `.feature-factory/agents/{agent}-{uuid}.md`
+
+### Available Tools
+
+- **ff-agents-current**: List all active agents with their UUIDs
+- **ff-agents-show**: View detailed context for a specific agent by UUID
+- **ff-agents-clear**: Clean up agent context files when done
+
+## Delegation Process
+
+### Step 1: Generate Your UUID
+
+Create a unique identifier for this agent instance:
+
+```
+Generate UUID: $MY_UUID = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+```
+
+### Step 2: Document Your Context
+
+Write your task to `.feature-factory/agents/`:
+
+```markdown
+Write file: .feature-factory/agents/{agent}-{$MY_UUID}.md
+Content:
+
+---
+
+id: "{$MY_UUID}"
+agent: {your-agent-name}
+title: "{task title}"
+description: "{task description}"
+folder: "{working directory}"
+status: in-progress
+started: "{ISO timestamp}"
+session: {session ID}
+parent: null
+delegated_to: []
+
+---
+
+## Task Context
+
+{Full context of what you're working on}
+
+## Progress
+
+- [x] Task started
+- [ ] Analysis complete
+- [ ] Implementation pending
+
+## Delegated Work
+
+No delegated work yet.
+```
+
+### Step 3: Identify Parallel Opportunities
+
+Ask: "What work can happen simultaneously?"
+
+Common parallel tasks:
+
+- **Research** + **Planning** (research tech while planning architecture)
+- **Security audit** + **Architecture review** (different perspectives)
+- **Multiple file modifications** (if in different modules)
+- **Test writing** + **Documentation** (while implementation continues)
+
+### Step 4: Select Agents
+
+Use this matrix:
+
+| Task Type      | Primary Agent        | Fallback | Coordination |
+| -------------- | -------------------- | -------- | ------------ |
+| Security audit | @ff-security         | @general | Parallel     |
+| Code quality   | @ff-review           | @general | Parallel     |
+| Architecture   | @ff-well-architected | @general | Parallel     |
+| Requirements   | @ff-acceptance       | @explore | Blocking     |
+| Research       | @research            | @general | Async        |
+| Exploration    | @explore             | @general | Parallel     |
+| Implementation | @general             | N/A      | Sequential   |
+
+### Step 5: Delegate in Parallel
+
+Generate child UUIDs and delegate:
+
+```
+Generate child UUIDs:
+- $CHILD_1 = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+- $CHILD_2 = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+- $CHILD_3 = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+
+Delegate simultaneously:
+Task(ff-security): "Security audit: Check OAuth implementation for CSRF vulnerabilities. Write context to .feature-factory/agents/ff-security-{$CHILD_1}.md"
+Task(research): "Research: Find best OAuth libraries for Node.js. Write context to .feature-factory/agents/research-{$CHILD_2}.md"
+Task(ff-acceptance): "Validate: Check if acceptance criteria are clear. Write context to .feature-factory/agents/ff-acceptance-{$CHILD_3}.md"
+```
+
+Update your context with delegated agents:
+
+```markdown
+Update file: .feature-factory/agents/{agent}-{$MY_UUID}.md
+delegated_to:
+
+- "{$CHILD_1}"
+- "{$CHILD_2}"
+- "{$CHILD_3}"
+```
+
+### Step 6: Monitor Progress
+
+Use ff-agents-current to check status:
+
+```
+ff-agents-current()
+```
+
+Example response:
+
+```json
+{
+  "count": 4,
+  "agents": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "agent": "planning",
+      "title": "Implement OAuth",
+      "status": "in-progress"
+    },
+    {
+      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+      "agent": "ff-security",
+      "title": "OAuth security audit",
+      "status": "completed",
+      "parent": "550e8400-e29b-41d4-a716-446655440000"
+    }
+  ]
+}
+```
+
+### Step 7: Read Results
+
+View specific agent details:
+
+```
+ff-agents-show(id: "6ba7b810-9dad-11d1-80b4-00c04fd430c8")
+```
+
+Or read the context file directly:
+
+```
+Read file: .feature-factory/agents/ff-security-6ba7b810-9dad-11d1-80b4-00c04fd430c8.md
+```
+
+### Step 8: Aggregate and Act
+
+Combine findings from all delegated agents:
+
+```markdown
+## Summary of Delegated Work
+
+### Security Audit (@ff-security)
+
+- **Status:** Completed
+- **Key Finding:** CSRF protection required
+- **Recommendation:** Use state parameter in OAuth flow
+
+### Research (@research)
+
+- **Status:** Completed
+- **Key Finding:** Passport.js is most popular library
+- **Recommendation:** Use passport-oauth2 strategy
+
+### Acceptance Validation (@ff-acceptance)
+
+- **Status:** Completed
+- **Result:** All criteria are clear and achievable
+```
+
+### Step 9: Clean Up
+
+When ALL work is complete:
+
+```
+ff-agents-clear()
+```
+
+Or clear specific agents:
+
+```
+ff-agents-clear(id: "6ba7b810-9dad-11d1-80b4-00c04fd430c8")
+ff-agents-clear(sessionID: "session-abc123")
+ff-agents-clear(agent: "research")
+```
+
+## Example: Planning with Parallel Research
+
+**Scenario:** Implementing OAuth authentication
+
+```markdown
+## My Workflow
+
+1. **Generate my UUID**
+   - $MY_UUID = "550e8400-e29b-41d4-a716-446655440000"
+
+2. **Document my context**
+   - Write to .feature-factory/agents/planning-550e8400-e29b-41d4-a716-446655440000.md
+
+3. **Identify parallel tasks**
+   - Security audit (can run in parallel)
+   - Research OAuth libraries (can run in parallel)
+   - Validate acceptance criteria (can run in parallel)
+
+4. **Generate child UUIDs**
+   - $SECURITY_UUID = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+   - $RESEARCH_UUID = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
+   - $ACCEPTANCE_UUID = "6ba7b812-9dad-11d1-80b4-00c04fd430c8"
+
+5. **Delegate in parallel**
+   - Task(ff-security): "Audit OAuth..." (use $SECURITY_UUID)
+   - Task(research): "Research OAuth..." (use $RESEARCH_UUID)
+   - Task(ff-acceptance): "Validate..." (use $ACCEPTANCE_UUID)
+
+6. **Update my context**
+   - Add delegated_to: [$SECURITY_UUID, $RESEARCH_UUID, $ACCEPTANCE_UUID]
+
+7. **Monitor progress**
+   - ff-agents-current()
+
+8. **Read results**
+   - ff-agents-show(id: $SECURITY_UUID)
+   - ff-agents-show(id: $RESEARCH_UUID)
+   - ff-agents-show(id: $ACCEPTANCE_UUID)
+
+9. **Create informed plan**
+   - Use all findings to create comprehensive plan
+
+10. **Clean up**
+    - ff-agents-clear()
+```
+
+## Best Practices
+
+1. **Always document context first** - Other agents need to know what you're working on
+2. **Generate UUIDs immediately** - Every agent instance needs a unique ID
+3. **Prefer parallel over sequential** - Unless tasks have dependencies
+4. **Use specific instructions** - Delegated agents need clear, actionable tasks
+5. **Monitor with ff-agents-current** - Check status before proceeding
+6. **Read full context** - Don't just check status, read the actual findings
+7. **Clean up immediately** - Don't leave context files after completion
+8. **Track parent-child relationships** - Use parent and delegated_to fields
+
+## Common Mistakes to Avoid
+
+- ❌ **Delegating without context** - Always write your context file first
+- ❌ **Reusing UUIDs** - Generate a new UUID for every agent instance
+- ❌ **Waiting sequentially** - Don't wait for one agent to finish before starting another
+- ❌ **Forgetting cleanup** - Always call ff-agents-clear() when done
+- ❌ **Vague instructions** - "Check security" is too vague; "Audit OAuth flow for CSRF vulnerabilities" is specific
+- ❌ **Ignoring results** - Actually read the context files from delegated agents
+- ❌ **Not updating delegated_to** - Track which agents you've delegated to
+
+## Integration with Other Skills
+
+Always use with:
+
+- **ff-mini-plan** - For breaking down tasks before delegation
+- **ff-todo-management** - For tracking parallel tasks
+- **ff-report-templates** - For formatting aggregated results
+
+## Fallback Strategy
+
+If specialized agents are unavailable:
+
+1. **@ff-security** → @general with security focus
+2. **@ff-review** → @general with code review focus
+3. **@ff-well-architected** → @general with architecture focus
+4. **@ff-acceptance** → @explore for requirements gathering
+5. **@research** → @general with research focus
+6. **@explore** → @general with read-only tools
+
+When falling back, be more specific in your instructions to compensate for the generalist nature of @general.