@vantagesec/socc 0.1.11 → 0.1.13

package/socc-canonical/.agents/soc-copilot/skills/remembering-conversations/MCP-TOOLS.md

@@ -0,0 +1,137 @@
+# Episodic Memory MCP Tools Reference
+
+The episodic-memory plugin exposes two MCP tools for searching and displaying past conversations.
+
+## search
+
+Search your episodic memory of past Claude Code conversations using semantic or text search.
+
+**Tool name:** `mcp__plugin_episodic-memory_episodic-memory__search`
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | `string` or `string[]` | Yes | Search query. String for single-concept search, array of 2-5 strings for multi-concept AND search |
+| `mode` | `"vector"` \| `"text"` \| `"both"` | No | Search mode (default: `"both"`). Only used for single-concept searches |
+| `limit` | `number` | No | Maximum results to return, 1-50 (default: 10) |
+| `after` | `string` | No | Only return conversations after this date (YYYY-MM-DD) |
+| `before` | `string` | No | Only return conversations before this date (YYYY-MM-DD) |
+| `response_format` | `"markdown"` \| `"json"` | No | Output format (default: `"markdown"`) |
+
+### Search Modes
+
+- **`vector`** - Semantic similarity search using embeddings
+- **`text`** - Exact text matching (case-insensitive)
+- **`both`** - Combined semantic + text search (default, recommended)
+
+### Single-Concept Search
+
+```typescript
+{
+  query: "React Router authentication errors",
+  mode: "both",
+  limit: 10
+}
+```
+
+### Multi-Concept Search (AND)
+
+Search for conversations containing ALL concepts:
+
+```typescript
+{
+  query: ["authentication", "React Router", "error handling"],
+  limit: 10
+}
+```
+
+Note: `mode` is ignored for multi-concept searches (always uses vector similarity).
+
+### Date Filtering
+
+```typescript
+{
+  query: "refactoring patterns",
+  after: "2025-09-01",
+  before: "2025-10-01"
+}
+```
+
+### Response Format
+
+#### Markdown (default)
+
+Human-readable format with:
+- Project name and date
+- Conversation summary
+- Matched exchange snippet
+- Similarity score
+- File path and line numbers
+
+#### JSON
+
+Machine-readable format:
+```json
+{
+  "results": [...],
+  "count": 5,
+  "mode": "both"
+}
+```
+
+## read
+
+Display a full conversation from episodic memory as markdown.
+
+**Tool name:** `mcp__plugin_episodic-memory_episodic-memory__read`
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | `string` | Yes | Absolute path to the JSONL conversation file |
+| `startLine` | `number` | No | Starting line number (1-indexed, inclusive) |
+| `endLine` | `number` | No | Ending line number (1-indexed, inclusive) |
+
+### Usage
+
+**Read entire conversation:**
+```typescript
+{
+  path: "/Users/name/.config/superpowers/conversation-archive/project/uuid.jsonl"
+}
+```
+
+**Read specific range:**
+```typescript
+{
+  path: "/Users/name/.config/superpowers/conversation-archive/project/uuid.jsonl",
+  startLine: 100,
+  endLine: 200
+}
+```
+
+### Response Format
+
+Markdown-formatted conversation with:
+- Message roles (user/assistant)
+- Content (including tool uses and results)
+- Line numbers for reference
+
+## Error Handling
+
+Both tools return errors as text content with `isError: true`:
+- Invalid parameters (validation errors)
+- File not found
+- Date parsing errors
+- Search failures
+
+## Performance Notes
+
+- **Search** is fast (< 100ms typically)
+- **Show** can be slow for large conversations
+  - Use `startLine`/`endLine` to paginate
+  - Conversations can be 1000+ lines
+- Vector search uses sqlite-vec with cached embeddings
+- Text search uses SQLite FTS5 full-text index

