@syntesseraai/opencode-feature-factory 0.6.8 → 0.6.10

package/skills/ff-context-tracking/SKILL.md

@@ -1,573 +0,0 @@
----
-name: ff-context-tracking
-description: Critical skill for all agents to track their context, maintain awareness of other agents' activities, and properly clean up agent files when finished. Use this skill to ensure cross-agent visibility and prevent orphaned context files.
-license: MIT
-compatibility: opencode
-metadata:
-  audience: all-agents
-  category: coordination
-  priority: critical
----
-
-# Context Tracking Skill
-
-**⚠️ CRITICAL: ALL AGENTS MUST USE THIS SKILL**
-
-This skill ensures every agent maintains proper context, stays aware of other agents' activities, and cleans up after completion. Without proper context tracking, agents work in isolation, duplicate effort, and leave orphaned files.
-
-## Why Context Tracking Matters
-
-### Cross-Agent Visibility
-
-- **Know what others are doing** - Check `ff-agents-current()` before starting work
-- **Avoid conflicts** - Don't modify files another agent is working on
-- **Build on findings** - Read other agents' context to leverage their work
-- **Coordinate efforts** - Track parent-child relationships in delegation chains
-
-### Accountability
-
-- **Track progress** - Context files show what each agent is working on
-- **Debug issues** - When things go wrong, check agent contexts to understand what happened
-- **Audit trail** - Agent contexts provide history of who did what when
-
-### Resource Management
-
-- **Prevent clutter** - Clean up context files when done
-- **Avoid confusion** - Stale context files mislead about current state
-- **Free resources** - Remove completed agent contexts promptly
-
-## When to Use This Skill
-
-### REQUIRED - Use at these moments:
-
-1. **At START of EVERY task** - Create your context file immediately
-2. **Before DELEGATING** - Check existing agents to avoid conflicts
-3. **When MONITORING** - Check status of delegated agents
-4. **At END of EVERY task** - Clean up your context file
-5. **When TROUBLESHOOTING** - Read other agents' contexts to understand system state
-
-### Context File Lifecycle
-
-```
-START → Create Context → Work → Update Progress → Complete → Clean Up → END
-   ↑                                                           ↓
-   └────────────────── Monitor Others ←────────────────────────┘
-```
-
-## Core Workflow
-
-### Step 1: Check Existing Agents (BEFORE Starting)
-
-**ALWAYS check what other agents are doing before you start:**
-
-```
-ff-agents-current()
-```
-
-**Why this matters:**
-
-- Avoid working on the same files as another agent
-- Build upon research already completed by @ff-research
-- Don't duplicate security audits already done by @ff-security
-- Coordinate with planning already done by @planning
-
-**Example scenarios:**
-
-```markdown
-## Scenario 1: @building starting implementation
-
-Before writing code:
-
-1. ff-agents-current() → Shows @ff-research is active
-2. Read ff-research context → They've researched the API already
-3. Use their findings instead of researching again
-
-## Scenario 2: @reviewing starting validation
-
-Before reviewing:
-
-1. ff-agents-current() → Shows @ff-security completed audit
-2. Read ff-security context → They found 2 vulnerabilities
-3. Focus review on those areas, don't duplicate security work
-```
-
-### Step 2: Create Your Context File (IMMEDIATELY)
-
-**Every agent MUST create a context file at the start:**
-
-```
-ff-agents-update:
-  fileName: "{agent-name}-{UUID}.md"
-  content: |
-    ---
-    id: "{UUID}"
-    agent: "{agent-name}"
-    title: "{brief task title}"
-    description: "{detailed description}"
-    status: "in-progress"
-    started: "{ISO timestamp}"
-    parent: "{parent UUID or null}"
-    delegated_to: []
-    ---
-
-    ## Task Context
-
-    {What you're working on and why}
-
-    ## Related Agents
-
-    {List other agents working on related tasks}
-
-    ## Progress
-
-    - [x] Context created
-    - [ ] Analysis in progress
-    - [ ] Findings documented
-
-    ## Notes
-
-    {Any important observations or decisions}
-```
-
-**Required fields:**
-
-- `id` - Your unique UUID
-- `agent` - Your agent type (building, planning, ff-security, etc.)
-- `title` - Brief, descriptive title
-- `description` - What you're doing and why
-- `status` - in-progress, completed, delegated, or failed
-- `started` - ISO timestamp
-- `parent` - Parent agent UUID if delegated, otherwise null
-- `delegated_to` - Array of child agent UUIDs
-
-### Step 3: Monitor Other Agents (DURING Work)
-
-**Check on other agents periodically:**
-
-```
-# See all active agents
-ff-agents-current()
-
-# Read specific agent's context
-ff-agents-show(id: "{agent-uuid}")
-
-# Or read directly
-ff-agents-get:
-  fileName: "{agent-name}-{uuid}.md"
-```
-
-**When to monitor:**
-
-- Before making changes that might conflict with others
-- When waiting for delegated agents to complete
-- When troubleshooting issues that might involve other agents
-- Periodically during long-running tasks
-
-### Step 4: Update Your Progress (AS YOU WORK)
-
-**Keep your context file current:**
-
-```
-ff-agents-update:
-  fileName: "{agent-name}-{UUID}.md"
-  content: |
-    ---
-    id: "{UUID}"
-    agent: "{agent-name}"
-    title: "{title}"
-    description: "{description}"
-    status: "in-progress"
-    started: "{timestamp}"
-    parent: "{parent}"
-    delegated_to: [{child-uuid-1}, {child-uuid-2}]
-    ---
-
-    ## Task Context
-
-    {Updated context}
-
-    ## Progress
-
-    - [x] Context created
-    - [x] Analysis complete
-    - [in_progress] Writing findings
-    - [ ] Final review
-
-    ## Key Findings
-
-    {Important discoveries as you make them}
-```
-
-### Step 5: Mark Complete and Clean Up (AT THE END)
-
-**CRITICAL: Always clean up when done:**
-
-```
-# Option 1: Clear your specific context
-ff-agents-clear(id: "{your-uuid}")
-
-# Option 2: Clear all your session's agents
-ff-agents-clear(sessionID: "{session-id}")
-
-# Option 3: If you're the parent, clear all delegated agents too
-ff-agents-clear(agent: "{agent-type}")
-```
-
-**When to clean up:**
-
-- ✅ Task completed successfully
-- ✅ Task failed but documented why
-- ✅ Task cancelled
-- ✅ Delegated agents have finished and you've read their results
-
-**NEVER leave context files behind unless:**
-
-- The task is intentionally ongoing (rare)
-- You're explicitly asked to keep context for monitoring
-
-## Cross-Agent Awareness Patterns
-
-### Pattern 1: Building on Research
-
-```markdown
-@building implementing a feature:
-
-1. ff-agents-current() → Shows @ff-research active
-2. ff-agents-show(id: "research-uuid") → Read their findings
-3. Use research findings in implementation
-4. No need to duplicate research work
-```
-
-### Pattern 2: Coordinated Validation
-
-```markdown
-@reviewing performing validation:
-
-1. ff-agents-current() → Shows @ff-security and @ff-review completed
-2. Read both contexts to understand what they found
-3. Focus comprehensive review on gaps they might have missed
-4. Aggregate all findings into final report
-```
-
-### Pattern 3: Conflict Avoidance
-
-```markdown
-@building about to edit a file:
-
-1. ff-agents-current() → Shows another @building agent active
-2. Read their context → They're editing the same file
-3. Wait for them to finish OR coordinate changes
-4. Avoid merge conflicts and duplicate work
-```
-
-### Pattern 4: Delegation Chain Tracking
-
-```markdown
-@planning delegating to multiple agents:
-
-1. Create planning context with parent: null
-2. Delegate to @ff-research, @ff-security, @ff-acceptance
-3. Update planning context with delegated_to: [uuid1, uuid2, uuid3]
-4. Each child agent has parent: "planning-uuid"
-5. Monitor all children with ff-agents-current()
-6. When all complete, read all contexts and aggregate
-7. Clear all contexts when done
-```
-
-## Context File Structure Standards
-
-### Standard Template
-
-```markdown
----
-id: '550e8400-e29b-41d4-a716-446655440000'
-agent: 'building'
-title: 'Implement OAuth Authentication'
-description: 'Building OAuth flow for customer portal login'
-status: 'in-progress'
-started: '2026-02-02T14:30:00Z'
-parent: null
-delegated_to:
-  - '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
-  - '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
----
-
-## Task Context
-
-Implementing Google OAuth authentication for the customer portal.
-Requirements from issue #123:
-
-- Support Google OAuth 2.0
-- Store user data in Supabase
-- Handle token refresh
-
-## Related Work
-
-- @ff-research researched OAuth libraries (completed)
-- @ff-security performed threat model (in-progress)
-
-## Progress
-
-- [x] Context created
-- [x] Research findings reviewed
-- [in_progress] Implementing auth middleware
-- [ ] Testing OAuth flow
-- [ ] Documentation
-
-## Blockers
-
-None currently.
-
-## Notes
-
-Using NextAuth.js based on @ff-research recommendation.
-```
-
-### Status Values
-
-- `in-progress` - Currently working on this task
-- `completed` - Task finished successfully
-- `delegated` - Task split into sub-tasks assigned to other agents
-- `failed` - Task failed, documented why
-- `blocked` - Task blocked, documented reason
-
-## Tools Reference
-
-### ff-agents-current
-
-List all active agents with their status.
-
-**Use when:**
-
-- Starting work (check for conflicts)
-- Monitoring delegated agents
-- Troubleshooting issues
-
-**Returns:**
-
-```json
-{
-  "count": 3,
-  "agents": [
-    {
-      "id": "uuid-1",
-      "agent": "building",
-      "title": "Implement OAuth",
-      "status": "in-progress"
-    },
-    {
-      "id": "uuid-2",
-      "agent": "ff-research",
-      "title": "Research OAuth libraries",
-      "status": "completed",
-      "parent": "uuid-1"
-    }
-  ]
-}
-```
-
-### ff-agents-show
-
-Get detailed context for a specific agent by UUID.
-
-**Use when:**
-
-- You need to read another agent's full context
-- You want to build on their findings
-- You're aggregating results from delegated agents
-
-### ff-agents-get
-
-Read an agent context file by name.
-
-**Use when:**
-
-- You know the exact filename
-- You need to read and then update a file
-
-### ff-agents-update
-
-Create or update your agent context file.
-
-**Use when:**
-
-- Creating your context at start
-- Updating progress as you work
-- Adding delegated agents
-
-### ff-agents-clear
-
-Clean up agent context files.
-
-**Use when:**
-
-- Task completed
-- Task failed/cancelled
-- Cleaning up delegated agents
-
-**Options:**
-
-- `id` - Clear specific agent by UUID
-- `sessionID` - Clear all agents in a session
-- `agent` - Clear all agents of a specific type
-
-## Common Mistakes to Avoid
-
-### ❌ Mistake 1: Not Checking Existing Agents
-
-**Problem:** Start working without checking what others are doing
-**Impact:** Duplicate work, conflicts, wasted effort
-**Solution:** Always run `ff-agents-current()` first
-
-### ❌ Mistake 2: No Context File
-
-**Problem:** Work without creating a context file
-**Impact:** Others can't see what you're doing, can't coordinate
-**Solution:** Create context file IMMEDIATELY at start
-
-### ❌ Mistake 3: Stale Context
-
-**Problem:** Context file says "in-progress" but work is done
-**Impact:** Others think work is still happening, don't build on it
-**Solution:** Update status to "completed" when done
-
-### ❌ Mistake 4: Not Cleaning Up
-
-**Problem:** Leave context files after completion
-**Impact:** Clutter, confusion about what's active
-**Solution:** Always call `ff-agents-clear()` when done
-
-### ❌ Mistake 5: Not Reading Other Contexts
-
-**Problem:** Ignore what other agents have found
-**Impact:** Miss important findings, duplicate work
-**Solution:** Read contexts of related agents with `ff-agents-show()`
-
-### ❌ Mistake 6: Missing Parent Links
-
-**Problem:** Delegated agents don't set parent field
-**Impact:** Can't track delegation chains
-**Solution:** Always set `parent: "{delegator-uuid}"` when delegated
-
-## Integration with Other Skills
-
-### With ff-delegation
-
-- Use context tracking to monitor delegated agents
-- Update `delegated_to` field when delegating
-- Read child agent contexts to aggregate results
-- Clean up all contexts when delegation chain completes
-
-### With ff-todo-management
-
-- Add "Check existing agents" as first todo item
-- Add "Create context file" as second todo item
-- Add "Clean up context" as final todo item
-- Track progress in both todo list AND context file
-
-## Best Practices Summary
-
-### DO:
-
-✅ **Check existing agents before starting** - `ff-agents-current()`
-✅ **Create context file immediately** - At the very start
-✅ **Update progress regularly** - Keep context current
-✅ **Read other agents' contexts** - Build on their work
-✅ **Set parent when delegated** - Track delegation chains
-✅ **Track delegated agents** - Update `delegated_to` field
-✅ **Clean up when done** - `ff-agents-clear()`
-✅ **Monitor periodically** - Check on delegated agents
-
-### DON'T:
-
-❌ **Start without checking others** - Risk conflicts
-❌ **Work without context file** - Invisible to others
-❌ **Leave stale contexts** - Confuses others
-❌ **Ignore other agents** - Miss important findings
-❌ **Forget parent links** - Break delegation chains
-❌ **Skip cleanup** - Leave clutter behind
-
-## Example: Complete Context Tracking Workflow
-
-```markdown
-## @building implementing a feature
-
-### Step 1: Check Existing Agents
-
-ff-agents-current()
-→ Shows @ff-research completed, @planning completed
-
-### Step 2: Read Their Contexts
-
-ff-agents-show(id: "research-uuid") → Read research findings
-ff-agents-show(id: "planning-uuid") → Read implementation plan
-
-### Step 3: Create My Context
-
-ff-agents-update:
-fileName: "building-{my-uuid}.md"
-content: |
-
----
-
-id: "{my-uuid}"
-agent: "building"
-title: "Implement OAuth"
-description: "Building based on @ff-research findings and @planning plan"
-status: "in-progress"
-started: "2026-02-02T14:30:00Z"
-parent: null
-delegated_to: []
-
----
-
-    ## Context
-
-    Building OAuth based on:
-    - @ff-research: Use NextAuth.js
-    - @planning: 3-step implementation plan
-
-### Step 4: Delegate for Parallel Work
-
-Generate child UUIDs for @ff-security and @ff-review
-Task(ff-security): "Audit OAuth implementation"
-Task(ff-review): "Review code quality"
-
-Update my context:
-ff-agents-update:
-delegated_to: ["security-uuid", "review-uuid"]
-
-### Step 5: Monitor Delegated Agents
-
-ff-agents-current() → Check if security and review complete
-ff-agents-show(id: "security-uuid") → Read security findings
-ff-agents-show(id: "review-uuid") → Read review findings
-
-### Step 6: Complete and Clean Up
-
-ff-agents-clear(id: "{my-uuid}")
-ff-agents-clear(id: "{security-uuid}")
-ff-agents-clear(id: "{review-uuid}")
-```
-
-## Remember
-
-**Context tracking is not optional - it's essential for coordination.**
-
-Without it:
-
-- Agents work in isolation
-- Effort is duplicated
-- Conflicts arise
-- Files are orphaned
-- Progress is unclear
-
-With it:
-
-- Agents coordinate effectively
-- Work builds on work
-- Conflicts are avoided
-- Resources are managed
-- Progress is transparent
-
-**ALWAYS track your context. ALWAYS clean up when done.**