specmem-hardwicksoftware 3.5.99

package/commands/specmem-hooks.md

@@ -0,0 +1,219 @@
+# SpecMem Hooks - Custom Hook Management
+
+Manage Claude Code hooks in `/specmem/claude-hooks/`.
+
+## COMMAND PARSING
+
+Parse what comes after `/specmem-hooks`:
+
+```javascript
+const args = "$ARGUMENTS".trim();
+
+if (!args || args === "help" || args === "--help" || args === "-h") {
+  // Show HELP below
+  return;
+}
+
+if (args === "list") {
+  // Execute LIST action
+  return;
+}
+
+if (args === "status") {
+  // Execute STATUS action
+  return;
+}
+
+if (args === "deploy") {
+  // Execute DEPLOY action
+  return;
+}
+
+if (args === "scan") {
+  // Execute SCAN action
+  return;
+}
+
+// Unknown command
+console.log("Unknown command. Use /specmem-hooks help for usage.");
+```
+
+---
+
+## HELP OUTPUT
+
+If no args or "help":
+
+```
+SpecMem Hooks - Hook Management
+
+USAGE:
+  /specmem-hooks              Show this help
+  /specmem-hooks list         List all hooks with descriptions
+  /specmem-hooks status       Show hook system status
+  /specmem-hooks deploy       Deploy enabled hooks to ~/.claude/hooks/
+  /specmem-hooks scan         Scan claude-hooks directory
+
+HOOKS DIRECTORY:
+  Source: /specmem/claude-hooks/
+  Target: ~/.claude/hooks/
+
+HOOK TYPES:
+  .js  - Node.js hooks (PreToolUse, PostToolUse, etc.)
+  .py  - Python hooks
+  .sh  - Shell script hooks
+  .cjs - CommonJS hooks
+
+AVAILABLE HOOKS:
+  agent-loading-hook.js           Configures agent deployment
+  agent-output-interceptor.js     Intercepts agent output
+  agent-type-matcher.js           Matches agent types
+  background-completion-silencer.js  Silences background completions
+  bash-auto-background.js         Auto-backgrounds long Bash commands
+  input-aware-improver.js         Improves prompts based on context
+  smart-context-hook.js           Smart context injection
+  smart-search-interceptor.js     Intercepts search operations
+  specmem-context-hook.js         Injects SpecMem context into prompts
+  specmem-drilldown-hook.js       Enforces drilldown after searches
+  specmem-precompact.js           Precompacts responses
+  specmem-session-start.cjs       Session initialization
+  specmem-team-member-inject.js   Injects team member coordination
+  specmem-unified-hook.py         Unified Python hook for all events
+  subagent-loading-hook.js        Configures subagent loading
+  task-progress-hook.js           Tracks task progress
+
+RELATED:
+  /specmem-stats    View system statistics
+  /specmem          Main SpecMem commands
+
+NOTE: This command does NOT use MCP tools.
+      It manages files in the hooks directory using Bash.
+```
+
+---
+
+## EXECUTION
+
+### For "list"
+
+Execute this bash command:
+
+```bash
+echo "=== SPECMEM HOOKS ===" && \
+echo "" && \
+for f in /specmem/claude-hooks/*.{js,py,sh,cjs} 2>/dev/null; do \
+  if [ -f "$f" ]; then \
+    echo "$(basename "$f")" && \
+    head -3 "$f" | grep -E "^(//|#)" | sed 's/^/  /' && \
+    echo ""; \
+  fi; \
+done
+```
+
+Display the output showing each hook file with its description from comments.
+
+### For "status"
+
+Execute these bash commands:
+
+```bash
+echo "=== HOOK SYSTEM STATUS ===" && \
+echo "" && \
+echo "Source Directory: /specmem/claude-hooks/" && \
+ls -1 /specmem/claude-hooks/*.{js,py,sh,cjs} 2>/dev/null | wc -l | xargs -I{} echo "Total Hooks: {}" && \
+echo "" && \
+echo "Target Directory: ~/.claude/hooks/" && \
+if [ -d ~/.claude/hooks/ ]; then \
+  ls -la ~/.claude/hooks/; \
+else \
+  echo "(not found - run deploy)"; \
+fi && \
+echo "" && \
+echo "Recent Hook Activity:" && \
+ls -lt /specmem/claude-hooks/*.{js,py,sh,cjs} 2>/dev/null | head -5 | awk '{print "  " $6, $7, $8, $9}'
+```
+
+### For "deploy"
+
+Execute these bash commands:
+
+```bash
+mkdir -p ~/.claude/hooks && \
+echo "Deploying hooks to ~/.claude/hooks/..." && \
+cp /specmem/claude-hooks/*.js ~/.claude/hooks/ 2>/dev/null; \
+cp /specmem/claude-hooks/*.cjs ~/.claude/hooks/ 2>/dev/null; \
+cp /specmem/claude-hooks/*.py ~/.claude/hooks/ 2>/dev/null; \
+cp /specmem/claude-hooks/*.sh ~/.claude/hooks/ 2>/dev/null; \
+chmod +x ~/.claude/hooks/* 2>/dev/null && \
+echo "" && \
+echo "Deployed hooks:" && \
+ls -la ~/.claude/hooks/
+```
+
+Report success or failure.
+
+### For "scan"
+
+Execute this bash command:
+
+```bash
+echo "=== SCANNING HOOKS ===" && \
+echo "" && \
+echo "JavaScript Hooks:" && \
+ls -la /specmem/claude-hooks/*.js 2>/dev/null || echo "  (none)" && \
+echo "" && \
+echo "CommonJS Hooks:" && \
+ls -la /specmem/claude-hooks/*.cjs 2>/dev/null || echo "  (none)" && \
+echo "" && \
+echo "Python Hooks:" && \
+ls -la /specmem/claude-hooks/*.py 2>/dev/null || echo "  (none)" && \
+echo "" && \
+echo "Shell Hooks:" && \
+ls -la /specmem/claude-hooks/*.sh 2>/dev/null || echo "  (none)"
+```
+
+---
+
+## HOOK DESCRIPTIONS
+
+Brief descriptions for common hooks:
+
+- **agent-loading-hook.js** - Configures model/settings for agent deployment based on .specmem/agent-config.json
+- **agent-output-interceptor.js** - Processes agent output for special formatting
+- **bash-auto-background.js** - Automatically backgrounds long-running Bash commands
+- **input-aware-improver.js** - Analyzes input and suggests improvements
+- **smart-context-hook.js** - Injects relevant SpecMem context into prompts
+- **specmem-context-hook.js** - Adds SpecMem memories to conversation context
+- **specmem-drilldown-hook.js** - Reminds user to drilldown after memory searches
+- **specmem-team-member-inject.js** - Adds team coordination instructions
+- **task-progress-hook.js** - Tracks and displays task progress
+
+---
+
+## MCP TOOLS USED
+
+**NONE** - This command uses Bash exclusively for file operations.
+
+---
+
+## EXAMPLES
+
+### List all hooks
+```
+/specmem-hooks list
+```
+
+### Check hook system status
+```
+/specmem-hooks status
+```
+
+### Deploy hooks to Claude
+```
+/specmem-hooks deploy
+```
+
+### Scan for new hooks
+```
+/specmem-hooks scan
+```

