@syntesseraai/opencode-feature-factory 0.2.45 → 0.3.0

package/skills/ff-learning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Enables agents to capture, store, and retrieve learnings from their work. Uses Local-Recall MCP-backed memory system with automatic extraction from OpenCode sessions.
 license: MIT
 compatibility: opencode
 metadata:
@@ -8,151 +8,82 @@ metadata:
   category: knowledge-management
 ---
 
-# Learning Skill
+# Learning Skill (Local-Recall)
 
-Use this skill to capture insights, store knowledge, and retrieve past learnings to improve future work.
+Use this skill to capture insights, store knowledge, and retrieve past learnings to improve future work. Memories are stored as JSON in `.feature-factory/local-recall/memories/` and automatically extracted from OpenCode session history.
 
-## When to Use
-
-### Required (ALWAYS use when):
+## How It Works
 
-- **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):
+The Local-Recall memory system has two paths for creating memories:
 
-- **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
+1. **Automatic extraction** – A background daemon reads OpenCode session history (`~/.local/share/opencode/storage/`) and extracts insights from assistant messages and thinking blocks.
+2. **Explicit storage** – Agents can store learnings directly using the `ff-learning-store` tool.
 
-## Memory Types
+Both paths write to the same JSON-based memory store, ensuring a unified search experience.
 
-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`
+## When to Use
 
-### 2. Semantic Memories (Facts & Knowledge)
+### Required (ALWAYS use when):
 
-**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`
+- **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
 
-### 3. Procedural Memories (Skills & Procedures)
+### Optional (use when helpful):
 
-**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`
+- **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
 
-## Frontmatter Schema
+## Memory Categories
 
-Every memory file MUST include YAML frontmatter with these fields:
+Memories are organized by category:
 
-```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']
----
-```
+### 1. Pattern
 
-### 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)   |
+**What:** Reusable code patterns, architectural patterns, and best practices
+**When to use:** When a repeatable technique or approach is discovered
+**Example:** "React Server Components require 'use client' directive for client-side interactivity"
 
-## File Organization
+### 2. Decision
 
-### Directory Structure
+**What:** Architectural decisions, technology choices, and their rationale
+**When to use:** When a significant decision is made during planning or implementation
+**Example:** "Chose NextAuth.js over Auth0 for OAuth - simpler integration, lower cost for our scale"
 
-```
-.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
-```
+### 3. Debugging
 
-### Naming Conventions
+**What:** Error resolutions, debugging steps, and troubleshooting knowledge
+**When to use:** After resolving a non-trivial bug or error
+**Example:** "CSRF token mismatch in OAuth - resolved by adding explicit state parameter"
 
-**Episodic:**
+### 4. Preference
 
-- Format: `YYYY-MM-DD-HH-mm-ss-{agent}-{descriptor}.md`
-- Example: `2026-02-02-14-30-00-building-oauth-implementation.md`
+**What:** Team conventions, style preferences, and configuration choices
+**When to use:** When establishing or discovering project conventions
+**Example:** "Team prefers barrel exports for module directories"
 
-**Semantic:**
+### 5. Context
 
-- Format: `{category}-{uuid}.md`
-- Example: `react-server-components-550e8400-e29b-41d4-a716-446655440000.md`
+**What:** Domain knowledge, project context, and environmental information
+**When to use:** When important contextual information is gathered during research
+**Example:** "Production DB uses read replicas - write queries must target primary"
 
-**Procedural:**
+### 6. Procedure
 
-- Format: `{skill-name}-{version}.md`
-- Example: `nextauth-setup-v1.md`
+**What:** Step-by-step procedures, workflows, and how-to guides
+**When to use:** When documenting a process that should be repeatable
+**Example:** "How to set up authentication with NextAuth.js in a Next.js application"
 
 ## 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.
+The ff-learning skill provides three tools for interacting with the memory system.
 
 ### Tool 1: Store Learning (ff-learning-store)
 
-**Purpose:** Create a new memory file with proper frontmatter
+**Purpose:** Create a new memory explicitly
 
 **When to use:**
 
@@ -164,40 +95,30 @@ Store a learning using ff-learning-store tool:
 **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
+- `description` (string, required): Detailed description of the learning
+- `category` (enum, required): One of `pattern`, `decision`, `debugging`, `preference`, `context`, or `procedure`
+- `tags` (array of strings, required): Relevant keywords for search
+- `importance` (float, required): 0.0 to 1.0 (0.8+ for critical learnings)
+- `content` (string, optional): Additional body content
+- `source` (enum, optional): Origin – conversation, research, implementation, review
+- `relatedMemories` (array, optional): IDs of related memories
 
 **Example:**
 
 ```markdown
