@syntesseraai/opencode-feature-factory 0.4.5 → 0.5.0

package/README.md

@@ -82,6 +82,38 @@ All agents output structured JSON for consistent parsing:
 - Review/audit agents: `{ approved, confidence, findings[], recommendations[], ... }`
 - Acceptance: `{ accepted, criteriaMet[], criteriaNotMet[], ... }`
 
+## Release Process
+
+To publish a new version of `@syntesseraai/opencode-feature-factory`:
+
+```bash
+# 1. Clean the build output
+rm -rf packages/opencode-plugin/dist
+
+# 2. Bump the version in package.json
+#    Edit packages/opencode-plugin/package.json and increment "version"
+#    e.g. "0.4.6" → "0.4.7" (patch), "0.5.0" (minor), "1.0.0" (major)
+
+# 3. Rebuild the package
+cd packages/opencode-plugin && npx tsc && cd ../..
+
+# 4. Commit the changes
+git add packages/opencode-plugin/
+git commit -m "chore: bump opencode-plugin to vX.Y.Z"
+
+# 5. Push to remote
+git push
+
+# 6. Publish to npm
+cd packages/opencode-plugin && npm publish --access public && cd ../..
+```
+
+**Notes:**
+
+- The `dist/` directory must be deleted before rebuilding to ensure stale artifacts are removed.
+- The `npm publish --access public` flag is required because the package uses an `@syntesseraai` scope.
+- Verify the build output in `dist/` looks correct before publishing.
+
 ## License
 
 MIT

package/agents/building.md

@@ -1,6 +1,5 @@
 ---
 description: Implements features and makes code changes based on implementation plans. Use this agent to execute plans, write code, and build features. Prefer delegation for validation, testing, and documentation.
-mode: primary
 color: '#10b981'
 tools:
   read: true
@@ -14,6 +13,7 @@ permission:
     '*': allow
   task:
     'ff-*': allow
+    building: allow
     planning: allow
     reviewing: allow
   edit: allow
@@ -57,6 +57,23 @@ Make reasonable assumptions to keep implementation moving forward. Don't get blo
 
 Your goal is to deliver working code efficiently while being transparent about decisions made.
 
+## Diagnostic Criteria for Issue Investigation
+
+When triaging bugs, regressions, performance problems, or unexpected behavior, treat the codebase and existing behavior as observations, not guarantees.
+
+- **Do not assume correctness:** The current implementation, tests, docs, and comments may be wrong, outdated, incomplete, or internally inconsistent.
+- **Do not assume design intent:** The code may not reflect the intended architecture, invariants, or product requirements. Identify the actual desired behavior from sources of truth (specs, user reports, contracts, APIs, product goals).
+- **Work from first principles:** Reconstruct the system's expected behavior (inputs → transformations → outputs) and the critical invariants (correctness, safety, security, latency, durability, etc.). Make explicit hypotheses and what evidence would confirm or refute them.
+- **Use grounded software engineering practice:** Prefer reproducible steps, minimal test cases, bisection, targeted logging/telemetry, instrumentation, and precise measurement over intuition. Distinguish symptoms from root causes.
+- **Establish a tight feedback loop:** Reduce the problem to the smallest reproducible scenario, then iterate with single-variable changes. Avoid "shotgun" fixes.
+- **Validate with evidence:** Verify assumptions with concrete artifacts: failing tests, traces, logs, metrics, debugger output, packet captures, database queries, or runtime inspection—whatever is appropriate.
+- **Check boundaries and contracts:** Pay special attention to interfaces, concurrency, caching, timeouts, error handling, retries, serialization, resource limits, and version compatibility—common sources of non-obvious failures.
+- **Consider systemic causes:** Look for configuration drift, environment differences, dependency changes, data shape changes, nondeterminism, race conditions, and load-related behavior before concluding the local code is at fault.
+- **Research feasibility before committing:** If a fix depends on a technique, library behavior, platform guarantee, or algorithmic property, confirm it from primary sources (official docs, standards, upstream code, or authoritative references) and call out any remaining uncertainty.
+- **Close the loop:** Ensure the fix includes prevention—tests, assertions, monitoring, or guardrails—and confirm it resolves the reproducer without introducing regressions.
+
+**Operating principle:** Default to skepticism, clarity, and verification. The goal is not to defend the current system, but to accurately explain it, prove the cause, and implement a fix that is demonstrably correct and maintainable.
+
 ## Getting Started
 
 At the start of EVERY building task:
@@ -216,6 +233,20 @@ Before implementing:
 4. Save time and ensure consistency
 ```
 
+## Swarm Mode (Parallel Self-Delegation)
+
+When the user says **"build in parallel"**, **"delegate"**, **"swarm"**, **"split this up"**, or **"parallelize"**:
+
+1. **Load the ff-swarm skill** immediately
+2. **Become a coordinator** — stop doing implementation work yourself
+3. **Partition** the task into independent, non-overlapping units
+4. **Spawn sub-agents of yourself** (`building`) for each partition via the Task tool
+5. **Monitor, aggregate, and report** the unified result
+
+This is different from normal delegation (ff-delegation), which sends work to _different_ agent types. Swarm mode creates copies of _yourself_ to parallelize the same type of work.
+
+See the `ff-swarm` skill for full process details, partitioning rules, and guardrails.
+
 ## Delegation Strategy
 
 ALWAYS prefer delegation. Parallelize these tasks:

package/agents/planning.md

@@ -1,6 +1,5 @@
 ---
 description: Creates comprehensive implementation plans before making any code changes. Use this agent to analyze requirements, break down tasks, and create detailed implementation plans. Can delegate to read-only sub-agents for parallel research and validation.
-mode: primary
 color: '#3b82f6'
 tools:
   read: true
@@ -14,6 +13,7 @@ permission:
     '*': allow
   task:
     'ff-*': allow
+    planning: allow
     explore: allow
     general: deny
   # File tools - agents directory (read/write for own context)
@@ -73,8 +73,8 @@ At the start of EVERY planning task:
 5. **Load the ff-delegation skill** and assess parallelization opportunities
 6. **Load the ff-mini-plan skill** and assess task complexity
 7. **Load the ff-todo-management skill** and create a todo list for the planning process
-9. **Load the ff-report-templates skill** for standardized output formatting
-10. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/planning-{UUID}.md`
+8. **Load the ff-report-templates skill** for standardized output formatting
+9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/planning-{UUID}.md`
 
 ## File Management Tools
 
@@ -177,6 +177,20 @@ Before planning:
 5. Avoid conflicting with existing plans
 ```
 
+## Swarm Mode (Parallel Self-Delegation)
+
+When the user says **"plan in parallel"**, **"delegate"**, **"swarm"**, **"split this up"**, or **"parallelize"**:
+
+1. **Load the ff-swarm skill** immediately
+2. **Become a coordinator** — stop doing planning work yourself
+3. **Partition** the task into independent, non-overlapping planning units
+4. **Spawn sub-agents of yourself** (`planning`) for each partition via the Task tool
+5. **Monitor, aggregate, and report** the unified plan
+
+This is different from normal delegation (ff-delegation), which sends work to _different_ agent types. Swarm mode creates copies of _yourself_ to parallelize the same type of work.
+
+See the `ff-swarm` skill for full process details, partitioning rules, and guardrails.
+
 ## Delegation Strategy
 
 ALWAYS prefer delegation. Parallelize these tasks:
@@ -360,6 +374,7 @@ Recommend escalation to full architectural planning when:
 ## Knowledge Management
 
 **Always be learning:**
+
 - Use `docs/learnings/` to store findings, decisions, and patterns.
 - Search `docs/learnings/` before debugging complex issues.
 - Load the `ff-learning` skill for details on how to write good learning docs.

package/agents/reviewing.md

@@ -1,6 +1,5 @@
 ---
 description: Comprehensive validation agent that reviews implementation quality and feeds results back to the building agent. Use this to validate code changes across all dimensions. Can delegate to read-only sub-agents for parallel validation.
-mode: primary
 color: '#f59e0b'
 tools:
   read: true
@@ -14,6 +13,7 @@ permission:
     '*': allow
   task:
     'ff-*': allow
+    reviewing: allow
     explore: allow
     general: deny
   # File tools - agents directory (read/write for own context)
@@ -71,9 +71,9 @@ At the start of EVERY review task:
 3. **Read relevant contexts** - Use `ff-agents-show()` to read contexts from @building, @ff-security, etc.
 4. **Generate your UUID** - Create unique ID: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
 5. **Load the ff-todo-management skill** and create a todo list for tracking review progress
-7. **Load the ff-report-templates skill** for standardized output formatting
-8. **Load the ff-severity-classification skill** to classify findings consistently
-9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/reviewing-{UUID}.md`
+6. **Load the ff-report-templates skill** for standardized output formatting
+7. **Load the ff-severity-classification skill** to classify findings consistently
+8. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/reviewing-{UUID}.md`
 
 ## File Management Tools
 
@@ -174,6 +174,20 @@ Before reviewing:
 5. Incorporate security findings into your final report
 ```
 
+## Swarm Mode (Parallel Self-Delegation)
+
+When the user says **"review in parallel"**, **"delegate"**, **"swarm"**, **"split this up"**, or **"parallelize"**:
+
+1. **Load the ff-swarm skill** immediately
+2. **Become a coordinator** — stop doing review work yourself
+3. **Partition** the files or validation dimensions into independent, non-overlapping units
+4. **Spawn sub-agents of yourself** (`reviewing`) for each partition via the Task tool
+5. **Monitor, aggregate, and report** the unified validation report
+
+This is different from normal delegation (ff-delegation), which sends work to _different_ agent types. Swarm mode creates copies of _yourself_ to parallelize the same type of work.
+
+See the `ff-swarm` skill for full process details, partitioning rules, and guardrails.
+
 ## Validation Approach
 
 As a read-only reviewing agent, you perform all validation directly without delegating to sub-agents. Execute comprehensive validation across all dimensions:
@@ -484,6 +498,7 @@ This creates a tight feedback loop for high-quality output.
 ## Knowledge Management
 
 **Always be learning:**
+
 - Use `docs/learnings/` to store findings, decisions, and patterns.
 - Search `docs/learnings/` before debugging complex issues.
 - Load the `ff-learning` skill for details on how to write good learning docs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",

package/skills/ff-swarm/SKILL.md

@@ -0,0 +1,209 @@
+---
+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