opencode-sdlc-plugin 0.2.1 → 0.3.2

package/commands/sdlc-recall.md

@@ -1,18 +1,213 @@
 ---
-description: Retrieve knowledge from memento MCP
+description: Search and retrieve memories from persistent storage
 ---
 
-# SDLC Recall
+# SDLC Recall - Memory Retrieval
+
+Search and retrieve relevant context from persistent memory. Use this command before starting work to check for existing knowledge that might help.
 
 ## Usage
 
+Call **sdlc_recall** to search memories:
+
+```
+sdlc_recall({
+  query: "authentication"
+})
+```
+
+## When to Recall
+
+Use this command at the start of work to:
+
+### Before Implementation
+- Check for existing patterns in this area
+- Find conventions you should follow
+- Recall domain rules that apply
+
+### During Debugging
+- Search for similar issues solved before
+- Find workarounds for known problems
+- Recall environment-specific quirks
+
+### Before Research
+- Check if you've already researched this topic
+- Find related notes that might help
+- Avoid duplicating previous work
+
+### When Returning to Code
+- Recall context from previous sessions
+- Find notes about why things were done a certain way
+- Refresh memory on complex systems
+
+## Query Examples
+
+### Simple Keyword Search
+
+```
+sdlc_recall({ query: "authentication" })
+sdlc_recall({ query: "rate limit" })
+sdlc_recall({ query: "postgres connection" })
+```
+
+### Key Path Search
+
+```
+sdlc_recall({ query: "auth/jwt" })
+sdlc_recall({ query: "api/stripe" })
+sdlc_recall({ query: "domain/orders" })
+```
+
+### Filtered by Tags
+
+```
+sdlc_recall({
+  query: "error handling",
+  tags: ["api"]
+})
+
+sdlc_recall({
+  query: "performance",
+  tags: ["database", "optimization"]
+})
+```
+
+### Project-Specific Search
+
+```
+sdlc_recall({
+  query: "conventions",
+  projectOnly: true
+})
+```
+
+### Limited Results
+
+```
+sdlc_recall({
+  query: "testing",
+  limit: 5
+})
+```
+
+## Response Format
+
+Results include:
+- **key**: The memory's unique identifier
+- **content**: The stored information
+- **tags**: Associated tags
+- **createdAt**: When it was first stored
+- **updatedAt**: When it was last modified
+- **projectDir**: Which project it came from (if stored locally)
+
+## Search Behavior
+
+The search matches against:
+1. **Memory keys** (highest priority)
+2. **Content text** (semantic matching)
+3. **Tags** (when specified)
+
+Results are ranked by relevance and returned in order.
+
+## Workflow Integration
+
+### Start of Session Pattern
+
+```
+# Before starting any new work
+sdlc_recall({ query: "<area-you're-working-on>" })
+
+# Check the results
+# If relevant memories exist, use them as context
+# If not, proceed and consider remembering insights later
+```
+
+### Debug Workflow
+
+```
+# When hitting an issue
+sdlc_recall({ query: "<error-message-or-symptom>", tags: ["bug-fix"] })
+
+# Check if this was solved before
+# If yes, use the solution
+# If no, solve it and remember the solution
+```
+
+### Pre-Implementation Checklist
+
+```
+# Before implementing a feature
+sdlc_recall({ query: "<feature-area>", tags: ["pattern", "convention"] })
+
+# Learn from previous patterns
+# Follow established conventions
+# Avoid reinventing solutions
+```
+
+## Memory Sources
+
+When **Memento MCP** is enabled:
+- Searches across all OpenCode projects
+- Shared knowledge base
+- Synchronized memories
+
+When using local storage:
+- Searches `~/.opencode/sdlc-memory.json`
+- Per-machine memories
+- Can filter by project with `projectOnly: true`
+
+## Best Practices
+
+1. **Search Before Starting**: Always check for relevant memories
+2. **Use Multiple Queries**: Try different keywords if first search fails
+3. **Filter When Appropriate**: Use tags to narrow down results
+4. **Read Carefully**: Memories might be outdated - verify applicability
+5. **Update If Needed**: If a memory is out of date, update it with `/sdlc:remember`
+
+## Examples
+
+### Finding Authentication Patterns
+
+```
+sdlc_recall({
+  query: "auth",
+  tags: ["pattern"]
+})
+```
+
+Results might include:
+- `auth/jwt-refresh-pattern` - JWT token refresh strategy
+- `auth/oauth/google-flow` - Google OAuth implementation
+- `auth/session/management` - Session handling patterns
+
+### Finding Bug Fix History
+
 ```
-/sdlc-recall <query>
+sdlc_recall({
+  query: "connection pool",
+  tags: ["bug-fix", "database"]
+})
 ```
 