-## Store Learning Example
-
-After implementing OAuth:
+Store a learning using ff-learning-store:
 
-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
+- title: "OAuth Implementation Pattern"
+- description: "Successfully implemented OAuth with NextAuth.js, resolved CSRF issues"
+- category: "pattern"
+- tags: ["oauth", "nextauth", "authentication"]
+- importance: 0.8
+- content: "Used state parameter to prevent CSRF. JWT strategy for session persistence."
 ```
 
-### Tool 2: Search Learnings
+### Tool 2: Search Learnings (ff-learning-search)
 
-**Purpose:** Find relevant memories by keywords/tags
+**Purpose:** Find relevant memories by keywords and filters
 
 **When to use:**
 
@@ -208,38 +129,27 @@ After implementing OAuth:
 
 **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
+- `query` (string, required): Search terms to match against title, body, and tags
+- `tags` (array, optional): Filter to memories containing ALL specified tags
+- `category` (enum, optional): Filter by category (`pattern`, `decision`, `debugging`, `preference`, `context`, `procedure`)
+- `limit` (number, optional): Max results, 1-50 (default: 10)
+- `minImportance` (float, optional): Minimum importance threshold
 
 **Example:**
 
 ```markdown
-## Search Example
-
-Before implementing authentication:
+Search learnings:
 
-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
+- query: "OAuth authentication"
+- tags: ["security"]
+- limit: 5
 ```
 
-### Tool 3: Get Learning
+**Returns:** Array of matching memories sorted by relevance × importance, with id, title, category, tags, importance, and relevance score.
+
+### Tool 3: Get Learning (ff-learning-get)
 
-**Purpose:** Retrieve full content of a specific memory
+**Purpose:** Retrieve the full content of a specific memory
 
 **When to use:**
 
@@ -249,289 +159,67 @@ Before implementing authentication:
 
 **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:**
+- `memoryId` (string, required): UUID of the memory to retrieve
 
-- At the end of planning sessions to document the plan
-- When creating architecture or migration plans
-- To document research findings as structured plans
+**Returns:** Complete memory object with all fields (id, sessionID, messageID, category, title, body, tags, importance, createdAt, extractedBy).
 
-**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:**
+## File Organization
 
-```markdown
-Create plan using ff-plan-create:
+### Directory Structure
 
-- 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"
+.feature-factory/local-recall/
+├── memories/           # All memory JSON files
+│   ├── {uuid}.json     # Individual memory files
+│   └── ...
+└── processed.json      # Tracks which messages have been processed
 ```
 
-### 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"
+### Memory JSON Schema
+
+Each memory is a JSON file with these fields:
+
+```json
+{
+  "id": "uuid-v4",
+  "sessionID": "ses_xxx",
+  "messageID": "msg_xxx",
+  "category": "pattern|decision|debugging|preference|context|procedure",
+  "title": "Brief descriptive title",
+  "body": "Detailed learning content",
+  "tags": ["keyword1", "keyword2"],
+  "importance": 0.8,
+  "createdAt": 1707900000000,
+  "extractedBy": "session|thinking|explicit"
+}
 ```
 
 ## 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
-```
+**When to capture:** After planning sessions, architectural decisions, risk identification
+**What to capture:** Architecture decisions (decision), risk factors (context), pattern discoveries (pattern)
 
 ### 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
