@syntesseraai/opencode-feature-factory 0.6.7 → 0.6.9

package/skills/ff-delegation/SKILL.md

@@ -1,457 +0,0 @@
----
-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.
-
-**⚠️ CRITICAL: Always use with ff-context-tracking skill**
-
-The ff-context-tracking skill provides the foundation for cross-agent visibility and coordination. You MUST load it before delegating to ensure proper context management.
-
-## When to Use
-
-You MUST delegate when:
-
-- **Multiple independent tasks** can be worked on simultaneously
-- **Specialized expertise** is needed (security, architecture, ff-research)
-- **Validation** is required from multiple perspectives
-- **Information gathering** can happen in parallel with planning
-
-## Prerequisites
-
-Before using this skill:
-
-1. **Load ff-context-tracking skill** - Essential for coordination
-2. **Check existing agents** - Run `ff-agents-current()` to see what's happening
-3. **Read relevant contexts** - Use `ff-agents-show()` to build on others' work
-
-## 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`
-
-### Cross-Agent Visibility
-
-Thanks to ff-context-tracking, all agents can:
-
-- See what other agents are doing (`ff-agents-current()`)
-- Read each other's contexts (`ff-agents-show()`)
-- Build on each other's findings
-- Avoid conflicts and duplication
-
-### 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: Check Existing Agents (CRITICAL)
-
-**ALWAYS check what other agents are doing before delegating:**
-
-```
-ff-agents-current()
-```
-
-**Why this matters:**
-
-- Avoid delegating research if @ff-research is already active
-- Don't duplicate security audits if @ff-security is running
-- Build on existing work rather than starting from scratch
-- Prevent agent conflicts and resource waste
-
-**Read relevant contexts:**
-
-```
-ff-agents-show(id: "{existing-agent-uuid}")
-```
-
-### Step 2: Generate Your UUID
-
-Create a unique identifier for this agent instance:
-
-```
-Generate UUID: $MY_UUID = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
-```
-
-### Step 3: Document Your Context
-
-Use `ff-agents-update` tool to create your agent context file:
-
-```
-ff-agents-update:
-  fileName: "{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.
-```
-
-**Why use ff-agents-update?** This specialized tool provides:
-
-- Security (prevents directory traversal attacks)
-- Validation (ensures proper file naming)
-- Organization (enforces .md extension)
-- Safety (restricted to .feature-factory/agents/ directory)
-
-### Step 4: Identify Parallel Opportunities
-
-Ask: "What work can happen simultaneously?"
-
-**Consider what you learned from checking existing agents:**
-
-- Don't delegate research if @ff-research already has findings
-- Don't delegate security audit if @ff-security is already running
-- Delegate to fill gaps in existing work
-- Delegate for independent validation dimensions
-
-Common parallel tasks:
-
-- **ff-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 5: 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       | @ff-research         | @general | Async        |
-| Exploration    | @explore             | @general | Parallel     |
-| Implementation | @general             | N/A      | Sequential   |
-
-### Step 6: 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(ff-research): "Research: Find best OAuth libraries for Node.js. Write context to .feature-factory/agents/ff-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"
-```
-
-**Important:** Each delegated agent will:
-
-1. Create their own context file (via ff-context-tracking)
-2. Set `parent: "{$MY_UUID}"` to link back to you
-3. Be visible via `ff-agents-current()`
-4. Clean up their context when done
-
-Update your context with delegated agents using `ff-agents-get` to read your file, then `ff-agents-update` to save the updated version:
-
-1. First, read your current context:
-
-   ```
-   ff-agents-get:
-     fileName: "{agent}-{$MY_UUID}.md"
-   ```
-
-2. Then update with delegated agents:
-
-   ```
-   ff-agents-update:
-     fileName: "{agent}-{$MY_UUID}.md"
-     content: |
-       [previous content with updated delegated_to section]
-
-       delegated_to:
-         - "{$CHILD_1}"
-         - "{$CHILD_2}"
-         - "{$CHILD_3}"
-   ```
-
-### Step 7: 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 8: 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
-```
-
-**Thanks to ff-context-tracking, you can:**
-
-- See all delegated agent statuses at once with `ff-agents-current()`
-- Read detailed findings from each agent's context
-- Build on their work rather than starting from scratch
-- Coordinate next steps based on their results
-
-### Step 9: 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 (@ff-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
-```
-
-**Build on their findings:**
-
-- Use @ff-research's library recommendation in your plan
-- Address @ff-security's vulnerabilities before implementation
-- Incorporate @ff-acceptance's criteria validation into requirements
-
-### Step 10: Clean Up (CRITICAL)
-
-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: "ff-research")
-```
-
-**Cleanup Scope:**
-
-- **Agent context files** (`.feature-factory/agents/`): Clean up via `ff-agents-clear()` - these are temporary coordination files managed by ff-context-tracking
-- **Plan files** (`.feature-factory/plans/`): @building agent asks user if plan should be deleted after implementation is complete
-- **Review files** (`.feature-factory/reviews/`): Do NOT delete - these are idempotent validation records that serve as audit trail
-- **Stale plan check**: @planning agent checks for existing plan files before creating new ones
-
-**Why cleanup matters:**
-
-- Prevents clutter in `.feature-factory/agents/`
-- Avoids confusion about what's currently active
-- Frees up resources
-- Follows ff-context-tracking best practices
-
-## Example: Planning with Parallel Research
-
-**Scenario:** Implementing OAuth authentication
-
-```markdown
-## My Workflow
-
-1. **Load ff-context-tracking skill**
-   - Essential for coordination and cross-agent visibility
-
-2. **Check existing agents**
-   - ff-agents-current() → See what's already happening
-   - Avoid duplicating existing research or audits
-
-3. **Read relevant contexts**
-   - ff-agents-show() → Build on any existing work
-   - Check if OAuth was already researched
-
-4. **Generate my UUID**
-   - $MY_UUID = "550e8400-e29b-41d4-a716-446655440000"
-
-5. **Document my context**
-   - Write to .feature-factory/agents/planning-550e8400-e29b-41d4-a716-446655440000.md
-   - Include context about what needs to be planned
-
-6. **Identify parallel tasks**
-   - Security audit (can run in parallel)
-   - Research OAuth libraries (can run in parallel)
-   - Validate acceptance criteria (can run in parallel)
-
-7. **Generate child UUIDs**
-   - $SECURITY_UUID = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
-   - $RESEARCH_UUID = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
-   - $ACCEPTANCE_UUID = "6ba7b812-9dad-11d1-80b4-00c04fd430c8"
-
-8. **Delegate in parallel**
-   - Task(ff-security): "Audit OAuth..." (use $SECURITY_UUID)
-   - Task(ff-research): "Research OAuth..." (use $RESEARCH_UUID)
-   - Task(ff-acceptance): "Validate..." (use $ACCEPTANCE_UUID)
-
-9. **Update my context**
-   - Add delegated_to: [$SECURITY_UUID, $RESEARCH_UUID, $ACCEPTANCE_UUID]
-
-10. **Monitor progress**
-    - ff-agents-current() → Check status of all delegated agents
-
-11. **Read results**
-    - ff-agents-show(id: $SECURITY_UUID) → Get security findings
-    - ff-agents-show(id: $RESEARCH_UUID) → Get research findings
-    - ff-agents-show(id: $ACCEPTANCE_UUID) → Get validation results
-
-12. **Create informed plan**
-    - Use all findings to create comprehensive plan
-    - Incorporate security recommendations from @ff-security
-    - Use library recommendations from @ff-research
-    - Ensure acceptance criteria from @ff-acceptance are met
-
-13. **Clean up**
-    - ff-agents-clear() → Remove all agent contexts
-    - Clean up your own context and all delegated agents
-```
-
-## Best Practices
-
-1. **ALWAYS use ff-context-tracking first** - Check existing agents before delegating
-2. **Always document context first** - Other agents need to know what you're working on
-3. **Generate UUIDs immediately** - Every agent instance needs a unique ID
-4. **Prefer parallel over sequential** - Unless tasks have dependencies
-5. **Use specific instructions** - Delegated agents need clear, actionable tasks
-6. **Monitor with ff-agents-current** - Check status before proceeding
-7. **Read full context** - Don't just check status, read the actual findings
-8. **Clean up immediately** - Don't leave context files after completion
-9. **Track parent-child relationships** - Use parent and delegated_to fields
-
-## Common Mistakes to Avoid
-
-- ❌ **Not checking existing agents** - Always run `ff-agents-current()` first
-- ❌ **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-context-tracking** - ESSENTIAL: For cross-agent visibility and coordination
-- **ff-mini-plan** - For breaking down tasks before delegation
-- **ff-todo-management** - For tracking parallel tasks
-- **ff-report-templates** - For formatting aggregated results
-
-### Why ff-context-tracking is Essential
-
-The ff-context-tracking skill provides the foundation that makes delegation work:
-
-- **Visibility**: See what all agents are doing via `ff-agents-current()`
-- **Coordination**: Read other agents' contexts via `ff-agents-show()`
-- **Accountability**: Every agent documents their work in context files
-- **Cleanup**: Properly remove context files when done via `ff-agents-clear()`
-
-**Without ff-context-tracking:**
-
-- Agents work in isolation
-- Duplication occurs
-- Conflicts arise
-- Context files are orphaned
-
-**With ff-context-tracking:**
-
-- Agents coordinate effectively
-- Work builds on work
-- Conflicts are avoided
-- Resources are managed
-
-**Always load ff-context-tracking before using ff-delegation.**
-
-## 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. **@ff-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.