-## Instructions
+Results might include:
+- `database/postgres/connection-pool` - Pool exhaustion fix
+- `database/connection/timeout` - Timeout configuration
+
+### Finding Domain Rules
+
+```
+sdlc_recall({
+  query: "order cancellation",
+  tags: ["domain", "business-rules"]
+})
+```
+
+Results might include:
+- `domain/orders/cancellation` - Cancellation policy rules
+- `domain/orders/refunds` - Refund processing rules
+
+## Related Commands
 
-- Use `mcp__memento__semantic_search` with the query.
-- Open relevant nodes with `mcp__memento__open_nodes`.
-- Summarize key observations and related entities.
-- If no results, suggest alternate search terms.
+- `/sdlc:remember` - Store new memories
+- `/sdlc-dev` - Implementation workflow (recall first)
+- `/sdlc-debug` - Debugging workflow (recall for past solutions)

package/commands/sdlc-remember.md

@@ -1,19 +1,136 @@
 ---
-description: Store knowledge in memento MCP
+description: Store discoveries and insights to persistent memory
 ---
 
-# SDLC Remember
+# SDLC Remember - Persistent Memory Storage
+
+Store context, discoveries, or insights to persistent memory for future sessions. This command helps you save important information that should persist across sessions.
 
 ## Usage
 
+Call **sdlc_remember** to store a memory:
+
 ```
-/sdlc-remember <what>
+sdlc_remember({
+  key: "auth/jwt-refresh-pattern",
+  content: "JWT tokens in this project use sliding window refresh. When a token is within 5 minutes of expiry, the client automatically requests a new token. The refresh endpoint is POST /api/auth/refresh with the current token in the Authorization header.",
+  tags: ["auth", "jwt", "api"]
+})
 ```
 
-## Instructions
+## When to Remember
+
+Use this command to store:
+
+### Project Conventions
+- Naming patterns discovered during development
+- File organization conventions
+- Code style preferences not in linting rules
+
+### Debugging Insights
+- Solutions to tricky bugs you solved
+- Environment-specific quirks
+- Workarounds for known issues
+
+### Domain Knowledge
+- Business rules learned during implementation
+- Domain terminology and definitions
+- Edge cases and their handling
+
+### Technical Decisions
+- Architecture rationale not in ADRs
+- Why certain approaches were chosen
+- Trade-offs made and their reasons
+
+### API Patterns
+- External API quirks and behaviors
+- Rate limits and retry strategies
+- Authentication flows
+
+## Key Naming Conventions
+
+Use slash-separated paths for organization:
+
+```
+project/component/topic
+
+Examples:
+- auth/oauth/google-flow
+- api/errors/retry-strategy
+- database/migrations/conventions
+- testing/fixtures/user-factory
+- deployment/env/staging-quirks
+```
+
+## Tags
+
+Tags help filter and find related memories:
+
+```
+sdlc_remember({
+  key: "api/rate-limits",
+  content: "GitHub API has a 5000 requests/hour limit. Use conditional requests with ETag headers to reduce consumption.",
+  tags: ["api", "github", "rate-limit", "optimization"]
+})
+```
+
+Common tag categories:
+- **Component**: `auth`, `api`, `database`, `frontend`, `testing`
+- **Type**: `bug-fix`, `pattern`, `convention`, `gotcha`
+- **Priority**: `critical`, `important`, `nice-to-know`
+
+## Examples
+
+### Storing a Bug Fix Insight
+
+```
+sdlc_remember({
+  key: "database/postgres/connection-pool",
+  content: "Connection pool exhaustion occurs under high load because the default pool size of 10 is too small. Increased to 25 with max_overflow=10. Also added connection recycling every 30 minutes to prevent stale connections.",
+  tags: ["database", "postgres", "performance", "bug-fix"]
+})
+```
+
+### Storing a Domain Rule
+
+```
+sdlc_remember({
+  key: "domain/orders/cancellation",
+  content: "Orders can only be cancelled within 24 hours of placement AND before shipping status is 'picked'. The OrderCancellationPolicy service handles this validation. Edge case: orders with 'priority shipping' have a 2-hour window instead.",
+  tags: ["domain", "orders", "business-rules"]
+})
+```
+
+### Storing an API Pattern
+
+```
+sdlc_remember({
+  key: "api/stripe/webhook-verification",
+  content: "Stripe webhooks must be verified using the raw body, not parsed JSON. The express.raw() middleware must be applied BEFORE any JSON body parser for the /webhooks/stripe route. Verification uses the Stripe-Signature header.",
+  tags: ["api", "stripe", "webhooks", "security"]
+})
+```
+
+## Memory Storage
+
+When **Memento MCP** is enabled in your configuration, memories sync across all OpenCode projects, enabling cross-project knowledge sharing.
+
+Otherwise, memories are stored locally in:
+```
+~/.opencode/sdlc-memory.json
+```
+
+## Best Practices
+
+1. **Be Specific**: Include enough context that future-you will understand
+2. **Use Consistent Keys**: Follow the same naming pattern across memories
+3. **Tag Generously**: More tags means easier discovery later
+4. **Update When Needed**: The same key updates the existing memory
+5. **Include Examples**: Code snippets and examples are valuable
+6. **Document "Why"**: Explain the reasoning, not just the facts
+
+## Related Commands
 