-```
+**When to capture:** After implementing features, overcoming challenges, resolving errors
+**What to capture:** Code patterns (pattern), error resolutions (debugging), integration insights (context)
 
 ### 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
-```
+**When to capture:** After completing reviews, identifying common issues
+**What to capture:** Common issue patterns (pattern), quality insights (context)
 
 ### 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
-```
+**When to capture:** After research, significant findings, technology evaluations
+**What to capture:** Key findings (pattern), technology comparisons (decision), best practices (procedure)
 
 ### 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
-```
+**When to capture:** After audits, vulnerability findings
+**What to capture:** Vulnerability patterns (debugging), security best practices (procedure)
 
 ## Integration with Other Skills
 
@@ -545,318 +233,107 @@ After validating requirements:
 
 - 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
+- **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
+- **Write searchable titles** – Use keywords that future you will search for
+- **Capture failures too** – What didn't work is as valuable as what did
+- **Search before storing** – Avoid duplicate memories
+- **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
+- **Store everything** – Not every small change needs a memory
+- **Use vague titles** – "Fixed bug" is not helpful; "Fixed race condition in auth middleware" is
+- **Store secrets** – Never put credentials or sensitive data in memories
+- **Be too brief** – One-line descriptions lack context
+- **Forget tags** – Untagged memories are hard to find
 
-### 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']
----
+## Additional Tools for Read-Only Agents
 
-## Key Concepts
+Since @planning and @reviewing agents are read-only (cannot write/edit files), the following tools are provided for essential file operations:
 
-### Server Components
+### Tool 4: Create Plan (ff-plan-create)
 
-- Can be async functions
-- Can fetch data directly
-- Run on server only
-- Cannot use useState, useEffect, or browser APIs
+**Purpose:** Create a new implementation plan file in `.feature-factory/plans/`
 
-### Client Components
+**Input parameters:**
 
-- Must use 'use client' directive
-- Cannot be async
-- Use useEffect for data fetching
-- Can use all React hooks and browser APIs
+- `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
 
-### Best Practices
+### Tool 5: Create Agent Context (ff-agent-context-create)
 
-1. **Fetch in Server Components when possible**
-   - Better performance
-   - Reduced client-side JavaScript
-   - Direct database access
+**Purpose:** Create a new agent context file in `.feature-factory/agents/`
 
-2. **Use Client Components for interactivity**
-   - Forms with validation
-   - Real-time updates
-   - Browser-only features
+**Input parameters:**
 
-3. **Pass data as props**
-   - Server Component fetches data
-   - Passes to Client Component as props
-   - Client Component handles interactivity
+- `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
 
-### Code Example
+### Tool 6: Update Agent Context (ff-agent-context-update)
 
-```typescript
-// Server Component (app/page.tsx)
-async function Page() {
-  const data = await fetchData(); // Direct fetch
-  return <ClientComponent initialData={data} />;
-}
+**Purpose:** Update an existing agent context file
 
-// Client Component (components/ClientComponent.tsx)
-'use client';
+**Input parameters:**
 
-function ClientComponent({ initialData }) {
-  const [data, setData] = useState(initialData);
-  // Handle interactivity...
-}
-````
+- `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
 
-````
+## Quick Reference
 
-### Example 3: Procedural Memory
+### Creating a 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
+Store a learning:
 
-## 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
+- title: "Descriptive searchable title"
+- description: "Detailed explanation of what was learned"
+- category: "pattern"
+- tags: ["relevant", "keywords"]
+- importance: 0.8
 ```
 
-## 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
+- [ ] Importance is appropriate (0.0-1.0)
 - [ ] No sensitive data included