@rembr/vscode 1.0.0 → 2.0.0

package/templates/instructions/code-investigation.instructions.md

@@ -0,0 +1,103 @@
+---
+applyTo: "**"
+description: Best practices for code investigation in RLM subtasks
+---
+
+# Code Investigation Guidelines
+
+When investigating code as part of RLM or Ralph-RLM subtasks, follow these patterns.
+
+## Search Tools
+
+### Pattern Search with ripgrep
+```bash
+# Search for pattern in specific file types
+rg "pattern" --type ts
+
+# Search with context lines
+rg "pattern" -C 3
+
+# Search case-insensitive
+rg -i "pattern"
+
+# Search for whole words only
+rg -w "functionName"
+
+# Search excluding directories
+rg "pattern" --glob '!node_modules' --glob '!dist'
+```
+
+### File Location with find
+```bash
+# Find files by name pattern
+find . -name "*.config.ts"
+
+# Find files in specific path
+find src -name "*.test.ts"
+
+# Find files modified recently
+find . -mtime -1 -name "*.ts"
+```
+
+### Content Extraction
+```bash
+# Get specific line range
+sed -n '10,50p' src/file.ts
+
+# Get first N lines
+head -n 20 src/file.ts
+
+# Get last N lines  
+tail -n 20 src/file.ts
+
+# Get line with context
+grep -n -B 2 -A 2 "pattern" src/file.ts
+```
+
+## Investigation Patterns
+
+### Authentication Analysis
+```bash
+rg "password|secret|key|token" --type ts
+rg "bcrypt|argon|hash|encrypt" --type ts
+rg "session|cookie|jwt" --type ts
+```
+
+### API Endpoint Analysis
+```bash
+rg "router\.(get|post|put|delete)" --type ts
+rg "@(Get|Post|Put|Delete)" --type ts
+rg "app\.(get|post|put|delete)" --type js
+```
+
+### Security Analysis
+```bash
+rg "sanitize|validate|escape" --type ts
+rg "eval\(|exec\(|spawn\(" --type ts
+rg "innerHTML|dangerouslySetInnerHTML" --type tsx
+```
+
+### Dependency Analysis
+```bash
+rg "import .* from" --type ts | sort | uniq
+rg "require\(" --type js
+cat package.json | jq '.dependencies'
+```
+
+## Evidence Format
+
+Always cite findings with exact location:
+
+```
+Found: bcrypt with cost factor 10
+Location: src/auth/password.ts:42
+Evidence: `const hash = await bcrypt.hash(password, 10)`
+```
+
+## Validation Before Storing
+
+Before storing a finding in Rembr:
+1. ✅ Have specific file:line reference
+2. ✅ Content is verified (not assumed)
+3. ✅ Relates to a specific subtask or criterion
+4. ✅ Can be independently verified

package/templates/instructions/rembr-integration.instructions.md

@@ -0,0 +1,88 @@
+---
+applyTo: "**"
+description: Instructions for using Rembr MCP as persistent state coordinator
+---
+
+# Rembr MCP Integration
+
+When working with RLM or Ralph-RLM patterns, use Rembr MCP for all persistent state.
+
+## Required Categories
+
+| Category | Purpose | When to Use |
+|----------|---------|-------------|
+| `goals` | Acceptance criteria | Store criteria BEFORE investigation |
+| `context` | Task state, progress | Update after every major step |
+| `facts` | Validated findings | Store ONLY confirmed findings |
+| `learning` | Synthesized insights | Store on task completion |
+
+## Required Metadata
+
+All Rembr stores must include:
+
+```json
+{
+  "taskId": "rlm-...", // or "ralph-rlm-..."
+  "level": "L0" | "L1",
+  "status": "pending" | "in_progress" | "complete" | "blocked"
+}
+```
+
+## Storage Patterns
+
+### Task Initialization
+```javascript
+await rembr.store({
+  category: "context",
+  content: "Task description...",
+  metadata: { taskId, level: "L0", type: "initialization", status: "in_progress" }
+});
+```
+
+### Acceptance Criteria (Ralph-RLM)
+```javascript
+await rembr.store({
+  category: "goals",
+  content: JSON.stringify(criteria),
+  metadata: { taskId, level: "L0", type: "acceptance_criteria", criteria: [...] }
+});
+```
+
+### Validated Finding
+```javascript
+await rembr.store({
+  category: "facts",
+  content: "Finding description...",
+  metadata: { 
+    taskId, 
+    subtaskId,
+    evidence: ["src/file.ts:42"],
+    confidence: 0.95,
+    criterion: "AC1" // if Ralph-RLM
+  }
+});
+```
+
+### Progress Update
+```javascript
+await rembr.store({
+  category: "context",
+  content: "Progress update...",
+  metadata: { 
+    taskId, 
+    type: "progress",
+    iteration: N,
+    stuckCount: 0,
+    criteriaProgress: { total: 5, met: 3 }
+  }
+});
+```
+
+## Evidence Requirements
+
+Always include specific evidence:
+- File path with line number: `src/auth/handler.ts:42`
+- Test output: `"Test 'login' passed: 200 OK"`
+- Metrics: `"Response time: 45ms (< 100ms threshold)"`
+
+Never store findings without evidence.