-- Search with `mcp__memento__semantic_search` before creating new entities.
-- Choose entity type: debugging_insight, user_preference, project, design_pattern, tool_discovery, domain_concept, feature_implementation, architecture_decision.
-- Include observations with date and scope.
-- Create relationships where possible.
-- Return a confirmation summary.
+- `/sdlc:recall` - Search and retrieve stored memories
+- `/sdlc-debug` - May suggest remembering debugging insights
+- `/sdlc-research` - May suggest remembering research findings

package/commands/sdlc-research.md

@@ -0,0 +1,343 @@
+---
+description: Research patterns, implementations, or documentation using Librarian
+---
+
+# SDLC Research - Librarian-Powered Research
+
+## Git Operations Policy
+
+**⚠️ AUTOMATIC GIT OPERATIONS ARE PROHIBITED**
+
+You must NOT perform any git operations automatically:
+- ❌ Do NOT run `git commit` to save changes
+- ❌ Do NOT run `git push` to push to remote
+- ❌ Do NOT run `git checkout -b` or `git branch` to create branches
+- ❌ Do NOT run `git merge`, `git rebase`, or `git cherry-pick`
+- ❌ Do NOT run `gh pr create` or other GitHub CLI operations
+
+**Git operations are ONLY permitted if the user explicitly requests them.**
+
+This command focuses on research and should rarely involve git operations. If you believe git operations are needed, ASK the user first.
+
+---
+
+Use Librarian, the research specialist, to find patterns, examples, and documentation from multiple sources.
+
+**You are Sisyphus, the orchestrator.** You will coordinate Librarian's research capabilities with Explore for comprehensive information gathering.
+
+## When to Use This Command
+
+- Learning how to use an unfamiliar library or framework
+- Finding implementation patterns for a specific use case
+- Looking up official documentation and best practices
+- Understanding how similar problems are solved in open source
+- Researching before implementing a complex feature
+
+## Step 1: Define Your Research Goals
+
+### 1.1 Load Story Context (if researching for a story)
+
+If this research is for an implementation task:
+
+```
+sdlc_get_story()
+```
+
+This provides:
+- Story requirements (what you need to build)
+- Architecture patterns (project conventions to follow)
+- Technology constraints (what frameworks/libraries to use)
+
+### 1.2 Clarify What You Need
+
+Be specific about your research goals:
+
+**Good research questions:**
+- "How do I implement JWT authentication in Express.js with refresh tokens?"
+- "What's the recommended way to handle form validation in React Hook Form?"
+- "How should I structure a GraphQL resolver for nested relationships?"
+
+**Vague research questions (too broad):**
+- "How do I use React?" (too general)
+- "What's a good database?" (no context)
+- "Help me with authentication" (no specifics)
+
+## Step 2: Multi-Source Research
+
+### 2.1 Internal Codebase Research (Explore)
+
+**First**, check what already exists in your codebase using **@explore**:
+
+```
+@explore I need to research existing patterns for {feature/technology}.
+
+Please find:
+1. Existing implementations of {similar functionality}
+2. How {technology/pattern} is currently used in this project
+3. Any established conventions or helpers for this use case
+4. Related tests that show expected behavior
+
+Return file paths with brief descriptions of what you found.
+```
+
+**Why start with Explore:**
+- Discover existing patterns to follow
+- Avoid reinventing what already exists
+- Understand project-specific conventions
+- Find code you can extend or reference
+
+### 2.2 External Research (Librarian)
+
+**Then**, use **@librarian** for external knowledge:
+
+```
+@librarian I need to research {topic} for my implementation.
+
+## Context
+
+**What I'm Building:**
+{brief description of feature}
+
+**Technology Stack:**
+{relevant frameworks, libraries, versions}
+
+**Project Constraints:**
+{any architectural constraints from sdlc_get_story or project knowledge}
+
+**What Explore Found:**
+{brief summary of internal patterns, if any}
+
+## Research Questions
+
+1. **Best Practices:** What are the recommended patterns for {specific thing}?
+2. **Official Documentation:** What does the official {library} documentation say about {specific API/feature}?
+3. **Common Pitfalls:** What mistakes do developers commonly make with {technology}?
+4. **Examples:** How have other production projects implemented {similar feature}?
+
+## Desired Output
+
+Please provide:
+1. **Summary** - Key findings in 2-3 paragraphs
+2. **Code Examples** - Concrete implementation examples
+3. **Recommendations** - What approach I should take given my constraints
+4. **Sources** - Links to documentation and references for further reading
+```
+
+### 2.3 Parallel Research (Optional)
+
+For comprehensive research, run **multiple Librarian queries in parallel**:
+
+```
+# Background task 1: Official documentation
+@librarian Research official {library} documentation for {specific feature}.
+Focus on API reference and official examples.
+
+# Background task 2: GitHub examples
+@librarian Search GitHub for production implementations of {feature}.
+Focus on well-maintained repos with similar tech stack.
+
+# Background task 3: Best practices
+@librarian Find articles and guides about best practices for {pattern}.
+Focus on recent content (2024+) and authoritative sources.
+```
+
+## Step 3: Research by Use Case
+
+### Use Case A: Learning a New Library
+
+```
+@librarian I need to learn how to use {library} for {specific purpose}.
+
+**My Goal:** {what you want to accomplish}
+**My Stack:** {your project's relevant technologies}
+**My Experience:** {what you already know about similar tools}
+
+Please research:
+1. **Getting Started** - How to set up and configure {library}
+2. **Core Concepts** - Key abstractions and patterns to understand
+3. **API Reference** - Main APIs I'll need for {specific purpose}
+4. **Examples** - Code examples for my use case
+5. **Gotchas** - Common mistakes and how to avoid them
+```
+
+### Use Case B: Design Pattern Research
+
+```
+@librarian I need to research the best pattern for {specific problem}.
+
+**Problem:** {describe the problem you're solving}
+**Constraints:** {technical constraints, performance requirements, etc.}
+**Options Considered:** {patterns you're aware of}
+
+Please research:
+1. **Pattern Comparison** - Compare {pattern A} vs {pattern B} for my use case
+2. **Trade-offs** - Pros and cons of each approach
+3. **Real-World Usage** - How production codebases handle this
+4. **Recommendation** - Which pattern fits my constraints best
+```
+
+### Use Case C: Troubleshooting Research
+
+```
+@librarian I'm encountering {issue} with {technology} and need to understand why.
+
+**The Issue:** {describe what's happening}
+**Error Message:** {if applicable}
+**What I've Tried:** {previous attempts}
+
+Please research:
+1. **Common Causes** - Why does this issue typically occur?
+2. **Solutions** - How have others solved this?
+3. **Root Cause** - What's the underlying reason for this behavior?
+4. **Prevention** - How to avoid this in the future?
+```
+
+### Use Case D: Architecture Research
+
+```
+@librarian I need to make an architectural decision about {topic}.
+
+**Context:** {what you're building}
+**Scale:** {expected load, data volume, team size}
+**Constraints:** {technical, business, or timeline constraints}
+
+Please research:
+1. **Industry Standards** - How do major companies handle this?
+2. **Pattern Options** - What architectural patterns apply?
+3. **Trade-off Analysis** - Pros/cons of each approach
+4. **Case Studies** - Real examples of each approach in production
+```
+
+## Step 4: Synthesize and Apply
+
+### 4.1 Combine Internal + External Findings
+
+After receiving research results:
+
+```markdown
+## Research Summary for {topic}
+
+### Internal Patterns (from Explore)
+- {pattern 1 found in codebase}
+- {pattern 2 found in codebase}
+- {existing code to reference}
+
+### External Best Practices (from Librarian)
+- {best practice 1}
+- {best practice 2}
+- {recommended approach}
+
+### Reconciliation
+- **Follow:** {internal pattern if it aligns with best practices}
+- **Adapt:** {external pattern to fit project conventions}
+- **Decision:** {final approach to use}
+```
+
+### 4.2 Validate with Oracle (if needed)
+
+For complex architectural decisions, consult **@oracle** to validate:
+
+```
+@oracle I've researched {topic} and want to validate my approach.
+
+**Research Findings:**
+{summary from Librarian}
+
+**Proposed Approach:**
+{what you plan to do}
+
+**Questions:**
+1. Does this approach fit our architecture?
+2. Are there any risks I'm missing?
+3. Is this the right trade-off for our use case?
+```
+
+### 4.3 Apply to Implementation
+
+Use your research to guide implementation:
+
+- Follow patterns found in the codebase (consistency)
+- Apply best practices from documentation
+- Avoid common pitfalls identified in research
+- Reference the examples found for similar use cases
+
+## Librarian's Research Sources
+
+Librarian has access to multiple research tools:
+
+| Source | Tool | Best For |
+|--------|------|----------|
+| **Official Docs** | context7 MCP | API references, official guides |
+| **Web Search** | websearch_exa MCP | Tutorials, blog posts, articles |
+| **GitHub** | grep.app MCP | Production code examples |
+| **Codebase** | Internal tools | Project-specific patterns |
+
+## Research Workflow Summary
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              1. DEFINE RESEARCH GOALS                    │
+│  - Load story context (if applicable)                   │
+│  - Clarify specific questions                           │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│            2. INTERNAL RESEARCH (@explore)               │
+│  - Find existing patterns in codebase                   │
+│  - Understand project conventions                       │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│           3. EXTERNAL RESEARCH (@librarian)              │
+│  - Official documentation (context7)                    │
+│  - Web articles and tutorials (exa)                     │
+│  - GitHub examples (grep.app)                           │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│              4. SYNTHESIZE FINDINGS                      │
+│  - Combine internal + external knowledge                │
+│  - Reconcile differences                                │
+│  - Validate with Oracle (if architectural)              │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│             5. APPLY TO IMPLEMENTATION                   │
+│  - Follow established patterns                          │
+│  - Apply best practices                                 │
+│  - Reference examples                                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Tips for Effective Research
+
+### Be Specific
+- "How to validate email in Zod" beats "how to use Zod"
+- Include version numbers when relevant
+- Mention your constraints
+
+### Use Multiple Sources
+- Start with internal codebase (Explore)
+- Then external documentation (Librarian)
+- Cross-reference multiple sources
+
+### Time-Box Research
+- Set a goal for what you need to learn
+- Don't over-research - get enough to start
+- You can always research more if needed
+
+### Document Findings
+- Save useful patterns for future reference
+- Note sources for deeper reading later
+- Share findings with team (if applicable)
+
+## Cost Awareness
+
+- **@explore** is cheap/free - use liberally for codebase searches
+- **@librarian** costs tokens - be specific with queries
+- **Parallel research** is efficient - batch related queries
+- **@oracle** is expensive - only for validating complex decisions