@syntesseraai/opencode-feature-factory 0.4.6 → 0.5.1

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
@@ -233,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.6",
+  "version": "0.5.1",
   "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-learning/SKILL.md

@@ -1,25 +1,36 @@
 # Feature Factory Learning Protocol
 
-This skill enables agents to continuously document and retrieve knowledge across the lifecycle of a task. It replaces the legacy "local-recall" MCP daemon with a lightweight, transparent Markdown-based system that lives directly in the repository's `docs/learnings/` folder.
+This skill enables agents to continuously document, organize, and retrieve knowledge across the lifecycle of a task using a strict hierarchical index structure. It ensures that knowledge is discoverable, context-rich, and properly categorized to aid LLM reasoning.
 
-## Core Philosophy
+## Core Philosophy & Hierarchy
 
-1. **Continuous Documentation:** Write down important facts, solutions, architectural decisions, and troubleshooting steps as soon as you verify them.
-2. **Transparent Storage:** Learnings are stored as plain Markdown files in `docs/learnings/` so they are reviewable, searchable, and committable.
-3. **Proactive Retrieval:** Before starting complex tasks or debugging, search the `docs/` and `docs/learnings/` directories to leverage past experience.
+1. **High Priority Context (`AGENTS.md`)**: Contains mandatory, "must-have" information that applies to every session. This is the root of all agent behavioral rules.
+2. **Discoverable Knowledge (`docs/INDEX.md`)**: The root index for all discoverable project information. Agents MUST consult this index when assessing user input or starting a new task.
+3. **Hierarchical Indexing**:
+   - `docs/INDEX.md` points to subfolder `INDEX.md` files (e.g., `docs/architecture/INDEX.md`, `docs/learnings/INDEX.md`).
+   - Every link in an `INDEX.md` file MUST include a **verbose, detailed description** of the target file or subfolder's purpose. This description is specifically designed to aid LLM reasoning when an agent is deciding which path to follow.
+   - Each subfolder's `INDEX.md` references the files at its own level and any nested subfolder `INDEX.md` files, alongside their descriptive purposes.
+4. **Continuous Documentation**: Write down important facts, solutions, architectural decisions, and progress as soon as verified. Always link new documents in the relevant `INDEX.md`.
 
 ## How to Use This Skill
 
-### 1. Documenting New Knowledge (Writing)
+### 1. Retrieving Knowledge (Reading & Discovery)
 
-Whenever you discover a non-obvious solution, establish a new convention, or resolve a complex bug, create a learning document.
+Before diving into implementation, debugging, or when assessing user input:
 
-**Tool to use:** `write` tool to `docs/learnings/{topic-slug}.md`
+- **Start at `docs/INDEX.md`**: Read the root index to understand the available knowledge domains.
+- **Navigate the Tree**: Follow the descriptive links to subfolder `INDEX.md` files to find specific guidelines, architecture rules, or past learnings.
+- **Use the right tools**: Use the `read` tool to traverse the `INDEX.md` files.
 
-**Naming Convention:**
-Use descriptive, kebab-case filenames: `docs/learnings/auth-token-refresh-flow.md`, `docs/learnings/docker-build-caching.md`.
+### 2. Documenting New Knowledge (Writing)
 
-**Template:**
+Whenever you discover a non-obvious solution, establish a new convention, resolve a complex bug, or need to document progress:
+
+1. **Create the Document**: Use the `write` tool to create a detailed markdown file in the appropriate subfolder (e.g., `docs/learnings/auth-token-refresh-flow.md`).
+2. **Update the Index**: You MUST update the `INDEX.md` file in that same folder. Add a link to your new file along with a verbose description of what the file contains and when another agent should read it.
+3. **Create Missing Indexes**: If a folder does not have an `INDEX.md` file, you MUST create it and link it back to the parent `INDEX.md` with a detailed reasoning description.
+
+**Template for new learning documents:**
 
 ```markdown
 # [Topic Title]
@@ -37,32 +48,18 @@ Use descriptive, kebab-case filenames: `docs/learnings/auth-token-refresh-flow.m
 
 ## Why this matters
 
-[Explain why this approach was chosen or why the bug occurred.]
+[Explain why this approach was chosen or why the bug occurred. Provide enough context to guide future agents.]
 ```
 
-### 2. Retrieving Past Knowledge (Reading)
-
-Before diving into debugging or implementing features, scan the `docs/` and `docs/learnings/` directories for relevant context.
-
-**Tools to use:**
-
-- `glob` tool with pattern `docs/learnings/*.md` to see all stored learnings.
-- `grep` tool to search inside `docs/` and `docs/learnings/` for specific keywords (e.g., error messages, library names).
-- `read` tool to pull the full context of relevant markdown files.
-
-### 3. Updating Existing Knowledge (Refining)
-
-If you find an existing learning document that is outdated or incomplete based on new work, use the `edit` tool to update it. Knowledge should evolve with the codebase.
-
-## When to Document a Learning
+### 3. Maintaining the Index Tree
 
-- **Architectural Decisions:** Why a specific library, pattern, or approach was chosen over alternatives.
-- **Environment Quirks:** Specific workarounds needed for local dev, testing, or deployment.
-- **Complex Debugging:** A root cause analysis of a tricky bug and how it was fixed.
-- **Undocumented Behaviors:** Workarounds for third-party API quirks or internal system edge cases.
+- **Verbose Descriptions**: When adding an entry to an `INDEX.md`, do not just list the filename. Explain _why_ the file exists, _what_ specific problems it solves, and _when_ an agent should consult it.
+  _Example:_ `* [auth-flow.md](./auth-flow.md) - Details the OAuth2 token refresh cycle, including how to handle race conditions when multiple requests hit an expired token. Consult this when modifying any API client or authentication middleware.`
+- **Refinement**: If an existing learning document or its index description is outdated, use the `edit` tool to update it.
 
 ## Checklist for Agents
 
-- [ ] Have I encountered a novel problem or established a new pattern? -> **Document it.**
-- [ ] Am I stuck on an error or unclear on a convention? -> **Search `docs/learnings/`.**
-- [ ] Is an existing learning document inaccurate? -> **Update it.**
+- [ ] Am I assessing user input or starting a task? -> **Read `docs/INDEX.md` to discover context.**
+- [ ] Have I encountered a novel problem, architectural decision, or established a new pattern? -> **Document it in a new file.**
+- [ ] Did I create a new document in `docs/`? -> **Update the local `INDEX.md` with a verbose description.**
+- [ ] Is a folder missing an `INDEX.md`? -> **Create it and link it to the parent `INDEX.md`.**

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