specmem-hardwicksoftware 3.5.99

package/commands/specmem-agents.md

@@ -0,0 +1,412 @@
+# SpecMem Agents - User-Configurable Agent Deployment
+
+Configure exactly which agents get deployed and with what settings.
+
+## COMMAND PARSING
+
+- If NO args, "help", "--help", "-h" → Show HELP below
+- If `list` → List all available agent types with descriptions
+- If `config` → Show current configuration
+- If `set <type> <setting> <value>` → Configure agent settings
+- If `defaults` → Reset to default configuration
+- If `deploy <type> <prompt>` → Deploy with specific type
+- If `interactive` or `-i` → Interactive agent selector
+
+## INPUT VALIDATION
+
+Extract everything after `/specmem-agents`:
+
+```javascript
+const args = "$ARGUMENTS".trim();
+
+if (!args || args === "help" || args === "--help" || args === "-h") {
+  // Show HELP OUTPUT below
+  return;
+}
+
+if (args === "list") {
+  // Execute LIST action
+  return;
+}
+
+if (args === "config") {
+  // Execute CONFIG action
+  return;
+}
+
+if (args === "defaults") {
+  // Execute DEFAULTS action
+  return;
+}
+
+if (args.startsWith("set ")) {
+  // Parse: set <target> <setting> <value>
+  const parts = args.slice(4).trim().split(/\s+/);
+  if (parts.length < 3) {
+    console.log("ERROR: set requires 3 arguments: <target> <setting> <value>");
+    console.log("Example: /specmem-agents set default model opus");
+    return;
+  }
+  // Execute SET action
+  return;
+}
+
+if (args.startsWith("deploy ")) {
+  // Parse: deploy <type> <prompt>
+  const match = args.match(/^deploy\s+(\S+)\s+(.+)$/);
+  if (!match) {
+    console.log("ERROR: deploy requires <type> and <prompt>");
+    console.log("Example: /specmem-agents deploy Explore \"find auth code\"");
+    return;
+  }
+  // Execute DEPLOY action
+  return;
+}
+
+if (args === "interactive" || args === "-i") {
+  // Execute INTERACTIVE action
+  return;
+}
+
+// Unknown command
+console.log("Unknown command. Use /specmem-agents help for usage.");
+```
+
+---
+
+## HELP OUTPUT
+
+```
+SpecMem Agents - Configurable Agent Deployment
+
+USAGE:
+  /specmem-agents                    Show this help
+  /specmem-agents list               List all agent types
+  /specmem-agents config             Show current settings
+  /specmem-agents set <args>         Configure agent settings
+  /specmem-agents deploy <type> <p>  Deploy specific type
+  /specmem-agents interactive        Interactive selector
+
+AVAILABLE AGENT TYPES:
+  general-purpose    Full toolset, any task
+  Bash               Shell command specialist
+  Explore            Codebase exploration (quick/medium/thorough)
+  Plan               Architecture & implementation planning
+  feature-dev:code-explorer    Deep code analysis
+  feature-dev:code-architect   Feature design blueprints
+  feature-dev:code-reviewer    Code review with confidence filtering
+
+CONFIGURABLE SETTINGS:
+  model          haiku | sonnet | opus (default: sonnet)
+  max_turns      1-100 (default: unlimited by type)
+  background     true | false (default: true)
+  ultrathink     true | false (opus only, default: false)
+
+EXAMPLES:
+  /specmem-agents set default model opus
+  /specmem-agents set feature-dev:code-explorer model opus
+  /specmem-agents deploy Explore "find authentication code"
+  /specmem-agents interactive
+
+NOTE: This command does NOT directly call MCP tools.
+      It configures agent settings in .specmem/agent-config.json
+      which are then read by agent-loading-hook.js
+```
+
+---
+
+## LIST - Show Available Agent Types
+
+Display this table:
+
+```
+AVAILABLE AGENT TYPES
+=====================
+
+TYPE                      | TOOLS                           | BEST FOR
+--------------------------|--------------------------------|---------------------------
+general-purpose           | All tools                       | Complex multi-step tasks
+Bash                      | Bash only                       | Git, CLI, terminal ops
+Explore                   | All (fast)                      | Codebase questions
+Plan                      | All                             | Architecture planning
+feature-dev:code-explorer | Glob,Grep,Read,NotebookRead     | Deep code analysis
+feature-dev:code-architect| Glob,Grep,Read,NotebookRead     | Feature design
+feature-dev:code-reviewer | Glob,Grep,Read,NotebookRead     | Code review
+
+THOROUGHNESS LEVELS (for Explore):
+  quick         Basic search, fast results
+  medium        Moderate exploration (default)
+  very thorough Comprehensive analysis
+
+MODEL OPTIONS:
+  haiku    Fast, cheap - simple tasks
+  sonnet   Balanced - most tasks (default)
+  opus     Deep thinking - complex analysis
+
+Set "ultrathink" to use Opus for deepest reasoning.
+```
+
+---
+
+## CONFIG - Show Current Configuration
+
+Read configuration from `.specmem/agent-config.json` or show defaults:
+
+```json
+{
+  "defaults": {
+    "model": "sonnet",
+    "background": true,
+    "ultrathink": false
+  },
+  "agents": {
+    "general-purpose": {
+      "model": "sonnet",
+      "description": "Full toolset agent"
+    },
+    "Explore": {
+      "model": "haiku",
+      "thoroughness": "medium"
+    },
+    "feature-dev:code-explorer": {
+      "model": "sonnet"
+    }
+  },
+  "presets": {
+    "ultrathink-team": {
+      "model": "opus",
+      "background": true,
+      "description": "Deep analysis team with Opus"
+    }
+  }
+}
+```
+
+If no config file exists, show:
+
+```
+CURRENT CONFIGURATION
+=====================
+Using defaults (no custom config)
+
+DEFAULT SETTINGS:
+  model:      sonnet
+  background: true
+  ultrathink: false
+
+Create custom config with:
+  /specmem-agents set default model opus
+  /specmem-agents set Explore model haiku
+```
+
+---
+
+## SET - Configure Agent Settings
+
+Parse: `set <target> <setting> <value>`
+
+Targets:
+- `default` - Set default for all agents
+- `<agent-type>` - Set for specific agent type
+
+Settings:
+- `model` - haiku | sonnet | opus
+- `background` - true | false
+- `ultrathink` - true | false (forces opus model)
+- `max_turns` - number 1-100
+- `thoroughness` - quick | medium | very thorough (Explore only)
+
+### Execution Logic
+
+1. Read existing config from `.specmem/agent-config.json` (or create empty)
+2. Update the specified setting
+3. Save config file
+4. Confirm the change
+
+Example outputs:
+
+```
+SET: default model = opus
+Config saved to .specmem/agent-config.json
+
+All new agents will use opus model by default.
+```
+
+```
+SET: Explore thoroughness = very thorough
+Config saved to .specmem/agent-config.json
+
+Explore agents will now use "very thorough" analysis.
+```
+
+---
+
+## DEPLOY - Deploy Specific Agent Type
+
+Parse: `deploy <type> <prompt>`
+
+Execute:
+```
+Task({
+  subagent_type: "<type>",
+  model: <from config or default>,
+  description: "<first 5 words of prompt>",
+  run_in_background: <from config>,
+  prompt: "<prompt>"
+})
+```
+
+If `ultrathink` is enabled in config, force model to "opus".
+
+Example:
+```
+/specmem-agents deploy feature-dev:code-explorer "trace the authentication flow"
+```
+
+Outputs:
+```
+DEPLOYING AGENT
+===============
+Type:       feature-dev:code-explorer
+Model:      opus (ultrathink enabled)
+Background: true
+Task:       trace the authentication flow
+
+Agent deployed. Check progress with:
+  /tasks
+```
+
+---
+
+## INTERACTIVE - Agent Selector UI
+
+When called, use AskUserQuestion to let user configure:
+
+### Question 1: Agent Type
+```json
+{
+  "question": "What type of agent do you want to deploy?",
+  "header": "Agent Type",
+  "options": [
+    {"label": "general-purpose", "description": "Full toolset for complex tasks"},
+    {"label": "Explore", "description": "Fast codebase exploration"},
+    {"label": "feature-dev:code-explorer", "description": "Deep code analysis"},
+    {"label": "feature-dev:code-architect", "description": "Architecture design"}
+  ],
+  "multiSelect": false
+}
+```
+
+### Question 2: Model Selection
+```json
+{
+  "question": "Which model should the agent use?",
+  "header": "Model",
+  "options": [
+    {"label": "sonnet (Recommended)", "description": "Balanced speed and quality"},
+    {"label": "opus", "description": "Deepest thinking, best for complex analysis"},
+    {"label": "haiku", "description": "Fastest, best for simple tasks"}
+  ],
+  "multiSelect": false
+}
+```
+
+### Question 3: Background Execution
+```json
+{
+  "question": "Run in background?",
+  "header": "Execution",
+  "options": [
+    {"label": "Background (Recommended)", "description": "Run async, continue working"},
+    {"label": "Foreground", "description": "Wait for completion"}
+  ],
+  "multiSelect": false
+}
+```
+
+After selections, ask for the task prompt and deploy.
+
+---
+
+## CONFIG FILE SCHEMA
+
+Location: `.specmem/agent-config.json`
+
+```typescript
+interface AgentConfig {
+  // Global defaults
+  defaults: {
+    model: "haiku" | "sonnet" | "opus";
+    background: boolean;
+    ultrathink: boolean;  // Forces opus with deep thinking
+    max_turns?: number;
+  };
+
+  // Per-agent-type overrides
+  agents: {
+    [agentType: string]: {
+      model?: "haiku" | "sonnet" | "opus";
+      background?: boolean;
+      max_turns?: number;
+      thoroughness?: "quick" | "medium" | "very thorough";  // Explore only
+      description?: string;
+    };
+  };
+
+  // Named presets for quick selection
+  presets: {
+    [presetName: string]: {
+      model: "haiku" | "sonnet" | "opus";
+      background: boolean;
+      description: string;
+      agents?: string[];  // Which agent types to use
+    };
+  };
+}
+```
+
+---
+
+## HOOK INTEGRATION
+
+The `agent-loading-hook.js` should read this config and apply settings:
+
+1. On Task tool PreToolUse, read `.specmem/agent-config.json`
+2. Get settings for the specified `subagent_type`
+3. Override model/background if configured
+4. Apply ultrathink (force opus) if enabled
+5. Continue with modified parameters
+
+---
+
+## MCP Tools Used
+
+- **NONE** - This command manages configuration files only
+- Configuration is read by `agent-loading-hook.js` during Task deployment
+- Agent deployment uses Claude Code's built-in Task tool
+
+---
+
+## EXAMPLES
+
+### Enable Ultrathink for All Agents
+```
+/specmem-agents set default ultrathink true
+```
+
+### Configure Fast Exploration
+```
+/specmem-agents set Explore model haiku
+/specmem-agents set Explore thoroughness quick
+```
+
+### Deploy Deep Analysis Team
+```
+/specmem-agents deploy feature-dev:code-explorer "analyze the authentication system"
+```
+
+### Interactive Full Control
+```
+/specmem-agents interactive
+```
+→ Select agent type → Select model → Choose background → Enter prompt → Deploy