package/socc-canonical/.agents/soc-copilot/skills/remembering-conversations/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: remembering-conversations
+description: Use when user asks 'how should I...' or 'what's the best approach...' after exploring code, OR when you've tried to solve something and are stuck, OR for unfamiliar workflows, OR when user references past work. Searches conversation history.
+---
+
+# Remembering Conversations
+
+**Core principle:** Search before reinventing. Searching costs nothing; reinventing or repeating mistakes costs everything.
+
+## Mandatory: Use the Search Agent
+
+**YOU MUST dispatch the search-conversations agent for any historical search.**
+
+Announce: "Dispatching search agent to find [topic]."
+
+Then use the Task tool with `subagent_type: "search-conversations"`:
+
+```
+Task tool:
+  description: "Search past conversations for [topic]"
+  prompt: "Search for [specific query or topic]. Focus on [what you're looking for - e.g., decisions, patterns, gotchas, code examples]."
+  subagent_type: "search-conversations"
+```
+
+The agent will:
+1. Search with the `search` tool
+2. Read top 2-5 results with the `show` tool
+3. Synthesize findings (200-1000 words)
+4. Return actionable insights + sources
+
+**Saves 50-100x context vs. loading raw conversations.**
+
+## When to Use
+
+You often get value out of consulting your episodic memory once you understand what you're being asked. Search memory in these situations:
+
+**After understanding the task:**
+- User asks "how should I..." or "what's the best approach..."
+- You've explored current codebase and need to make architectural decisions
+- User asks for implementation approach after describing what they want
+
+**When you're stuck:**
+- You've investigated a problem and can't find the solution
+- Facing a complex problem without obvious solution in current code
+- Need to follow an unfamiliar workflow or process
+
+**When historical signals are present:**
+- User says "last time", "before", "we discussed", "you implemented"
+- User asks "why did we...", "what was the reason..."
+- User says "do you remember...", "what do we know about..."
+
+**Don't search first:**
+- For current codebase structure (use Grep/Read to explore first)
+- For info in current conversation
+- Before understanding what you're being asked to do
+
+## Direct Tool Access (Discouraged)
+
+You CAN use MCP tools directly, but DON'T:
+- `mcp__plugin_episodic-memory_episodic-memory__search`
+- `mcp__plugin_episodic-memory_episodic-memory__show`
+
+Using these directly wastes your context window. Always dispatch the agent instead.
+
+See MCP-TOOLS.md for complete API reference if needed for advanced usage.

package/socc-canonical/.agents/soc-copilot/skills/sequential-thinking/README.md

@@ -0,0 +1,118 @@
+# Sequential Thinking Skill
+
+Agent skill for systematic problem-solving through iterative reasoning with revision and branching capabilities.
+
+## What This Skill Does
+
+Enables Claude to break down complex problems into sequential thought steps, revise conclusions when needed, and explore alternative solution paths—all while maintaining context throughout the reasoning process.
+
+## Installation
+
+This skill requires the Sequential Thinking MCP server to be installed and configured in your Claude Desktop or Claude Code environment.
+
+### Step 1: Install MCP Server
+
+Choose one of the following methods:
+
+#### NPX (Recommended)
+
+Add to your `claude_desktop_config.json` or MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}
+```
+
+#### Docker
+
+```json
+{
+  "mcpServers": {
+    "sequentialthinking": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "mcp/sequentialthinking"]
+    }
+  }
+}
+```
+
+### Step 2: Add Skill to Project
+
+Copy this skill folder to your project's `.claude/skills/` directory:
+
+```bash
+cp -r sequential-thinking /path/to/your/project/.claude/skills/
+```
+
+### Step 3: Verify Installation
+
+Restart Claude and check that the `mcp__reasoning__sequentialthinking` tool is available.
+
+## Usage
+
+Once installed, Claude will automatically use this skill when:
+- Facing complex multi-step problems
+- Needing to revise earlier conclusions
+- Exploring alternative solution approaches
+- Working through uncertain or evolving scopes
+
+You can also explicitly request it:
+```
+"Let's think through this step-by-step using sequential thinking"
+```
+
+## Configuration
+
+### Disable Logging (Optional)
+
+To suppress thought information logging, set environment variable:
+
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "env": {
+        "DISABLE_THOUGHT_LOGGING": "true"
+      }
+    }
+  }
+}
+```
+
+## Skill Structure
+
+```
+sequential-thinking/
+├── SKILL.md              # Main skill definition
+├── README.md             # This file
+└── references/
+    ├── advanced.md       # Revision and branching patterns
+    └── examples.md       # Real-world use cases
+```
+
+## When Claude Uses This Skill
+
+The skill activates for:
+- **Complex analysis**: Breaking down multi-faceted problems
+- **Design decisions**: Exploring and comparing alternatives
+- **Debugging**: Systematic investigation with course correction
+- **Planning**: Multi-stage project planning with evolving scope
+- **Architecture**: Evaluating trade-offs across approaches
+
+## Learn More
+
+- [MCP Sequential Thinking Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview.md)
+
+## License
+
+MIT