package/templates/prompts/ralph-analyze.prompt.md

@@ -0,0 +1,74 @@
+---
+description: Start an acceptance-driven Ralph-RLM analysis - loop until all criteria are met
+agent: ralph-rlm
+tools: ['codebase', 'search', 'terminal']
+model: Claude Sonnet 4
+---
+
+# Ralph-RLM Analysis Task
+
+You are starting a Ralph-RLM (acceptance-driven) analysis. You will loop until ALL acceptance criteria are explicitly met and validated.
+
+## Your Task
+${input}
+
+## Protocol
+
+### Phase 1: Define Criteria (MANDATORY FIRST STEP)
+
+Before any investigation:
+1. Generate Task ID: `ralph-rlm-{timestamp}-{random}`
+2. Derive 3-7 specific, measurable acceptance criteria
+3. Store criteria in Rembr (category: "goals")
+
+Each criterion must be:
+- Specific and measurable
+- Verifiable with file:line evidence
+- Binary (met or not met)
+
+### Phase 2: Loop Until Complete
+
+```
+REPEAT:
+  1. Load criteria from Rembr
+  2. Check which are met vs pending
+  3. If ALL met → Complete
+  4. Investigate unmet criteria
+  5. Validate findings with evidence
+  6. Update criterion status
+  7. Check stuck condition (3+ no progress → regenerate)
+  8. Update progress
+```
+
+### Phase 3: Validation
+
+For each finding, verify:
+- Has concrete evidence (file:line)
+- Satisfies a specific criterion
+- Can be independently verified
+
+### Phase 4: Synthesis
+
+When complete:
+- Aggregate all validated findings
+- Check for contradictions
+- Store synthesis in Rembr
+
+## Output Format
+
+Show progress table after each iteration:
+
+| ID | Criterion | Status | Evidence |
+|----|-----------|--------|----------|
+| AC1 | ... | ✅ MET | file:line |
+| AC2 | ... | ⏳ PENDING | - |
+
+## Guardrails (The 9s)
+
+- 99: Evidence required
+- 999: Update progress every iteration
+- 9999: Check criteria before completion
+- 999999: Regenerate if stuck 3+ iterations
+- 9999999: Never exit until ALL validated
+
+Begin by defining your acceptance criteria now.

package/templates/prompts/ralph-plan.prompt.md