package/commands/specmem-pointers.md

@@ -0,0 +1,149 @@
+# SpecMem Pointers - Semantic Code Search with Tracebacks (user)
+
+## IMMEDIATE ACTION REQUIRED
+
+**Step 1: Check Input**
+Look at what comes after `/specmem-pointers`:
+
+- If EMPTY, whitespace only, "help", "--help", or "-h" → Show HELP below, STOP
+- Otherwise → Continue to Step 2
+
+**Step 2: Parse Arguments**
+Extract from input:
+- `--limit N` → set limit (default: 10, max: 100)
+- `--threshold N` → set threshold (default: 0.1, range: 0-1)
+- `--gallery` → galleryMode: true (Mini COT analysis)
+- `--camera` → cameraRollMode: true (drilldown IDs)
+- `--zoom-level LEVEL` → zoomLevel: ultra-wide/wide/normal/close/macro
+- `--zoom N` → zoom: 0-100 (0=signature, 50=balanced, 100=full)
+- `--lang LANG` → set language filter
+- `--file PATTERN` → set filePattern
+- `--type TYPE` → set definitionTypes (function, class, method, etc.)
+- `--no-tracebacks` → includeTracebacks: false
+- `--no-memory-links` → includeMemoryLinks: false
+- `--with-attribution` → includeAttribution: true
+- `--cot-scoring` → useCotScoring: true
+- `--summarize` → summarize: true
+- `--max-content N` → maxContentLength: N
+- Everything else = the query
+
+**VALIDATION:**
+- If query is empty after parsing options → STOP and show HELP
+- If limit < 1 or limit > 100 → ERROR: "limit must be 1-100"
+- If threshold < 0 or threshold > 1 → ERROR: "threshold must be 0-1"
+- If zoom < 0 or zoom > 100 → ERROR: "zoom must be 0-100"
+
+**Step 3: EXECUTE THIS MCP TOOL NOW**
+
+```
+mcp__specmem__find_code_pointers({
+  query: "<extracted query>",
+  limit: <limit or 10>,
+  threshold: <threshold or 0.1>,
+  includeTracebacks: <true unless --no-tracebacks>,
+  includeMemoryLinks: <true unless --no-memory-links>,
+  includeAttribution: <true if --with-attribution>,
+  galleryMode: <true if --gallery>,
+  cameraRollMode: <true if --camera>,
+  useCotScoring: <true if --cot-scoring>,
+  zoomLevel: "<zoom level if provided>",
+  zoom: <zoom value if provided or 50>,
+  language: "<lang if provided>",
+  filePattern: "<pattern if provided>",
+  definitionTypes: <[type] if provided>,
+  summarize: <true if --summarize>,
+  maxContentLength: <N if --max-content>
+})
+```
+
+**Step 4: Display Results**
+Show the tool output formatted as:
+
+```
+CODE POINTERS: "<query>"
+Found N results (threshold: X.XX)
+
+[1] <file>:<line> | <type> | score: <similarity>
+    <code snippet>
+
+    USED BY (Tracebacks):
+    - <caller-file>:<line>
+    - <caller-file>:<line>
+
+    Memory Links: <related memories if available>
+    Attribution: <user/assistant if enabled>
+
+[2] <file>:<line> | <type> | score: <similarity>
+    <code snippet>
+
+    USED BY:
+    - <caller-file>:<line>
+...
+```
+
+If --gallery, include Mini COT analysis summary.
+If --camera, mention drilldown IDs for exploration.
+If --with-attribution, show who created/modified the code.
+
+---
+
+## HELP
+
+```
+SpecMem Pointers - Semantic Code Search with Tracebacks
+
+USAGE:
+  /specmem-pointers <query>
+  /specmem-pointers authentication flow
+  /specmem-pointers --gallery websocket handler
+  /specmem-pointers --limit 20 database queries
+
+OPTIONS:
+  --limit N              Max results (default: 10, max: 100)
+  --threshold N          Min similarity 0-1 (default: 0.1)
+  --gallery              Enable Mini COT analysis (deeper insights)
+  --camera               Enable camera roll mode (drilldown IDs)
+  --zoom-level LEVEL     ultra-wide/wide/normal/close/macro
+  --zoom N               Zoom 0-100: 0=sig only, 50=balanced, 100=full
+  --lang LANG            Filter by language (typescript, python, etc.)
+  --file PATTERN         Filter by file pattern (e.g., "src/**/*.ts")
+  --type TYPE            Filter by type (function, class, method, etc.)
+  --no-tracebacks        Skip caller/callee analysis
+  --no-memory-links      Skip memory attribution
+  --with-attribution     Show user/claude attribution
+  --cot-scoring          Enable Mini COT relevance scoring
+  --summarize            Truncate content for compact view
+  --max-content N        Max content length (0=unlimited)
+
+EXAMPLES:
+  /specmem-pointers error handling middleware
+  /specmem-pointers --gallery api validation
+  /specmem-pointers --limit 15 form components
+  /specmem-pointers --lang python data processing
+  /specmem-pointers --zoom 0 function signatures
+  /specmem-pointers --camera --zoom-level wide search patterns
+  /specmem-pointers --with-attribution authentication logic
+
+WHAT IT DOES:
+  1. Semantic search finds code by MEANING (not keywords)
+  2. Shows tracebacks - what files import/use the code
+  3. Links code to related memories (context from past work)
+  4. Gallery mode adds AI analysis of results
+  5. Camera roll mode enables drill-down exploration
+
+TRACEBACKS:
+  Shows which files use the found code:
+  - Import relationships
+  - Function calls
+  - Class usage
+  - Caller/callee analysis
+
+DIFFERENCE FROM /specmem-code:
+  - /specmem-code: Basic code search (NO tracebacks by default)
+  - /specmem-pointers: Code search WITH tracebacks enabled
+
+RELATED:
+  /specmem-code     Code search WITHOUT tracebacks
+  /specmem-find     Search memories (not code)
+  /specmem-changes  View file change history
+```