package/skills/ff-swarm/SKILL.md

@@ -1,209 +0,0 @@
----
-name: ff-swarm
-description: Enables agents to partition tasks and spawn sub-agents of themselves for parallel execution. The originating agent becomes the coordinator, monitoring progress and aggregating results.
-license: MIT
-compatibility: opencode
-metadata:
-  audience: agents
-  category: orchestration
----
-
-# Swarm: Self-Partitioned Parallel Execution
-
-This skill enables any agent to split a task into partitions and spawn copies of itself as sub-agents to work in parallel. The original agent becomes the **coordinator** — it does not do implementation work itself, only orchestrates.
-
-## When to Activate
-
-Activate this skill when the user explicitly requests parallel execution:
-
-- **"build in parallel"**
-- **"delegate"** (when referring to splitting the current task, not delegating to a different agent type)
-- **"swarm this"**
-- **"split this up"**
-- **"parallelize"**
-
-**Do NOT activate** for normal delegation to different agent types (e.g., delegating review to @reviewing). Use the `ff-delegation` skill for that instead.
-
-## How It Differs from ff-delegation
-
-| Aspect         | ff-delegation                        | ff-swarm                               |
-| -------------- | ------------------------------------ | -------------------------------------- |
-| Sub-agent type | Different specialized agents         | Copies of yourself (same agent type)   |
-| Purpose        | Cross-functional work (review, test) | Partitioned parallel work on same task |
-| Coordinator    | You continue your own work too       | You STOP working, only coordinate      |
-| Use case       | "Review this" / "Run security audit" | "Build these 3 features in parallel"   |
-
-## Coordinator Role
-
-Once you activate swarm mode, you become a **pure coordinator**. Your responsibilities change:
-
-1. **Partition** — Break the task into independent, non-overlapping units of work
-2. **Spawn** — Create sub-agents of your own type for each partition
-3. **Monitor** — Track progress of all sub-agents
-4. **Aggregate** — Collect and combine results when sub-agents complete
-5. **Report** — Present the unified result to the user
-
-**You do NOT do implementation work yourself.** If there are N partitions, spawn N sub-agents.
-
-## Partitioning Rules
-
-Good partitions are:
-
-- **Independent** — No partition depends on another's output
-- **Non-overlapping** — No two partitions modify the same files
-- **Roughly equal** — Balance work across partitions
-- **Self-contained** — Each partition has all the context it needs
-
-If the task cannot be cleanly partitioned (e.g., sequential dependencies, shared file modifications), tell the user and either:
-
-- Execute sequentially yourself (no swarm)
-- Partition only the independent parts and handle dependent parts yourself after sub-agents complete
-
-## Process
-
-### Step 1: Analyze and Partition
-
-```markdown
-I'll split this into N parallel tasks:
-
-1. **[Partition A]** — [scope and files]
-2. **[Partition B]** — [scope and files]
-3. **[Partition C]** — [scope and files]
-
-These are independent — no shared files or dependencies between them.
-```
-
-Verify no file conflicts exist between partitions. If two partitions need the same file, restructure the partitions.
-
-### Step 2: Generate UUIDs
-
-Generate a coordinator UUID for yourself and a child UUID for each sub-agent:
-
-- Coordinator: `{your-agent-type}-{coordinator-uuid}` (your context file)
-- Sub-agent 1: `{your-agent-type}-{child-uuid-1}`
-- Sub-agent 2: `{your-agent-type}-{child-uuid-2}`
-- Sub-agent N: `{your-agent-type}-{child-uuid-N}`
-
-### Step 3: Document Coordinator Context
-
-Write your context file with the partition plan and child UUIDs:
-
-```markdown
-# Coordinator: {agent-type}
-
-**Mode:** Swarm coordinator
-**Task:** [overall task description]
-**Partitions:** N
-**Sub-agents:** [child-uuid-1, child-uuid-2, ...]
-
-## Partition Plan
-
-1. [Partition A] → child-uuid-1
-2. [Partition B] → child-uuid-2
-3. [Partition C] → child-uuid-3
-
-## Status
-
-- [ ] child-uuid-1: Pending
-- [ ] child-uuid-2: Pending
-- [ ] child-uuid-3: Pending
-```
-
-### Step 4: Spawn Sub-Agents
-
-Use the Task tool to spawn each sub-agent **of your own type**. Each sub-agent must receive:
-
-1. **Full context** of its specific partition (not the whole task)
-2. **File boundaries** — which files it owns and must not go beyond
-3. **Completion criteria** — what "done" looks like for its partition
-4. **Context tracking instructions** — write results to its agent context file
-
-```
-Task({your-agent-type}): "
-You are a swarm sub-agent handling partition N of a parallel task.
-
-## Your Partition
-[Detailed description of this partition's scope]
-
-## Files You Own
-- file1.ts
-- file2.ts
-
-## Files You Must NOT Touch
-- [files owned by other partitions]
-
-## Completion Criteria
-- [What done looks like]
-
-## Context
-Write your progress and results to .feature-factory/agents/{your-agent-type}-{child-uuid}.md
-"
-```
-
-**Spawn all sub-agents in a single message** so they run concurrently.
-
-### Step 5: Monitor Progress
-
-After spawning, periodically check on sub-agents:
-
-```
-ff-agents-current() → See which sub-agents are still active
-ff-agents-show(id: "child-uuid") → Read completed results
-```
-
-### Step 6: Aggregate Results
-
-Once all sub-agents complete:
-
-1. Read each sub-agent's context file for results
-2. Check for any conflicts or issues
-3. Combine results into a unified summary
-4. Run any cross-partition validation (e.g., type checking, tests)
-
-### Step 7: Clean Up and Report
-
-1. Clean up all sub-agent context files
-2. Clean up your own coordinator context file
-3. Present the unified result to the user
-
-## Example: Building Agent Swarm
-
-User says: "Build the user auth, payment integration, and notification system in parallel"
-
-```markdown
-## Partition Plan
-
-1. **User Auth** → building-aaa111
-   - Files: src/auth/\*.ts, src/middleware/auth.ts
-   - Scope: Login, registration, JWT handling
-
-2. **Payment Integration** → building-bbb222
-   - Files: src/payments/\*.ts, src/api/billing.ts
-   - Scope: Stripe integration, subscription management
-
-3. **Notification System** → building-ccc333
-   - Files: src/notifications/\*.ts, src/api/notify.ts
-   - Scope: Email, push, webhook notifications
-```
-
-Then spawn 3 `building` sub-agents, one for each partition.
-
-## Example: Planning Agent Swarm
-
-User says: "Plan out the API redesign, database migration, and frontend overhaul in parallel"
-
-Spawn 3 `planning` sub-agents, each creating their own plan for their partition.
-
-## Example: Reviewing Agent Swarm
-
-User says: "Review these 12 changed files in parallel"
-
-Partition files into groups and spawn `reviewing` sub-agents, each reviewing their subset.
-
-## Guardrails
-
-- **Maximum sub-agents:** Cap at 5 concurrent sub-agents to avoid overwhelming the system
-- **File ownership is strict:** Sub-agents must not modify files outside their partition
-- **Fail fast:** If a sub-agent fails, report it immediately rather than waiting for all to complete
-- **No nested swarms:** Sub-agents must NOT activate ff-swarm themselves (one level of fan-out only)
-- **Sequential fallback:** If partitioning isn't possible, say so and execute normally