package/socc-canonical/.agents/soc-copilot/skills/sequential-thinking/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: sequential-thinking
+description: Use when complex problems require systematic step-by-step reasoning with ability to revise thoughts, branch into alternative approaches, or dynamically adjust scope. Ideal for multi-stage analysis, design planning, problem decomposition, or tasks with initially unclear scope.
+license: MIT
+---
+
+# Sequential Thinking
+
+Enables structured problem-solving through iterative reasoning with revision and branching capabilities.
+
+## Core Capabilities
+
+- **Iterative reasoning**: Break complex problems into sequential thought steps
+- **Dynamic scope**: Adjust total thought count as understanding evolves
+- **Revision tracking**: Reconsider and modify previous conclusions
+- **Branch exploration**: Explore alternative reasoning paths from any point
+- **Maintained context**: Keep track of reasoning chain throughout analysis
+
+## When to Use
+
+Use `mcp__reasoning__sequentialthinking` when:
+- Problem requires multiple interconnected reasoning steps
+- Initial scope or approach is uncertain
+- Need to filter through complexity to find core issues
+- May need to backtrack or revise earlier conclusions
+- Want to explore alternative solution paths
+
+**Don't use for**: Simple queries, direct facts, or single-step tasks.
+
+## Basic Usage
+
+The MCP tool `mcp__reasoning__sequentialthinking` accepts these parameters:
+
+### Required Parameters
+
+- `thought` (string): Current reasoning step
+- `nextThoughtNeeded` (boolean): Whether more reasoning is needed
+- `thoughtNumber` (integer): Current step number (starts at 1)
+- `totalThoughts` (integer): Estimated total steps needed
+
+### Optional Parameters
+
+- `isRevision` (boolean): Indicates this revises previous thinking
+- `revisesThought` (integer): Which thought number is being reconsidered
+- `branchFromThought` (integer): Thought number to branch from
+- `branchId` (string): Identifier for this reasoning branch
+
+## Workflow Pattern
+
+```
+1. Start with initial thought (thoughtNumber: 1)
+2. For each step:
+   - Express current reasoning in `thought`
+   - Estimate remaining work via `totalThoughts` (adjust dynamically)
+   - Set `nextThoughtNeeded: true` to continue
+3. When reaching conclusion, set `nextThoughtNeeded: false`
+```
+
+## Simple Example
+
+```typescript
+// First thought
+{
+  thought: "Problem involves optimizing database queries. Need to identify bottlenecks first.",
+  thoughtNumber: 1,
+  totalThoughts: 5,
+  nextThoughtNeeded: true
+}
+
+// Second thought
+{
+  thought: "Analyzing query patterns reveals N+1 problem in user fetches.",
+  thoughtNumber: 2,
+  totalThoughts: 6, // Adjusted scope
+  nextThoughtNeeded: true
+}
+
+// ... continue until done
+```
+
+## Advanced Features
+
+For revision patterns, branching strategies, and complex workflows, see:
+- [Advanced Usage](references/advanced.md) - Revision and branching patterns
+- [Examples](references/examples.md) - Real-world use cases
+
+## Tips
+
+- Start with rough estimate for `totalThoughts`, refine as you progress
+- Use revision when assumptions prove incorrect
+- Branch when multiple approaches seem viable
+- Express uncertainty explicitly in thoughts
+- Adjust scope freely - accuracy matters less than progress visibility