package/commands/specmem-autoclaude.md

@@ -0,0 +1,295 @@
+# SpecMem AutoClaude - Autonomous Task Execution
+
+## COMMAND PARSING - READ THIS FIRST
+
+Parse what comes after `/specmem-autoclaude`:
+
+**CRITICAL: Check for empty/missing arguments FIRST**
+
+```
+ARGS = everything after "/specmem-autoclaude "
+ARGS = ARGS.trim()
+```
+
+**Decision tree:**
+1. If ARGS is empty OR ARGS === "" → **STOP. Output HELP TEXT below. Do NOT proceed.**
+2. If ARGS === "help" OR ARGS === "-h" OR ARGS === "--help" → **STOP. Output HELP TEXT below. Do NOT proceed.**
+3. If ARGS has content (the task prompt) → Continue to AUTOCLAUDE WORKFLOW
+
+---
+
+## HELP TEXT - OUTPUT THIS EXACTLY THEN STOP
+
+**When to show:** Empty args, no args, or "help" argument.
+
+**ACTION:** Output the text below verbatim, then STOP. Do not call any MCP tools.
+
+```
+SpecMem AutoClaude - Autonomous Task Execution
+
+USAGE:
+  /specmem-autoclaude "<task>"    Execute task autonomously
+  /specmem-autoclaude help        Show this help
+
+EXAMPLES:
+  /specmem-autoclaude "fix the login bug"
+  /specmem-autoclaude "improve websocket performance"
+  /specmem-autoclaude "add dark mode to dashboard"
+
+WHAT IT DOES:
+  1. Searches SpecMem for relevant memories
+  2. Finds related code files in codebase
+  3. Creates todo list and executes task autonomously
+  4. Saves learnings for future reference
+
+REQUIRED:
+  - You MUST provide a task in quotes
+  - Empty command shows this help
+
+TIPS:
+  - Be specific about what you want
+  - Works best with tasks discussed before
+  - Check /specmem-stats for available context
+
+MCP TOOLS USED:
+  - mcp__specmem__find_memory (search memories)
+  - mcp__specmem__find_code_pointers (search code)
+  - mcp__specmem__save_memory (store learnings)
+
+RELATED:
+  /specmem-find      Search memories only
+  /specmem-code      Search code only
+  /specmem-stats     View memory statistics
+```
+
+**STOP HERE IF SHOWING HELP. Do not continue to workflow.**
+
+---
+
+## AUTOCLAUDE WORKFLOW
+
+**PREREQUISITE:** A task prompt MUST be provided. If $TASK is empty, go back to HELP TEXT.
+
+When a task is provided, execute these steps:
+
+### Step 1: Gather Memory Context
+
+Search for relevant memories about the task:
+
+**Call mcp__specmem__find_memory:**
+```
+{
+  "query": "$TASK",
+  "limit": 10,
+  "summarize": false,
+  "keywordFallback": true,
+  "includeRecent": 5
+}
+```
+
+Also search for related issues and problems:
+```
+{
+  "query": "problem issue bug error $TASK",
+  "limit": 5,
+  "summarize": true
+}
+```
+
+**PARAMETERS:**
+- query: string (REQUIRED) - what to search for
+- limit: number (default: 10) - max results
+- summarize: boolean (default: true) - truncate content
+- keywordFallback: boolean (default: true) - fallback to keyword search
+- includeRecent: number (default: 0) - force include N recent memories
+
+### Step 2: Find Relevant Code
+
+Use semantic code search to find related files:
+
+**Call mcp__specmem__find_code_pointers:**
+```
+{
+  "query": "$TASK",
+  "limit": 10,
+  "threshold": 0.1,
+  "includeTracebacks": true,
+  "includeMemoryLinks": true,
+  "zoom": 50
+}
+```
+
+**PARAMETERS:**
+- query: string (REQUIRED) - what code to search for
+- limit: number (default: 10) - max results
+- threshold: number (default: 0.1) - min similarity 0-1
+- includeTracebacks: boolean (default: true) - show caller/callee
+- includeMemoryLinks: boolean (default: true) - link to memories
+- zoom: number (default: 50) - detail level 0-100
+
+### Step 3: Create Todo List
+
+Based on the memories and code found, create actionable todos:
+
+**Call TodoWrite:**
+```
+[
+  {
+    content: "Analyze current implementation",
+    status: "in_progress",
+    activeForm: "Analyzing implementation"
+  },
+  {
+    content: "Implement fix/improvement",
+    status: "pending",
+    activeForm: "Implementing changes"
+  },
+  {
+    content: "Test changes",
+    status: "pending",
+    activeForm: "Testing changes"
+  },
+  {
+    content: "Save learnings to SpecMem",
+    status: "pending",
+    activeForm: "Saving learnings"
+  }
+]
+```
+
+### Step 4: Execute Autonomously
+
+**RULES:**
+1. Read files BEFORE editing (use Read tool)
+2. Make targeted, focused changes (use Edit tool)
+3. Test after significant changes (use Bash tool if needed)
+4. Update todos as you progress (mark completed, add new ones)
+5. If you get stuck, save progress and report
+
+**WORKFLOW:**
+- Mark first todo as "in_progress"
+- Complete the task
+- Mark as "completed" when done
+- Move to next todo
+
+### Step 5: Save Learnings
+
+When task is complete, save a comprehensive memory:
+
+**Call mcp__specmem__save_memory:**
+```
+{
+  "content": "Task: $TASK\n\nChanges Made:\n- [list specific changes]\n- [one change per line]\n\nFiles Modified:\n- [absolute path 1]\n- [absolute path 2]\n\nKey Learnings:\n[insights gained]\n[patterns discovered]\n[things to remember]\n\nContext:\n[relevant context for future reference]",
+  "importance": "high",
+  "memoryType": "episodic",
+  "tags": ["task-completion", "autoclaude", "task-type"]
+}
+```
+
+**PARAMETERS:**
+- content: string (REQUIRED) - the memory content
+- importance: "critical" | "high" | "medium" | "low" | "trivial" (default: "medium")
+- memoryType: "episodic" | "semantic" | "procedural" | "working" (default: "semantic")
+- tags: string[] (optional) - categorization tags
+
+**VALIDATION:**
+- content MUST NOT be empty
+- Use "high" importance for task completions
+- Use "episodic" type for events/tasks
+- Include relevant tags for categorization
+
+### Step 6: Report Completion
+
+Output a summary:
+
+```
+AUTOCLAUDE TASK COMPLETE
+
+TASK: $TASK
+
+CHANGES MADE:
+- [specific change 1 with file path]
+- [specific change 2 with file path]
+- [etc.]
+
+FILES MODIFIED:
+- /absolute/path/to/file1
+- /absolute/path/to/file2
+
+MEMORIES SEARCHED: [count] memories found
+CODE SEARCHED: [count] files found
+MEMORY SAVED: [memory_id] - learnings stored for future reference
+
+NEXT STEPS:
+- [optional: suggest what user should do next]
+- [optional: mention related tasks]
+```
+
+---
+
+## ERROR HANDLING
+
+**If memory search returns no results:**
+- Try broader search terms
+- Check if task relates to something discussed before
+- Proceed with code search only
+
+**If code search returns no results:**
+- Try different search terms
+- Check file patterns and language filters
+- Ask user to clarify which files to modify
+
+**If unable to complete task:**
+- Save partial progress to memory
+- Mark current todo as "in_progress" (not completed)
+- Report what was done and what's blocked
+- Ask user for guidance
+
+---
+
+## VALIDATION CHECKLIST
+
+Before executing, verify:
+- [ ] Task prompt is NOT empty
+- [ ] find_memory called with valid query
+- [ ] find_code_pointers called with valid query
+- [ ] TodoWrite called with valid todo structure
+- [ ] save_memory called with non-empty content
+- [ ] All file paths in output are ABSOLUTE (not relative)
+- [ ] All changes are tested before marking complete
+- [ ] Final memory includes all relevant details
+
+---
+
+## TOOL REFERENCE
+
+### mcp__specmem__find_memory
+Search memories by semantic meaning.
+
+**Required:** query (string)
+**Optional:** limit, summarize, keywordFallback, includeRecent, threshold, memoryTypes, tags
+
+### mcp__specmem__find_code_pointers
+Search code by semantic meaning.
+
+**Required:** query (string)
+**Optional:** limit, threshold, includeTracebacks, includeMemoryLinks, zoom, language, filePattern, definitionTypes
+
+### mcp__specmem__save_memory
+Store a memory for future reference.
+
+**Required:** content (string)
+**Optional:** importance, memoryType, tags, metadata
+
+**CRITICAL:** content parameter MUST NOT be empty string.
+
+---
+
+## NOTES
+
+- Always use absolute file paths in output
+- Test changes before marking todos complete
+- Save detailed learnings to help with future tasks
+- If task is ambiguous, ask for clarification
+- Use existing memories to inform your approach
+- Link related memories when relevant