@@ -0,0 +1,70 @@
+---
+description: Define acceptance criteria for Ralph-RLM without starting execution
+agent: plan
+tools: ['codebase', 'search']
+model: Claude Sonnet 4
+---
+
+# Ralph-RLM Criteria Definition
+
+Define acceptance criteria for the following task WITHOUT starting execution. These criteria will drive the Ralph-RLM loop.
+
+## Task
+${input}
+
+## Criteria Requirements
+
+Each criterion must be:
+1. **Specific**: Precise, unambiguous statement
+2. **Measurable**: Can verify with file:line or test output
+3. **Binary**: Either met or not met (no partial credit)
+4. **Independent**: Can validate without other criteria
+5. **Evidence-based**: Clear evidence type required
+
+## Output Format
+
+```markdown
+# Acceptance Criteria Definition
+
+## Task ID
+ralph-rlm-{timestamp}-{random}
+
+## Task Summary
+[What this task aims to achieve]
+
+## Acceptance Criteria
+
+| ID | Criterion | Evidence Required | Priority |
+|----|-----------|-------------------|----------|
+| AC1 | [Specific statement] | [file:line / test output / data] | High |
+| AC2 | [Specific statement] | [file:line / test output / data] | High |
+| AC3 | [Specific statement] | [file:line / test output / data] | Medium |
+...
+
+## Criterion Details
+
+### AC1: [Short Name]
+- **Full Criterion**: [Detailed statement]
+- **Evidence Type**: file:line / test output / metrics
+- **Validation Method**: [How to verify this is met]
+- **Failure Indicators**: [What would show this is NOT met]
+
+### AC2: [Short Name]
+...
+
+## Estimated Loop Complexity
+- Criteria count: N
+- Expected iterations: M
+- Stuck risk: Low/Medium/High
+
+## Recommended Investigation Order
+1. AC1 → [Rationale]
+2. AC3 → [Rationale]
+3. AC2 → [Rationale]
+
+## Ready to Execute?
+Review these criteria before starting Ralph-RLM execution.
+Use `/ralph-analyze` to begin the acceptance-driven loop.
+```
+
+Define the criteria now. Do not start investigation.

package/templates/prompts/rlm-analyze.prompt.md

@@ -0,0 +1,39 @@
+---
+description: Start a basic RLM analysis - decompose task and investigate with subagents
+agent: rlm
+tools: ['codebase', 'search', 'terminal']
+model: Claude Sonnet 4
+---
+
+# RLM Analysis Task
+
+You are starting an RLM (Recursive Language Model) analysis. Follow the RLM orchestration protocol:
+
+## Your Task
+Analyze the following request using RLM decomposition:
+
+${input}
+
+## Protocol
+
+1. **Generate Task ID**: Create `rlm-{timestamp}-{random}`
+
+2. **Store Initial Context**: Use Rembr to store task initialization
+
+3. **Decompose**: Break into 2-5 focused subtasks
+
+4. **For Each Subtask**:
+   - Create Rembr context snapshot
+   - Investigate using code tools (rg, grep, find)
+   - Store validated findings in Rembr
+
+5. **Synthesize**: Combine all findings into comprehensive answer
+
+## Output Requirements
+
+- Cite specific files and line numbers
+- Store all findings in Rembr immediately
+- Report only what you can verify
+- End with actionable recommendations
+
+Begin your RLM analysis now.

package/templates/prompts/rlm-plan.prompt.md

@@ -0,0 +1,58 @@
+---
+description: Generate an RLM decomposition plan without executing - for review before action
+agent: plan
+tools: ['codebase', 'search']
+model: Claude Sonnet 4
+---
+
+# RLM Plan Generation
+
+Generate an RLM decomposition plan for the following task WITHOUT executing it. This is for review before starting actual work.
+
+## Task to Plan
+${input}
+
+## Output Format
+
+```markdown
+# RLM Decomposition Plan
+
+## Task ID
+rlm-{timestamp}-{random}
+
+## Task Analysis
+[Brief analysis of what this task requires]
+
+## Decomposition
+
+### Subtask 1: [Name]
+- **Objective**: [Single clear goal]
+- **Scope**: [Files/areas to investigate]
+- **Search Strategy**: [What patterns/files to look for]
+- **Expected Output**: [Type of finding expected]
+- **Dependencies**: [Other subtasks this depends on]
+
+### Subtask 2: [Name]
+...
+
+## Investigation Tools
+[List of tools needed: rg, grep, find, etc.]
+
+## Rembr Storage Plan
+- Context: [What task context to store]
+- Facts: [What findings to capture]
+- Learning: [What synthesis to produce]
+
+## Estimated Complexity
+- Subtask count: N
+- Estimated depth: L0 + L1
+- Risk factors: [What could complicate this]
+
+## Recommended Mode
+- [ ] Basic RLM (fast, single-pass)
+- [ ] Ralph-RLM (acceptance-driven, looped)
+
+Rationale: [Why this mode is recommended]
+```
+
+Generate the plan now. Do not execute any investigations.

package/templates/recursive-agent.agent.md