package/socc-canonical/.agents/soc-copilot/skills/sequential-thinking/references/advanced.md

@@ -0,0 +1,122 @@
+# Advanced Usage: Revision and Branching
+
+## Revising Previous Thoughts
+
+When a thought proves incorrect or incomplete, use revision to correct the reasoning chain:
+
+```typescript
+{
+  thought: "Actually, the N+1 problem isn't the bottleneck—profiling shows the issue is missing indexes on join columns.",
+  thoughtNumber: 5,
+  totalThoughts: 7,
+  isRevision: true,
+  revisesThought: 2, // References thought #2
+  nextThoughtNeeded: true
+}
+```
+
+**When to revise**:
+- New evidence contradicts earlier conclusions
+- Assumptions prove incorrect
+- Scope was misunderstood
+- Need to correct factual errors
+
+## Branching Into Alternatives
+
+Explore different solution paths by branching from a specific thought:
+
+```typescript
+// Main path (thoughts 1-3)
+{
+  thought: "Could optimize with caching or database indexes.",
+  thoughtNumber: 3,
+  totalThoughts: 6,
+  nextThoughtNeeded: true
+}
+
+// Branch A: Explore caching
+{
+  thought: "If we implement Redis caching, we'd need to handle cache invalidation.",
+  thoughtNumber: 4,
+  totalThoughts: 6,
+  branchFromThought: 3,
+  branchId: "caching-approach",
+  nextThoughtNeeded: true
+}
+
+// Branch B: Explore indexing (alternative from thought 3)
+{
+  thought: "Adding composite index would avoid query overhead entirely.",
+  thoughtNumber: 4,
+  totalThoughts: 5,
+  branchFromThought: 3,
+  branchId: "indexing-approach",
+  nextThoughtNeeded: true
+}
+```
+
+**When to branch**:
+- Multiple viable approaches exist
+- Need to compare trade-offs
+- Exploring contingencies
+- Testing hypotheses in parallel
+
+## Combining Revision and Branching
+
+```typescript
+// Original branch proves problematic
+{
+  thought: "The caching approach has too many edge cases for our timeline.",
+  thoughtNumber: 6,
+  totalThoughts: 8,
+  branchId: "caching-approach",
+  isRevision: true,
+  revisesThought: 4,
+  nextThoughtNeeded: true
+}
+
+// Return to indexing branch
+{
+  thought: "Returning to index optimization—this approach is more reliable.",
+  thoughtNumber: 7,
+  totalThoughts: 9,
+  branchId: "indexing-approach",
+  nextThoughtNeeded: true
+}
+```
+
+## Dynamic Scope Adjustment
+
+Freely adjust `totalThoughts` as understanding evolves:
+
+```typescript
+// Initial estimate
+{ thoughtNumber: 1, totalThoughts: 5, ... }
+
+// Complexity increases
+{ thoughtNumber: 3, totalThoughts: 8, ... }
+
+// Actually simpler than expected
+{ thoughtNumber: 5, totalThoughts: 6, ... }
+```
+
+**Purpose**: Provide progress visibility, not strict planning. The estimate guides pacing but should adapt to reality.
+
+## Session Management
+
+Each reasoning session maintains its own context. The tool tracks:
+- All thoughts in sequence
+- Revision relationships
+- Branch hierarchies
+- Current state
+
+You don't need to manually manage state—focus on expressing reasoning clearly.
+
+## Best Practices
+
+1. **Express uncertainty**: "This might be...", "Uncertain if...", "Need to verify..."
+2. **Show reasoning**: Not just conclusions, but how you arrived there
+3. **Revise freely**: Correcting course is expected and valuable
+4. **Branch decisively**: When exploring alternatives, commit to exploring each fully
+5. **Adjust scope**: Don't lock into initial estimates
+6. **Maintain clarity**: Each thought should be self-contained enough to understand in isolation