package/commands/specmem-progress.md

@@ -0,0 +1,287 @@
+# SpecMem Progress - Watch Team Member Progress
+
+Watch team member progress in real-time using SpecMem team communication.
+
+## COMMAND PARSING
+
+```javascript
+const args = "$ARGUMENTS".trim();
+
+if (!args || args === "help" || args === "--help" || args === "-h") {
+  // Show recent team messages (default 10)
+  // Execute DEFAULT action
+  return;
+}
+
+if (args === "--live" || args === "live") {
+  // Execute LIVE mode
+  return;
+}
+
+if (args.startsWith("--count ")) {
+  const countMatch = args.match(/--count\s+(\d+)/);
+  if (!countMatch) {
+    console.log("ERROR: --count requires a number");
+    console.log("Example: /specmem-progress --count 20");
+    return;
+  }
+  const count = parseInt(countMatch[1], 10);
+  // Execute with custom count
+  return;
+}
+
+// Unknown argument - show help
+console.log("Unknown argument. Use /specmem-progress help for usage.");
+```
+
+---
+
+## INPUT VALIDATION
+
+```javascript
+const args = "$ARGUMENTS".trim();
+
+// Valid commands:
+// - /specmem-progress              (show last 10)
+// - /specmem-progress --count 20   (show last 20)
+// - /specmem-progress --live       (live polling)
+// - /specmem-progress help         (show help)
+```
+
+---
+
+## HELP OUTPUT
+
+```
+SpecMem Progress - Watch Team Activity
+
+USAGE:
+  /specmem-progress              Show last 10 team messages
+  /specmem-progress --count 20   Show last 20 messages
+  /specmem-progress --live       Live polling mode (updates every 5s)
+  /specmem-progress help         Show this help
+
+WHAT YOU'LL SEE:
+  - Team member status updates
+  - Task claims and completions
+  - Help requests and responses
+  - Broadcast messages
+
+This shows real progress from agents using MCP team communication!
+
+MCP TOOL USED:
+  mcp__specmem__read_team_messages
+
+RELATED:
+  /specmem-team-member status    Full team status
+  /specmem-team-member messages  Read messages with filters
+```
+
+---
+
+## EXECUTION
+
+### DEFAULT MODE (no args or "help")
+
+Execute this MCP tool:
+
+```javascript
+mcp__specmem__read_team_messages({
+  limit: 10,
+  compress: false
+})
+```
+
+### WITH --count
+
+Execute this MCP tool with custom limit:
+
+```javascript
+mcp__specmem__read_team_messages({
+  limit: COUNT,
+  compress: false
+})
+```
+
+### LIVE MODE (--live)
+
+Poll `mcp__specmem__read_team_messages` every 5 seconds.
+
+Only show NEW messages since last poll by using the `since` parameter:
+
+```javascript
+// First call - show last 10
+let lastTimestamp = null;
+
+while (true) {
+  const result = mcp__specmem__read_team_messages({
+    limit: 10,
+    since: lastTimestamp,
+    compress: false
+  });
+
+  if (result.messages && result.messages.length > 0) {
+    // Display new messages
+    displayMessages(result.messages);
+
+    // Update last timestamp
+    lastTimestamp = result.messages[0].timestamp;
+  }
+
+  // Wait 5 seconds
+  await sleep(5000);
+}
+```
+
+**NOTE**: Live mode should display "Press Ctrl+C to stop" and update in place.
+
+---
+
+## DISPLAY FORMAT
+
+Show messages in a clean progress format:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  📊 TEAM PROGRESS                                            ║
+╠══════════════════════════════════════════════════════════════╣
+║  [12:34:05] Agent-1: Starting authentication module...       ║
+║  [12:34:12] Agent-2: Claimed files: src/auth/*               ║
+║  [12:34:25] Agent-1: ✅ Completed login form                 ║
+║  [12:34:30] Agent-3: 🔄 Working on API endpoints...          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Showing 4 messages. Use --count to see more.
+```
+
+For each message, display:
+- **Timestamp**: [HH:MM:SS] format
+- **Sender**: Abbreviated sender name or ID
+- **Content**: Message content (truncate if > 60 chars)
+- **Icon**: Based on message type
+  - 🔄 - status updates
+  - ✅ - completions
+  - ❓ - questions
+  - 🆘 - help requests
+  - 📢 - broadcasts
+
+---
+
+## MCP TOOL SCHEMA
+
+Tool: `mcp__specmem__read_team_messages`
+
+Optional parameters:
+- `limit`: number (default: 10, max: 100) - Max messages to return
+- `since`: string (ISO 8601) - Only messages after this timestamp
+- `unread_only`: boolean (default: false) - Only unread messages
+- `mentions_only`: boolean (default: false) - Only messages mentioning you
+- `include_broadcasts`: boolean (default: true) - Include broadcast messages
+- `compress`: boolean (default: true) - Enable Chinese compression
+
+Returns:
+- `messages`: array of TeamMessage objects
+  - `id`: string - Message ID
+  - `sender`: string - Sender ID
+  - `sender_name`: string - Sender display name
+  - `content`: string - Message content
+  - `type`: string - Message type
+  - `priority`: string - Message priority
+  - `timestamp`: string - ISO 8601 timestamp
+  - `mentions`: string[] - Mentioned member IDs
+  - `read_by`: string[] - Members who read this
+
+---
+
+## OUTPUT EXAMPLES
+
+### Default (last 10 messages)
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  📊 TEAM PROGRESS                                            ║
+╠══════════════════════════════════════════════════════════════╣
+║  [14:23:45] design-agent: 🔄 Setting up design tokens        ║
+║  [14:24:12] component-agent: 🔄 Creating Button component    ║
+║  [14:24:30] design-agent: ✅ Design system complete          ║
+║  [14:25:01] component-agent: ✅ Button component ready       ║
+║  [14:25:15] integration-agent: 🔄 Integrating components     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Showing 5 messages. Use --count to see more.
+```
+
+### With --count 20
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  📊 TEAM PROGRESS (Last 20)                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║  [13:00:00] coordinator: 📢 Starting webdev team deployment  ║
+║  [13:00:15] design-agent: 🔄 Claimed tailwind.config.ts      ║
+║  ...                                                          ║
+║  [14:25:15] integration-agent: 🔄 Integrating components     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Showing 20 messages.
+```
+
+### Live mode
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  📊 TEAM PROGRESS (LIVE)                                     ║
+║  Press Ctrl+C to stop                                        ║
+╠══════════════════════════════════════════════════════════════╣
+║  [14:25:15] integration-agent: 🔄 Integrating components     ║
+║  [14:25:30] quality-agent: 🔄 Starting review...             ║
+║  [14:26:00] quality-agent: ✅ Quality check passed!          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Last update: 14:26:00
+```
+
+### No messages
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  📊 TEAM PROGRESS                                            ║
+╠══════════════════════════════════════════════════════════════╣
+║  No team messages found.                                     ║
+║                                                               ║
+║  Try:                                                         ║
+║  - Deploy a team: /specmem-webdev <task>                     ║
+║  - Check status: /specmem-team-member status                 ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## MCP TOOLS USED
+
+- `mcp__specmem__read_team_messages` - Read team communication messages
+
+---
+
+## EXAMPLES
+
+### Show last 10 messages
+```
+/specmem-progress
+```
+
+### Show last 20 messages
+```
+/specmem-progress --count 20
+```
+
+### Live polling mode
+```
+/specmem-progress --live
+```
+(Press Ctrl+C to stop)
+
+### Show help
+```
+/specmem-progress help
+```