@syntesseraai/opencode-feature-factory 0.2.27 → 0.2.29

package/agents/building.md

@@ -33,9 +33,10 @@ At the start of EVERY building task:
 2. **Load the ff-delegation skill** and assess parallelization opportunities
 3. **Load the ff-mini-plan skill** and create an execution plan
 4. **Load the ff-todo-management skill** and create a todo list for tracking progress
-5. **Load the ff-severity-classification skill** to assess risks of changes
-6. **Document your context** - Write to `.feature-factory/agents/building-{UUID}.md`
-7. Check if there's an existing implementation plan from @planning agent
+5. **Load the ff-learning skill** to capture implementation insights
+6. **Load the ff-severity-classification skill** to assess risks of changes
+7. **Document your context** - Write to `.feature-factory/agents/building-{UUID}.md`
+8. Check if there's an existing implementation plan from @planning agent
 
 ## Core Responsibilities
 
@@ -304,3 +305,33 @@ When @reviewing agent returns findings:
 ```
 
 Create todos for each critical/high item, fix them, then re-invoke @reviewing if needed.
+
+## Capture Learnings
+
+Before completing your building task:
+
+1. **Reflect on insights gained** during implementation:
+   - Technical challenges overcome
+   - Code patterns and best practices discovered
+   - Error resolutions and debugging insights
+   - Integration challenges and solutions
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for technical patterns and best practices
+   - Create episodic memories for significant implementation experiences
+   - Create procedural memories for reusable workflows discovered
+   - Tag with relevant technology names and categories
+
+3. **Example learning capture:**
+
+   ```markdown
+   After implementing feature:
+
+   1. Generate UUID: `uuidgen`
+   2. Determine memory type based on content:
+      - Technical pattern → semantic
+      - Implementation experience → episodic
+      - Reusable workflow → procedural
+   3. Create memory file in appropriate directory
+   4. Include frontmatter with relevant tags and importance
+   ```

package/agents/ff-acceptance.md

@@ -25,8 +25,9 @@ At the start of EVERY validation task:
 
 1. **Load the ff-mini-plan skill** and create a quick 2-5 step plan for your validation approach
 2. **Load the ff-todo-management skill** and create a todo list from your plan
-3. **Load the ff-severity-classification skill** to ensure consistent issue classification
-4. **Load the ff-report-templates skill** for standardized output formatting
+3. **Load the ff-learning skill** to capture validation insights and patterns
+4. **Load the ff-severity-classification skill** to ensure consistent issue classification
+5. **Load the ff-report-templates skill** for standardized output formatting
 
 ## Scope
 
@@ -178,3 +179,32 @@ Use ff-severity-classification skill standards:
 7. Mark all todos complete before finishing
 
 Remember: Your role is to be the "gatekeeper" ensuring requirements are fully and correctly implemented before proceeding.
+
+## Capture Learnings
+
+Before completing your validation task:
+
+1. **Reflect on insights gained** during validation:
+   - Requirement validation patterns and insights
+   - Acceptance criteria patterns observed
+   - Ambiguity resolutions and scope clarifications
+   - Common gaps between requirements and implementation
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for requirement patterns
+   - Create episodic memories for significant validation findings
+   - Tag with requirement types, categories, and validation insights
+
+3. **Example memory format:**
+   ```yaml
+   ---
+   id: 'uuid-from-uuidgen'
+   title: 'Validation Pattern: [Pattern Name]'
+   description: 'Common pattern of [issue] in [type] requirements'
+   date: '2026-02-02T12:00:00Z'
+   memory_type: 'semantic'
+   agent_id: 'ff-acceptance'
+   importance: 0.7
+   tags: ['validation', 'requirements', 'pattern', '{category}']
+   ---
+   ```

package/agents/ff-research.md

@@ -24,7 +24,8 @@ At the start of EVERY research task:
 2. **Load the ff-research-methods skill** for research methodology
 3. **Load the ff-mini-plan skill** and create a research plan
 4. **Load the ff-todo-management skill** and create a todo list
-5. **Load the ff-report-templates skill** for output formatting
+5. **Load the ff-learning skill** to capture research findings and knowledge
+6. **Load the ff-report-templates skill** for output formatting
 
 ## Core Responsibilities
 
@@ -321,3 +322,34 @@ 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.
+
+## Capture Learnings
+
+Before completing your research task:
+
+1. **Reflect on insights gained** during research:
+   - Key findings and conclusions
+   - Technology comparisons and evaluations
+   - Best practices discovered
+   - Source quality assessments
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for key findings and knowledge
+   - Create episodic memories for significant research discoveries
+   - Tag with research topics, technologies, and categories
+   - Set high importance (0.8-1.0) for critical findings
+
+3. **Example memory format:**
+   ```yaml
+   ---
+   id: 'uuid-from-uuidgen'
+   title: 'Research Finding: [Topic]'
+   description: 'Key finding about [topic] from [source]'
+   date: '2026-02-02T12:00:00Z'
+   memory_type: 'semantic'
+   agent_id: 'ff-research'
+   importance: 0.9
+   tags: ['research', '{topic}', '{technology}', 'best-practices']
+   source: 'research'
+   ---
+   ```

package/agents/ff-review.md

@@ -25,8 +25,9 @@ At the start of EVERY review task:
 
 1. **Load the ff-mini-plan skill** and create a quick 2-5 step plan for your review approach
 2. **Load the ff-todo-management skill** and create a todo list from your plan
-3. **Load the ff-severity-classification skill** to ensure consistent issue classification
-4. **Load the ff-report-templates skill** for standardized output formatting
+3. **Load the ff-learning skill** to capture code quality insights and patterns
+4. **Load the ff-severity-classification skill** to ensure consistent issue classification
+5. **Load the ff-report-templates skill** for standardized output formatting
 
 ## Scope Boundaries
 
@@ -181,3 +182,32 @@ Use ff-severity-classification skill standards:
 6. Format output using ff-report-templates (Code Review template)
 7. Mark all todos complete before finishing
 8. Recommend delegating to other agents if specialized issues found
+
+## Capture Learnings
+
+Before completing your code review:
+
+1. **Reflect on insights gained** during the review:
+   - Code quality patterns observed
+   - Common issues and their solutions
+   - Best practices identified
+   - Review technique improvements
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for code patterns and anti-patterns
+   - Create episodic memories for significant review findings
+   - Tag with code quality categories, technologies, and patterns
+
+3. **Example memory format:**
+   ```yaml
+   ---
+   id: 'uuid-from-uuidgen'
+   title: 'Code Pattern: [Pattern Name]'
+   description: 'Effective pattern for [scenario] in [technology]'
+   date: '2026-02-02T12:00:00Z'
+   memory_type: 'semantic'
+   agent_id: 'ff-review'
+   importance: 0.7
+   tags: ['code-quality', 'pattern', '{technology}', '{category}']
+   ---
+   ```

package/agents/ff-security.md

@@ -25,8 +25,9 @@ At the start of EVERY security audit:
 
 1. **Load the ff-mini-plan skill** and create a quick 2-5 step plan for your audit approach
 2. **Load the ff-todo-management skill** and create a todo list from your plan
-3. **Load the ff-severity-classification skill** to ensure consistent vulnerability classification
-4. **Load the ff-report-templates skill** for standardized output formatting
+3. **Load the ff-learning skill** to capture security insights and vulnerability patterns
+4. **Load the ff-severity-classification skill** to ensure consistent vulnerability classification
+5. **Load the ff-report-templates skill** for standardized output formatting
 
 ## Scope
 
@@ -216,3 +217,32 @@ Use ff-severity-classification skill standards with security-specific definition
 6. Format output using ff-report-templates (Security Audit template)
 7. Mark all todos complete before finishing
 8. Recommend delegating to other agents if additional issues found
+
+## Capture Learnings
+
+Before completing your security audit:
+
+1. **Reflect on insights gained** during the audit:
+   - Vulnerability patterns discovered
+   - Security best practices identified
+   - Threat model insights
+   - Common security mistakes observed
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for vulnerability patterns and fixes
+   - Create episodic memories for significant security findings
+   - Tag with security categories, vulnerability types, and technologies
+
+3. **Example memory format:**
+   ```yaml
+   ---
+   id: 'uuid-from-uuidgen'
+   title: 'Security Pattern: [Vulnerability Type]'
+   description: 'Common [vulnerability] pattern in [context] and how to fix it'
+   date: '2026-02-02T12:00:00Z'
+   memory_type: 'semantic'
+   agent_id: 'ff-security'
+   importance: 0.9
+   tags: ['security', 'vulnerability', '{type}', '{technology}']
+   ---
+   ```

package/agents/ff-validate.md

@@ -25,8 +25,9 @@ At the start of EVERY validation orchestration:
 
 1. **Load the ff-mini-plan skill** and create a quick plan for your orchestration approach
 2. **Load the ff-todo-management skill** and create a todo list for tracking
-3. **Load the ff-severity-classification skill** for consistent issue classification
-4. **Load the ff-report-templates skill** for standardized output formatting
+3. **Load the ff-learning skill** to capture validation insights and patterns
+4. **Load the ff-severity-classification skill** for consistent issue classification
+5. **Load the ff-report-templates skill** for standardized output formatting
 
 ## Core Responsibilities
 
@@ -209,3 +210,32 @@ 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
+
+## Capture Learnings
+
+Before completing your validation orchestration:
+
+1. **Reflect on insights gained** during validation:
+   - Validation patterns and effective techniques
+   - Common issues found across multiple agents
+   - Orchestration efficiency improvements
+   - Cross-agent finding patterns
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for validation patterns
+   - Create episodic memories for significant validation results
+   - Tag with validation types, agent combinations, and categories
+
+3. **Example memory format:**
+   ```yaml
+   ---
+   id: 'uuid-from-uuidgen'
+   title: 'Validation Pattern: [Pattern Name]'
+   description: 'Common pattern of [findings] when validating [type] changes'
+   date: '2026-02-02T12:00:00Z'
+   memory_type: 'semantic'
+   agent_id: 'ff-validate'
+   importance: 0.7
+   tags: ['validation', 'orchestration', 'pattern', '{category}']
+   ---
+   ```

package/agents/ff-well-architected.md

@@ -25,8 +25,9 @@ At the start of EVERY architecture review:
 
 1. **Load the ff-mini-plan skill** and create a quick 2-5 step plan for your review approach
 2. **Load the ff-todo-management skill** and create a todo list from your plan
-3. **Load the ff-severity-classification skill** to ensure consistent issue classification
-4. **Load the ff-report-templates skill** for standardized output formatting
+3. **Load the ff-learning skill** to capture architectural insights and patterns
+4. **Load the ff-severity-classification skill** to ensure consistent issue classification
+5. **Load the ff-report-templates skill** for standardized output formatting
 
 ## Scope
 
@@ -179,3 +180,32 @@ Use ff-severity-classification skill standards:
 8. Invoke other agents if specialized issues found
 
 Focus on providing actionable, specific recommendations that improve the overall architecture quality across all six pillars.
+
+## Capture Learnings
+
+Before completing your architecture review:
+
+1. **Reflect on insights gained** during the review:
+   - Architectural patterns and anti-patterns observed
+   - Pillar-specific insights (Operational Excellence, Security, Reliability, etc.)
+   - Scalability and efficiency considerations
+   - Cross-pillar interactions and trade-offs
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for architectural patterns
+   - Create episodic memories for significant architectural findings
+   - Tag with pillar names, architecture categories, and patterns
+
+3. **Example memory format:**
+   ```yaml
+   ---
+   id: 'uuid-from-uuidgen'
+   title: 'Architecture Pattern: [Pattern Name]'
+   description: 'Pattern for achieving [pillar] excellence in [context]'
+   date: '2026-02-02T12:00:00Z'
+   memory_type: 'semantic'
+   agent_id: 'ff-well-architected'
+   importance: 0.8
+   tags: ['architecture', '{pillar}', 'pattern', '{category}']
+   ---
+   ```

package/agents/planning.md

@@ -16,10 +16,6 @@ permission:
   task:
     'ff-*': allow
     explore: allow
-  write:
-    '.feature-factory/agents/*': allow
-  edit:
-    '.feature-factory/agents/*': allow
 ---
 
 You are a planning specialist for Feature Factory. Your role is to create comprehensive implementation plans before any code changes are made.
@@ -32,8 +28,9 @@ At the start of EVERY planning task:
 2. **Load the ff-delegation skill** and assess parallelization opportunities
 3. **Load the ff-mini-plan skill** and assess task complexity
 4. **Load the ff-todo-management skill** and create a todo list for the planning process
-5. **Load the ff-report-templates skill** for standardized output formatting
-6. **Document your context** - Write to `.feature-factory/agents/planning-{UUID}.md`
+5. **Load the ff-learning skill** to capture planning insights and patterns
+6. **Load the ff-report-templates skill** for standardized output formatting
+7. **Document your context** - Use `ff-agent-context-create` tool to create `.feature-factory/agents/planning-{UUID}.md`
 
 ## Core Responsibilities
 
@@ -192,7 +189,7 @@ Recommend escalation to full architectural planning when:
 
 1. **Generate UUID** - Create unique ID for this planning instance
 2. **Load required skills** (ff-delegation, ff-mini-plan, ff-todo-management, ff-report-templates)
-3. **Document context** - Write to `.feature-factory/agents/planning-{UUID}.md`
+3. **Document context** - Use `ff-agent-context-create` tool to create `.feature-factory/agents/planning-{UUID}.md`
 4. **Delegate in parallel**:
    - Task(ff-research): "Research [technology] best practices"
    - Task(ff-acceptance): "Validate acceptance criteria"
@@ -218,3 +215,33 @@ 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
+
+## Capture Learnings
+
+Before completing your planning task:
+
+1. **Reflect on insights gained** during planning:
+   - Architecture decisions made and their rationale
+   - Risk factors identified and mitigation strategies
+   - Pattern discoveries from codebase exploration
+   - Estimation accuracy and lessons learned
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for architectural patterns discovered
+   - Create episodic memories for significant planning decisions
+   - Tag with relevant keywords (architecture, patterns, risks, decisions)
+
+3. **Example learning capture:**
+
+   ```markdown
+   After completing planning:
+
+   Use ff-learning-store tool:
+
+   - title: "Architecture Decision: [Decision Name]"
+   - description: "Rationale for choosing [approach] over [alternatives]"
+   - memoryType: "semantic"
+   - tags: ["architecture", "decision", "{technology}"]
+   - importance: 0.8
+   - content: "Detailed explanation of the decision..."
+   ```

package/agents/reviewing.md

@@ -5,7 +5,7 @@ temperature: 0.1
 color: '#f59e0b'
 tools:
   read: true
-  write: true
+  write: false
   edit: false
   bash: false
   skill: true
@@ -16,8 +16,6 @@ permission:
   task:
     'ff-*': allow
     building: allow
-  write:
-    '.feature-factory/agents/*': allow
 ---
 
 You are a reviewing/validation specialist for Feature Factory. Your role is to comprehensively validate code changes and provide actionable feedback to the @building agent.
@@ -29,9 +27,10 @@ At the start of EVERY review task:
 1. **Generate your UUID** - Create unique ID: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
 2. **Load the ff-delegation skill** for parallel validation orchestration
 3. **Load the ff-todo-management skill** and create a todo list for tracking review progress
-4. **Load the ff-report-templates skill** for standardized output formatting
-5. **Load the ff-severity-classification skill** to classify findings consistently
-6. **Document your context** - Write to `.feature-factory/agents/reviewing-{UUID}.md`
+4. **Load the ff-learning skill** to capture review patterns and insights
+5. **Load the ff-report-templates skill** for standardized output formatting
+6. **Load the ff-severity-classification skill** to classify findings consistently
+7. **Document your context** - Write to `.feature-factory/agents/reviewing-{UUID}.md`
 
 ## Core Responsibilities
 
@@ -240,11 +239,11 @@ When combining results from multiple agents:
 
 1. **Generate UUID** - Create unique ID for this reviewing instance
 2. **Load required skills** (ff-delegation, ff-todo-management, ff-report-templates, ff-severity-classification)
-3. **Document context** - Write to `.feature-factory/agents/reviewing-{UUID}.md`
+3. **Document context** - Use `ff-agent-context-create` tool to create `.feature-factory/agents/reviewing-{UUID}.md`
 4. **Create review todo list**
 5. **Mark "Launch validation"** as in_progress
 6. **Invoke @ff-validate agent** (runs 4 sub-agents in parallel)
-7. **Track child agents** - Add their UUIDs to your `delegated_to` list
+7. **Track child agents** - Use `ff-agent-context-update` tool to add their UUIDs to your `delegated_to` list
 8. **Monitor progress** - `ff-agents-current()`
 9. **Wait for results**, mark todo complete
 10. **Mark "Aggregate results"** as in_progress
@@ -312,3 +311,33 @@ Typical workflow:
 8. Repeat until clean or only low-priority items remain
 
 This creates a tight feedback loop between building and reviewing for high-quality output.
+
+## Capture Learnings
+
+Before completing your review task:
+
+1. **Reflect on insights gained** during validation:
+   - Common issues and patterns identified across reviews
+   - Quality patterns observed in good implementations
+   - Review effectiveness and process improvements
+   - Tool and technique discoveries
+
+2. **Store important learnings** using ff-learning skill:
+   - Create semantic memories for common issue patterns and solutions
+   - Create episodic memories for significant review findings
+   - Tag with review type, categories, and technologies reviewed
+
+3. **Example learning capture:**
+
+   ```markdown
+   After completing review:
+
+   Use ff-learning-store tool:
+
+   - title: "Review Pattern: [Common Issue Type]"
+   - description: "Common pattern of [issue] found in [context]"
+   - memoryType: "semantic"
+   - tags: ["review", "pattern", "{issue-type}", "{technology}"]
+   - importance: 0.7
+   - content: "Detailed explanation of the pattern and solution..."
+   ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "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,862 @@
+---
+name: ff-learning
+description: Enables agents to capture, store, and retrieve learnings from their work. Use this skill to create memory files with YAML frontmatter, search past learnings, and build organizational knowledge over time.
+license: MIT
+compatibility: opencode
+metadata:
+  audience: agents
+  category: knowledge-management
+---
+
+# Learning Skill
+
+Use this skill to capture insights, store knowledge, and retrieve past learnings to improve future work.
+
+## When to Use
+
+### Required (ALWAYS use when):
+
+- **Completing any significant task** - Store what was learned
+- **Resolving errors or issues** - Document the solution for future reference
+- **Discovering new patterns** - Capture reusable approaches
+- **Making architectural decisions** - Record rationale and context
+- **Researching technologies** - Save key findings and sources
+
+### Optional (use when helpful):
+
+- **Quick fixes** - Simple one-line changes may not need learning capture
+- **Routine tasks** - Well-understood repetitive work
+- **Draft work** - Temporary explorations that won't be retained
+
+## Memory Types
+
+Agents can create three types of memories:
+
+### 1. Episodic Memories (Experiences)
+
+**What:** Specific experiences, events, or task executions  
+**When to use:** After completing tasks, resolving issues, or having significant interactions  
+**Example:** "Successfully implemented OAuth flow - encountered CSRF issue, resolved by adding state parameter"  
+**File naming:** `YYYY-MM-DD-HH-mm-ss-{agent}-{type}.md`
+
+### 2. Semantic Memories (Facts & Knowledge)
+
+**What:** Factual knowledge, concepts, or understanding about the domain  
+**When to use:** When researching technologies, understanding requirements, or documenting patterns  
+**Example:** "React Server Components require 'use client' directive for client-side interactivity"  
+**File naming:** `{category}-{uuid}.md`
+
+### 3. Procedural Memories (Skills & Procedures)
+
+**What:** Step-by-step procedures, workflows, or how-to guides  
+**When to use:** When documenting processes, creating reusable workflows, or standardizing approaches  
+**Example:** "How to set up authentication with NextAuth.js in a Next.js application"  
+**File naming:** `{skill-name}-{version}.md`
+
+## Frontmatter Schema
+
+Every memory file MUST include YAML frontmatter with these fields:
+
+```yaml
+---
+id: 'uuid-v4-format' # Required: Unique identifier
+title: 'Brief, descriptive title' # Required: Human-readable title
+description: 'Detailed description' # Required: What was learned
+date: '2026-02-02T12:00:00Z' # Required: ISO 8601 timestamp
+memory_type: 'episodic|semantic|procedural' # Required: Type of memory
+agent_id: 'agent-name' # Required: Which agent created this
+importance: 0.0-1.0 # Required: 0.0 (low) to 1.0 (critical)
+tags: ['keyword1', 'keyword2'] # Required: Searchable keywords
+source: 'conversation|research|implementation|review' # Optional: Origin
+related_memories: ['uuid-1', 'uuid-2'] # Optional: Related memory IDs
+context: # Optional: Additional context
+  project: 'project-name'
+  task: 'task-description'
+  files: ['file1.ts', 'file2.ts']
+---
+```
+
+### Field Descriptions
+
+| Field              | Type   | Required | Description                                            |
+| ------------------ | ------ | -------- | ------------------------------------------------------ |
+| `id`               | string | Yes      | UUID v4 format, uniquely identifies this memory        |
+| `title`            | string | Yes      | Brief, searchable title (50-100 chars ideal)           |
+| `description`      | string | Yes      | Detailed explanation of the learning                   |
+| `date`             | string | Yes      | ISO 8601 timestamp when memory was created             |
+| `memory_type`      | enum   | Yes      | One of: episodic, semantic, procedural                 |
+| `agent_id`         | string | Yes      | Name of the agent that created this memory             |
+| `importance`       | float  | Yes      | 0.0 to 1.0, higher = more important                    |
+| `tags`             | array  | Yes      | Keywords for search and categorization                 |
+| `source`           | enum   | No       | Origin: conversation, research, implementation, review |
+| `related_memories` | array  | No       | UUIDs of related memories for linking                  |
+| `context`          | object | No       | Additional structured context (project, task, files)   |
+
+## File Organization
+
+### Directory Structure
+
+```
+.feature-factory/memories/
+├── episodic/          # Experience-based learnings
+│   └── YYYY/
+│       └── MM/
+│           └── DD/
+│               └── HH-mm-ss-{agent}-{type}.md
+├── semantic/          # Factual knowledge
+│   └── {category}/
+│       └── {topic}-{uuid}.md
+├── procedural/        # Skills and procedures
+│   └── {type}/
+│       └── {skill-name}-{version}.md
+└── index/            # Search indices (auto-generated)
+    └── tags.json
+```
+
+### Naming Conventions
+
+**Episodic:**
+
+- Format: `YYYY-MM-DD-HH-mm-ss-{agent}-{descriptor}.md`
+- Example: `2026-02-02-14-30-00-building-oauth-implementation.md`
+
+**Semantic:**
+
+- Format: `{category}-{uuid}.md`
+- Example: `react-server-components-550e8400-e29b-41d4-a716-446655440000.md`
+
+**Procedural:**
+
+- Format: `{skill-name}-{version}.md`
+- Example: `nextauth-setup-v1.md`
+
+## Tools
+
+The ff-learning skill provides three tools for agents to interact with the memory system. These tools are especially important for **read-only agents** (like @planning and @reviewing) that cannot directly write files.
+
+### Using the Tools
+
+**For read-only agents:** Use the tool calls directly:
+
+```markdown
+Store a learning using ff-learning-store tool:
+
+- title: "OAuth Implementation Pattern"
+- description: "Successfully implemented OAuth with NextAuth.js"
+- memoryType: "semantic"
+- tags: ["oauth", "nextauth", "authentication"]
+- importance: 0.8
+```
+
+**For agents with write permissions:** Can use either tools or direct file operations.
+
+### Tool 1: Store Learning (ff-learning-store)
+
+**Purpose:** Create a new memory file with proper frontmatter
+
+**When to use:**
+
+- At end of task completion
+- When insight or pattern is discovered
+- After error resolution
+- When research findings are significant
+
+**Input parameters:**
+
+- `title` (string, required): Brief title for the learning
+- `description` (string, required): Detailed description
+- `memory_type` (enum, required): episodic, semantic, or procedural
+- `tags` (array, required): Relevant keywords
+- `importance` (float, required): 0.0 to 1.0
+- `content` (string, optional): Additional markdown content
+- `source` (enum, optional): Origin of the learning
+- `related_memories` (array, optional): UUIDs of related memories
+
+**Process:**
+
+1. Generate UUID using `uuidgen` or similar
+2. Get current timestamp in ISO 8601 format
+3. Determine appropriate directory based on memory_type
+4. Format frontmatter with all required fields
+5. Write file to appropriate location
+6. Return the file path
+
+**Example:**
+
+```markdown
+## Store Learning Example
+
+After implementing OAuth:
+
+1. Generate UUID: `uuidgen` → `550e8400-e29b-41d4-a716-446655440000`
+2. Create timestamp: `date -u +%Y-%m-%dT%H:%M:%SZ` → `2026-02-02T14:30:00Z`
+3. Determine directory: `semantic/authentication/`
+4. Write file: `semantic/authentication/oauth-implementation-550e8400.md`
+5. Content includes frontmatter + detailed implementation notes
+```
+
+### Tool 2: Search Learnings
+
+**Purpose:** Find relevant memories by keywords/tags
+
+**When to use:**
+
+- At start of new task (find related past work)
+- When facing similar problem to previous one
+- For context gathering before planning
+- To avoid repeating mistakes
+
+**Input parameters:**
+
+- `query` (string, required): Search terms
+- `tags` (array, optional): Filter by specific tags
+- `memory_type` (enum, optional): Filter by type
+- `agent_id` (string, optional): Filter by agent
+- `limit` (number, optional): Max results (default: 10)
+- `min_importance` (float, optional): Minimum importance threshold
+
+**Process:**
+
+1. Use `glob` to find all memory files: `.feature-factory/memories/**/*.md`
+2. Read frontmatter from each file
+3. Match against query (title, description, tags)
+4. Apply filters (tags, type, agent, importance)
+5. Sort by relevance and importance
+6. Return array of matching memory metadata
+
+**Example:**
+
+```markdown
+## Search Example
+
+Before implementing authentication:
+
+1. Search: `query: "OAuth", tags: ["authentication", "security"]`
+2. Find: `semantic/authentication/oauth-implementation-550e8400.md`
+3. Review: Read the memory to understand previous approach
+4. Apply: Use lessons learned in new implementation
+```
+
+### Tool 3: Get Learning
+
+**Purpose:** Retrieve full content of a specific memory
+
+**When to use:**
+
+- After search to read full details
+- When referenced by ID in another memory
+- For deep dive into specific learning
+
+**Input parameters:**
+
+- `memory_id` (string, optional): UUID of the memory
+- `file_path` (string, optional): Direct path to memory file
+
+**Process:**
+
+1. If `memory_id` provided, search for file containing that ID
+2. If `file_path` provided, read directly
+3. Parse frontmatter and content
+4. Return complete memory object
+
+**Example:**
+
+```markdown
+## Get Learning Example
+
+After finding a relevant memory:
+
+1. Get by ID: `memory_id: "550e8400-e29b-41d4-a716-446655440000"`
+2. Or get by path: `file_path: "semantic/authentication/oauth-implementation-550e8400.md"`
+3. Read full content including implementation details
+4. Apply learnings to current task
+```
+
+## Additional Tools for Read-Only Agents
+
+Since @planning and @reviewing agents are read-only (cannot write/edit files), the following tools are provided for essential file operations:
+
+### Tool 4: Create Plan (ff-plan-create)
+
+**Purpose:** Create a new implementation plan file in `.feature-factory/plans/`
+
+**When to use:**
+
+- At the end of planning sessions to document the plan
+- When creating architecture or migration plans
+- To document research findings as structured plans
+
+**Input parameters:**
+
+- `title` (string, required): Title of the plan
+- `description` (string, required): What the plan covers
+- `content` (string, required): Full markdown content
+- `planType` (enum, required): implementation, architecture, migration, or research
+- `relatedIssues` (array, optional): Related issue IDs
+- `estimatedEffort` (string, optional): Time estimate
+
+**Example:**
+
+```markdown
+Create plan using ff-plan-create:
+
+- title: "OAuth Implementation Plan"
+- description: "Plan for implementing OAuth authentication"
+- content: "## Phase 1: Setup..."
+- planType: "implementation"
+- estimatedEffort: "2-3 hours"
+```
+
+### Tool 5: Create Agent Context (ff-agent-context-create)
+
+**Purpose:** Create a new agent context file in `.feature-factory/agents/`
+
+**When to use:**
+
+- At the start of EVERY agent task to document context
+- When delegating work to track parent-child relationships
+- To maintain agent state and progress
+
+**Input parameters:**
+
+- `id` (string, required): UUID for this agent instance
+- `agent` (string, required): Agent type (planning, building, etc.)
+- `title` (string, required): Task title
+- `description` (string, required): Task description
+- `status` (enum, optional): in-progress, completed, delegated, failed
+- `parent` (string, optional): Parent agent UUID
+- `delegatedTo` (array, optional): Child agent UUIDs
+- `notes` (string, optional): Additional notes
+
+**Example:**
+
+```markdown
+Create agent context using ff-agent-context-create:
+
+- id: "550e8400-e29b-41d4-a716-446655440000"
+- agent: "planning"
+- title: "Implement OAuth"
+- description: "Plan OAuth implementation for customer portal"
+- status: "in-progress"
+```
+
+### Tool 6: Update Agent Context (ff-agent-context-update)
+
+**Purpose:** Update an existing agent context file
+
+**When to use:**
+
+- When status changes (e.g., completed, delegated)
+- When adding delegated child agents
+- When appending progress updates or notes
+
+**Input parameters:**
+
+- `agentId` (string, required): Agent UUID to update
+- `agent` (string, required): Agent type
+- `status` (enum, optional): New status
+- `addDelegatedTo` (string, optional): Add child agent UUID
+- `notes` (string, optional): Notes to append
+- `progressUpdate` (string, optional): Progress line to add
+
+**Example:**
+
+```markdown
+Update agent context using ff-agent-context-update:
+
+- agentId: "550e8400-e29b-41d4-a716-446655440000"
+- agent: "planning"
+- status: "completed"
+- notes: "Planning finished successfully"
+```
+
+## Usage by Agent Type
+
+### Planning Agent
+
+**When to capture:**
+
+- After completing planning session
+- When architectural decisions are made
+- When risks are identified
+
+**What to capture:**
+
+- Architecture decisions and rationale
+- Risk factors and mitigation strategies
+- Pattern discoveries from codebase exploration
+- Estimation accuracy reflections
+
+**Example workflow:**
+
+```markdown
+At end of planning session:
+
+1. Reflect on what was learned
+2. Store key insights:
+   - Architecture decisions made
+   - Risk factors identified
+   - Pattern discoveries
+3. Tag with relevant keywords
+4. Link related memories
+```
+
+### Building Agent
+
+**When to capture:**
+
+- After implementing feature
+- When technical challenge is overcome
+- When error is resolved
+- When new pattern is discovered
+
+**What to capture:**
+
+- Technical implementation details
+- Code patterns and best practices
+- Error resolutions and debugging steps
+- Integration challenges and solutions
+
+**Example workflow:**
+
+```markdown
+After implementing feature:
+
+1. Document technical learnings
+2. Store code patterns discovered
+3. Record error resolutions
+4. Tag with technology names
+5. Link to related documentation
+```
+
+### Reviewing Agent
+
+**When to capture:**
+
+- After completing review
+- When common issues are identified
+- When quality patterns are observed
+
+**What to capture:**
+
+- Common issues and their solutions
+- Quality patterns observed
+- Review effectiveness insights
+- Improvement recommendations
+
+**Example workflow:**
+
+```markdown
+After completing review:
+
+1. Summarize findings
+2. Store patterns of issues found
+3. Document effective review techniques
+4. Tag with review type and categories
+```
+
+### Research Agent
+
+**When to capture:**
+
+- After completing research
+- When significant findings are discovered
+- When technology evaluation is complete
+
+**What to capture:**
+
+- Key findings and conclusions
+- Technology comparisons
+- Best practices discovered
+- Source references and links
+
+**Example workflow:**
+
+```markdown
+After completing research:
+
+1. Store key findings as semantic memories
+2. Tag with research topics
+3. Link to sources
+4. Set high importance for critical findings
+```
+
+### Security Agent
+
+**When to capture:**
+
+- After security audit
+- When vulnerabilities are found
+- When security patterns are identified
+
+**What to capture:**
+
+- Vulnerability findings and fixes
+- Security best practices
+- Threat model insights
+- Compliance considerations
+
+**Example workflow:**
+
+```markdown
+After security audit:
+
+1. Document vulnerabilities found
+2. Store security best practices
+3. Record threat model insights
+4. Tag with security categories
+```
+
+### Acceptance Agent
+
+**When to capture:**
+
+- After validating requirements
+- When acceptance criteria insights are gained
+- When requirement patterns are identified
+
+**What to capture:**
+
+- Requirement validation insights
+- Acceptance criteria patterns
+- Ambiguity resolutions
+- Scope clarifications
+
+**Example workflow:**
+
+```markdown
+After validating requirements:
+
+1. Document requirement insights
+2. Store acceptance criteria patterns
+3. Record ambiguity resolutions
+4. Tag with requirement types
+```
+
+## Integration with Other Skills
+
+### With ff-delegation
+
+- Store learnings from delegated agents
+- Capture insights from parallel work
+- Link related memories across agent boundaries
+
+### With ff-todo-management
+
+- Add "Capture learnings" as final todo item
+- Track learning capture in todo list
+- Ensure learnings are not forgotten
+
+### With ff-mini-plan
+
+- Search past learnings during planning
+- Use previous patterns to inform new plans
+- Store plan effectiveness as episodic memory
+
+### With ff-report-templates
+
+- Use standardized formats for memory content
+- Include severity/confidence in technical learnings
+- Apply report structure to procedural memories
+
+## Best Practices
+
+### Do:
+
+- ✅ **Be specific** - Concrete details are more useful than generalities
+- ✅ **Use consistent tags** - Establish tag conventions for your project
+- ✅ **Set appropriate importance** - Reserve 0.8-1.0 for truly critical learnings
+- ✅ **Link related memories** - Create connections between related learnings
+- ✅ **Include context** - Project, task, and file context helps retrieval
+- ✅ **Write searchable titles** - Use keywords that future you will search for
+- ✅ **Capture failures too** - What didn't work is as valuable as what did
+- ✅ **Review periodically** - Search old learnings before starting new tasks
+
+### Don't:
+
+- ❌ **Store everything** - Not every small change needs a memory
+- ❌ **Use vague titles** - "Fixed bug" is not helpful; "Fixed race condition in auth middleware" is
+- ❌ **Duplicate memories** - Search first to avoid redundancy
+- ❌ **Forget tags** - Untagged memories are hard to find
+- ❌ **Store secrets** - Never put credentials or sensitive data in memories
+- ❌ **Be too brief** - One-line descriptions lack context
+
+## Common Mistakes to Avoid
+
+### Mistake 1: Not Searching First
+
+**Problem:** Creating duplicate memories for the same learning  
+**Solution:** Always search before storing: `Search learnings with query and tags`
+
+### Mistake 2: Poor Tagging
+
+**Problem:** Memories can't be found later due to inconsistent or missing tags  
+**Solution:** Establish tag conventions: technology names, categories, project names
+
+### Mistake 3: Wrong Memory Type
+
+**Problem:** Using episodic for procedural knowledge or vice versa  
+**Solution:**
+
+- Episodic = specific event/task
+- Semantic = general knowledge
+- Procedural = how-to guide
+
+### Mistake 4: Missing Context
+
+**Problem:** Memory lacks context to be useful later  
+**Solution:** Always include project, task, and relevant files in context field
+
+### Mistake 5: Not Capturing Failures
+
+**Problem:** Only storing successes, missing valuable failure lessons  
+**Solution:** Store what didn't work and why - prevents future repetition
+
+## Example Memory Files
+
+### Example 1: Episodic Memory
+
+````markdown
+---
+id: '550e8400-e29b-41d4-a716-446655440000'
+title: 'OAuth Implementation with NextAuth.js'
+description: 'Successfully implemented OAuth authentication using NextAuth.js with Google provider. Encountered and resolved CSRF token issues.'
+date: '2026-02-02T14:30:00Z'
+memory_type: 'episodic'
+agent_id: 'building'
+importance: 0.8
+tags: ['oauth', 'nextauth', 'authentication', 'nextjs', 'csrf']
+source: 'implementation'
+context:
+  project: 'customer-portal'
+  task: 'Implement Google OAuth'
+  files: ['app/api/auth/[...nextauth]/route.ts', 'lib/auth.ts']
+---
+
+## Implementation Details
+
+### What Worked
+
+1. Using NextAuth.js with Google provider
+2. Configuring callback URLs properly
+3. Storing user data in Supabase after OAuth
+
+### Challenges Faced
+
+1. **CSRF Token Mismatch**
+   - Issue: State parameter not being validated
+   - Solution: Added explicit state parameter in OAuth config
+   - Code: See lib/auth.ts lines 45-52
+
+2. **Session Persistence**
+   - Issue: Sessions not persisting across page reloads
+   - Solution: Configured JWT strategy with database persistence
+
+### Key Code Pattern
+
+```typescript
+// Always include state parameter for CSRF protection
+providers: [
+  GoogleProvider({
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    authorization: {
+      params: {
+        state: generateState(),
+      },
+    },
+  }),
+],
+```
+````
+
+### Lessons Learned
+
+- Always validate state parameter in OAuth flows
+- Test session persistence across page reloads
+- Use JWT strategy for serverless environments
+
+````
+
+### Example 2: Semantic Memory
+
+```markdown
+---
+id: '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
+title: 'React Server Components Data Fetching'
+description: 'Understanding when and how to fetch data in React Server Components vs Client Components'
+date: '2026-02-01T10:00:00Z'
+memory_type: 'semantic'
+agent_id: 'research'
+importance: 0.9
+tags: ['react', 'server-components', 'data-fetching', 'nextjs', 'patterns']
+source: 'research'
+related_memories: ['550e8400-e29b-41d4-a716-446655440000']
+---
+
+## Key Concepts
+
+### Server Components
+
+- Can be async functions
+- Can fetch data directly
+- Run on server only
+- Cannot use useState, useEffect, or browser APIs
+
+### Client Components
+
+- Must use 'use client' directive
+- Cannot be async
+- Use useEffect for data fetching
+- Can use all React hooks and browser APIs
+
+### Best Practices
+
+1. **Fetch in Server Components when possible**
+   - Better performance
+   - Reduced client-side JavaScript
+   - Direct database access
+
+2. **Use Client Components for interactivity**
+   - Forms with validation
+   - Real-time updates
+   - Browser-only features
+
+3. **Pass data as props**
+   - Server Component fetches data
+   - Passes to Client Component as props
+   - Client Component handles interactivity
+
+### Code Example
+
+```typescript
+// Server Component (app/page.tsx)
+async function Page() {
+  const data = await fetchData(); // Direct fetch
+  return <ClientComponent initialData={data} />;
+}
+
+// Client Component (components/ClientComponent.tsx)
+'use client';
+
+function ClientComponent({ initialData }) {
+  const [data, setData] = useState(initialData);
+  // Handle interactivity...
+}
+````
+
+````
+
+### Example 3: Procedural Memory
+
+```markdown
+---
+id: '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
+title: 'Setting Up Feature Factory in New Project'
+description: 'Step-by-step procedure for installing and configuring Feature Factory in a new codebase'
+date: '2026-01-15T09:00:00Z'
+memory_type: 'procedural'
+agent_id: 'building'
+importance: 0.7
+tags: ['feature-factory', 'setup', 'installation', 'configuration']
+source: 'implementation'
+---
+
+## Prerequisites
+
+- Node.js 18+
+- Git repository initialized
+- opencode CLI installed
+
+## Steps
+
+### 1. Install Plugin
+
+```bash
+cd packages/opencode-plugin
+npm install
+npm run build
+````
+
+### 2. Configure Agents
+
+Create `.config/opencode/agents/` directory and copy agent files:
+
+```bash
+mkdir -p .config/opencode/agents
+cp -r packages/opencode-plugin/agents/* .config/opencode/agents/
+```
+
+### 3. Configure Skills
+
+Create `.config/opencode/skills/` directory and copy skill files:
+
+```bash
+mkdir -p .config/opencode/skills
+cp -r packages/opencode-plugin/skills/* .config/opencode/skills/
+```
+
+### 4. Initialize Feature Factory
+
+```bash
+npx ff-setup
+```
+
+### 5. Verify Setup
+
+```bash
+npx ff-doctor
+```
+
+## Common Issues
+
+### Issue: Agents not found
+
+**Solution:** Check that agent files are in `.config/opencode/agents/`
+
+### Issue: Skills not loading
+
+**Solution:** Verify skill files have proper frontmatter
+
+## Next Steps
+
+- Read `docs/GETTING_STARTED.md`
+- Try running `@planning` agent
+- Create your first feature plan
+
+````
+
+## Quick Reference
+
+### Creating a Memory
+
+1. Generate UUID: `uuidgen`
+2. Get timestamp: `date -u +%Y-%m-%dT%H:%M:%SZ`
+3. Choose directory based on type
+4. Write file with frontmatter + content
+5. Include tags for searchability
+
+### Searching Memories
+
+```markdown
+Search learnings:
+- query: "authentication"
+- tags: ["oauth", "security"]
+- memory_type: "semantic"
+- limit: 5
+````
+
+### Memory Checklist
+
+Before storing a memory, verify:
+
+- [ ] UUID is unique
+- [ ] Title is descriptive and searchable
+- [ ] Description explains what was learned
+- [ ] Date is ISO 8601 format
+- [ ] Memory type is correct
+- [ ] Agent ID is set
+- [ ] Importance is appropriate (0.0-1.0)
+- [ ] Tags are relevant and consistent
+- [ ] Context includes project/task/files
+- [ ] No sensitive data included