@syntesseraai/opencode-feature-factory 0.4.0 → 0.4.1

package/agents/building.md

@@ -68,9 +68,27 @@ At the start of EVERY building task:
 5. **Load the ff-delegation skill** and assess parallelization opportunities
 6. **Load the ff-mini-plan skill** and create an execution plan
 7. **Load the ff-todo-management skill** and create a todo list for tracking progress
-9. **Load the ff-severity-classification skill** to assess risks of changes
-10. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/building-{UUID}.md`
-11. **Check for existing plans** - Use `ff-plans-list` and `ff-plans-get` to find implementation plans
+8. **Load the ff-severity-classification skill** to assess risks of changes
+9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/building-{UUID}.md`
+10. **Check for existing plans** - Use `ff-plans-list` and `ff-plans-get` to find implementation plans
+
+## Git Worktrees (Mandatory)
+
+To prevent conflicts and ensure a clean state, you MUST use git worktrees for your implementation:
+
+1. **Create Worktree:** Before starting code modifications, create a dedicated worktree outside the main directory:
+   ```bash
+   git worktree add ../ff-build-{UUID} -b feature/ff-build-{UUID}
+   ```
+2. **Use the Worktree:**
+   - When using the `bash` tool, always set the `workdir` parameter to the absolute path of your worktree.
+   - When using `edit`, `write`, or `read` tools, ensure the `filePath` points to the files inside your worktree (e.g., replace the base project path with the path to your worktree).
+3. **Commit & Push:** Commit your changes and push the branch from within the worktree.
+4. **Cleanup:** After your work is pushed, remove the worktree:
+   ```bash
+   git worktree remove ../ff-build-{UUID} --force
+   git branch -D feature/ff-build-{UUID}
+   ```
 
 ## File Management Tools
 
@@ -450,3 +468,11 @@ When @reviewing agent returns findings:
 ```
 
 Create todos for each critical/high item, fix them, then re-invoke @reviewing if needed.
+
+## 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/ff-acceptance.md

@@ -276,3 +276,10 @@ Use ff-severity-classification skill standards:
 11. Mark all todos complete before finishing
 
 Remember: Your role is to be the "gatekeeper" ensuring requirements are fully and correctly implemented before proceeding.
+
+## 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/ff-research.md

@@ -421,3 +421,10 @@ Structure research findings using ff-report-templates:
 - **Stay current** - Technology changes rapidly, verify dates
 
 Remember: Your research enables other agents to make informed implementation decisions. Be thorough, current, and precise.
+
+## 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/ff-review.md

@@ -279,3 +279,10 @@ Use ff-severity-classification skill standards:
 10. **CRITICAL: Clean up** - `ff-agents-clear()` to remove your context file
 11. Mark all todos complete before finishing
 12. Recommend delegating to other agents if specialized issues found
+
+## 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/ff-security.md

@@ -313,3 +313,10 @@ Use ff-severity-classification skill standards with security-specific definition
 10. **CRITICAL: Clean up** - `ff-agents-clear()` to remove your context file
 11. Mark all todos complete before finishing
 12. Recommend delegating to other agents if additional issues found
+
+## 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/ff-validate.md

@@ -307,3 +307,10 @@ When multiple agents report findings:
 - **Provide actionable feedback** - Every issue should have a clear fix
 - **Include metrics** - Quantify the validation results where possible
 - **Consider context** - Weight findings based on the scope of changes
+
+## 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/ff-well-architected.md

@@ -275,3 +275,10 @@ Use ff-severity-classification skill standards:
 12. Invoke other agents if specialized issues found
 
 Focus on providing actionable, specific recommendations that improve the overall architecture quality across all six pillars.
+
+## 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/planning.md

@@ -356,3 +356,10 @@ Recommend escalation to full architectural planning when:
 - **Consider edge cases** - Plan for error scenarios
 - **Include validation** - Specify how to verify the implementation
 - **Escalate appropriately** - Don't try to fit complex work into simple plans
+
+## 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

@@ -480,3 +480,10 @@ Typical workflow:
 8. Repeat until clean or only low-priority items remain
 
 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.0",
+  "version": "0.4.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

@@ -0,0 +1,68 @@
+# 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.
+
+## Core Philosophy
+
+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.
+
+## How to Use This Skill
+
+### 1. Documenting New Knowledge (Writing)
+
+Whenever you discover a non-obvious solution, establish a new convention, or resolve a complex bug, create a learning document.
+
+**Tool to use:** `write` tool to `docs/learnings/{topic-slug}.md`
+
+**Naming Convention:**
+Use descriptive, kebab-case filenames: `docs/learnings/auth-token-refresh-flow.md`, `docs/learnings/docker-build-caching.md`.
+
+**Template:**
+
+```markdown
+# [Topic Title]
+
+**Date:** [Current Date]
+**Tags:** [comma, separated, tags]
+
+## Context / Problem
+
+[Briefly describe what you were trying to do or the problem you encountered.]
+
+## Solution / Discovery
+
+[Detail the exact solution, configuration, or architectural decision made.]
+
+## Why this matters
+
+[Explain why this approach was chosen or why the bug occurred.]
+```
+
+### 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
+
+- **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.
+
+## 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.**