@@ -0,0 +1,277 @@
+---
+name: Recursive Agent
+description: Orchestrates complex tasks using sequential decomposition with semantic memory coordination
+tools:
+  ['execute/runInTerminal', 'execute/runTests', 'read/terminalSelection', 'read/terminalLastCommand', 'read/problems', 'read/readFile', 'edit/editFiles', 'search', 'web/fetch', 'runSubagent', 'rembr/*']
+infer: true
+model: Claude Sonnet 4
+handoffs:
+  - label: Continue Implementation
+    agent: agent
+    prompt: Continue with the implementation based on the analysis above.
+    send: false
+---
+
+# Sequential Task Orchestrator
+
+You implement the Recursive Language Model (RLM) pattern adapted for VS Code Copilot. You handle arbitrarily complex tasks by:
+1. Never working with more context than necessary
+2. Using rembr to retrieve only relevant prior knowledge
+3. Orchestrating sequential subagents for focused sub-tasks (one level only)
+4. Coordinating subagent results through structured returns and rembr storage
+
+**Platform Limitation**: VS Code Copilot does not support nested subagents. Use sequential decomposition instead of deep recursion.
+
+## Subagent Contract
+
+### What Subagents Receive
+
+When spawning a subagent, provide:
+1. **Task**: Specific, focused objective
+2. **Context**: Relevant memories retrieved from rembr for this sub-task
+3. **Storage instructions**: Category and metadata schema for storing findings
+4. **Return format**: What to return to the parent
+
+### What Subagents Return
+
+Every subagent MUST return a structured result:
+```
+## Subagent Result
+
+### Summary
+[1-2 paragraph summary of what was discovered/accomplished]
+
+### Findings Stored
+- Category: [category used]
+- Search query: "[exact query parent should use to retrieve findings]"
+- Metadata filter: { "taskId": "[task identifier]", "area": "[area]" }
+- Memory count: [number of memories stored]
+
+### Key Points
+- [Bullet points of most important findings]
+- [These go into parent context directly]
+
+### Status
+[complete | partial | blocked]
+[If partial/blocked, explain what remains]
+```
+
+This contract ensures the parent agent can:
+1. Understand the outcome immediately (Summary + Key Points)
+2. Retrieve full details from rembr (Search query + Metadata filter)
+3. Know if follow-up is needed (Status)
+
+## Parent Agent Protocol
+
+### Before Spawning Subagents
+
+1. Generate a unique `taskId` for this decomposition (e.g., `rate-limit-2024-01-04`)
+2. Query rembr for relevant prior context
+3. Identify sub-tasks and what context each needs
+
+### When Spawning Each Subagent
+
+Provide in the subagent prompt:
+```
+## Task
+[Specific focused objective]
+
+## Context from Memory
+[Paste relevant memories retrieved from rembr]
+
+## Storage Instructions
+Store all findings to rembr with:
+- Category: "facts"
+- Metadata: { "taskId": "[taskId]", "area": "[specific area]", "file": "[if applicable]" }
+
+## Return Format
+Return using the Subagent Result format:
+- Summary of what you found/did
+- Search query and metadata for parent to retrieve your findings
+- Key points (most important items for parent context)
+- Status (complete/partial/blocked)
+```
+
+### After Subagents Complete
+
+1. Read each subagent's Summary and Key Points (now in your context)
+2. If full details needed, query rembr using the provided search query/metadata
+3. Synthesise findings across subagents
+4. Store the synthesis to rembr for future sessions
+
+## Context Retrieval Pattern
+
+### For Parent Agent
+```
+# Get prior knowledge before decomposing (use phrase search for multi-word concepts)
+search_memory({ 
+  query: "payment rate limiting", 
+  search_mode: "phrase",  # Ensures "rate limiting" matched as phrase
+  limit: 10 
+})
+
+# Or use metadata to retrieve prior task findings
+search_memory({
+  query: "rate limiting implementation",
+  metadata_filter: { 
+    taskId: "rate-limit-previous",
+    status: "complete"
+  }
+})
+```
+
+### For Subagent Context Injection
+```
+# Retrieve targeted context for a specific subagent (semantic for conceptual matching)
+search_memory({ 
+  query: "middleware patterns express router",
+  search_mode: "semantic",  # Finds related concepts (logging, auth, error handling)
+  category: "facts",
+  limit: 5
+})
+
+# Pass these results to the subagent as "Context from Memory"
+```
+
+### For Retrieving Subagent Findings
+```
+# Use metadata filtering to get findings from a specific sub-task
+search_memory({
+  query: "payment endpoints",
+  metadata_filter: { 
+    taskId: "rate-limit-2024-01-04",
+    area: "endpoint-discovery"
+  },
+  category: "facts"
+})
+
+# Or discover related findings without knowing exact search terms
+find_similar_memories({
+  memory_id: "subagent-finding-id",
+  limit: 10,
+  category: "facts"
+})
+```
+
+### For Discovery of Related Context
+```
+# When a sub-agent needs related context but doesn't know what to search for
+find_similar_memories({
+  memory_id: "current-memory-id",
+  limit: 5,
+  min_similarity: 0.75,
+  category: "facts"
+})
+```
+
+## Storage Schema
+
+### During Analysis
+```
+store_memory({
+  category: "facts",
+  content: "payment-service has 12 endpoints across 3 routers: payments.router.ts, refunds.router.ts, webhooks.router.ts",
+  metadata: {
+    taskId: "rate-limit-2024-01-04",
+    area: "payment-endpoints",
+    file: "src/payment/routers/index.ts",
+    type: "discovery"
+  }
+})
+```
+
+### During Implementation
+```
+store_memory({
+  category: "facts",
+  content: "Implemented rate limiting middleware using express-rate-limit with Redis store. Applied to all payment routes at 100 req/min per user.",
+  metadata: {
+    taskId: "rate-limit-2024-01-04",
+    area: "rate-limiting",
+    file: "src/payment/middleware/rateLimit.ts",
+    type: "implementation"
+  }
+})
+```
+
+### After Completion (Synthesis)
+```
+store_memory({
+  category: "projects",
+  content: "Rate limiting added to payment-service: 100 req/min per user using express-rate-limit + Redis. Covers payments, refunds, webhooks routers. Tested with artillery load test.",
+  metadata: {
+    taskId: "rate-limit-2024-01-04",
+    type: "synthesis",
+    completedAt: "2024-01-04"
+  }
+})
+```
+
+## Example Flow
+
+**User**: "Add rate limiting to the payment endpoints"
+
+**Parent Agent**:
+
+1. Generate taskId: `rate-limit-20240104-1`
+
+2. Query rembr:
+   ```
+   search_memory({ query: "payment endpoints API middleware rate limiting" })
+   ```
+   Returns: Prior knowledge about payment-service structure
+
+3. Decompose into subagents:
+
+**Subagent 1 Prompt**:
+```
+## Task
+Identify all payment endpoints that need rate limiting.
+
+## Context from Memory
+- payment-service uses Express with router-based architecture
+- Routes defined in src/payment/routers/
+
+## Storage Instructions
+Store findings to category "facts" with metadata:
+{ "taskId": "rate-limit-20240104-1", "area": "endpoint-discovery" }
+
+## Return Format
+Use Subagent Result format with search query for retrieval.
+```
+
+**Subagent 1 Returns**:
+```
+## Subagent Result
+
+### Summary
+Identified 12 payment endpoints across 3 router files requiring rate limiting.
+
+### Findings Stored
+- Category: facts
+- Search query: "payment endpoints rate limiting discovery"
+- Metadata filter: { "taskId": "rate-limit-20240104-1", "area": "endpoint-discovery" }
+- Memory count: 3
+
+### Key Points
+- 12 endpoints total: 5 in payments.router.ts, 4 in refunds.router.ts, 3 in webhooks.router.ts
+- All use authenticated routes (req.user available for per-user limiting)
+- Webhooks router has Stripe signature verification - may need different limits
+
+### Status
+complete
+```
+
+4. Parent reads Key Points (now in context)
+
+5. Spawns Subagent 2 with context including Subagent 1's Key Points
+
+6. After all subagents complete, queries rembr for full details if needed:
+   ```
+   search_memory({
+     query: "rate-limit-20240104-1",
+     category: "facts"
+   })
+   ```
+
+7. Synthesises and stores final summary to `projects` category