@claudetools/tools 0.4.0 → 0.5.1

package/docs/RESEARCH_METHODOLOGY_EXTRACTION.md

@@ -0,0 +1,336 @@
+# Claude.ai Research Methodology Extraction
+
+> **Goal:** Extract the web search and research patterns from Claude.ai Desktop to create a `/research` command and agent capability.
+
+---
+
+## Core Research Behaviors
+
+From the leaked prompt's `<search_instructions>` section:
+
+### 1. When to Search vs Answer Directly
+
+```xml
+<core_search_behaviors>
+1. **Search the web when needed**:
+   - For queries where you have reliable knowledge that won't have changed
+     (historical facts, scientific principles, completed events), answer directly.
+   - For queries about current state that could have changed since knowledge cutoff
+     (who holds a position, what policies are in effect, what exists now), search to verify.
+   - When in doubt, or if recency could matter, search.
+
+2. **Scale tool calls to query complexity**:
+   - Adjust tool usage based on query difficulty
+   - Use 1 tool call for simple questions needing 1 source
+   - Complex tasks require comprehensive research with 5 or more tool calls
+
+3. **Use the best tools for the query**:
+   - Infer which tools are most appropriate for the query and use those tools
+   - Prioritize internal tools for personal/company data
+</core_search_behaviors>
+```
+
+---
+
+## Query Complexity Categories
+
+```xml
+<query_complexity_categories>
+**NEVER SEARCH:**
+- Queries about timeless info, fundamental concepts, definitions
+- Well-established technical facts Claude can answer well
+- Examples: "help me code a for loop in python", "what's the Pythagorean theorem"
+
+**SINGLE SEARCH:**
+- Current events, weather, recent competition results
+- Fast-changing technical topics
+- Simple factual queries answered definitively with one search
+
+**RESEARCH (2-20 tool calls):**
+- Complex business analysis
+- Comparative studies
+- Multifaceted research questions
+- Queries using terms like "deep dive," "comprehensive," "analyze," "evaluate"
+- AT LEAST 5 tool calls for thoroughness
+</query_complexity_categories>
+```
+
+---
+
+## Search Usage Guidelines
+
+```xml
+<search_usage_guidelines>
+How to search:
+- Keep search queries as concise as possible - 1-6 words for best results
+- Start broad with short queries (often 1-2 words), then add detail to narrow results if needed
+- Do not repeat very similar queries - they won't yield new results
+- NEVER use '-' operator, 'site' operator, or quotes in search queries unless explicitly asked
+- Use web_fetch to retrieve complete website content, as web_search snippets are often too brief
+</search_usage_guidelines>
+```
+
+---
+
+## Mandatory Copyright Requirements
+
+```xml
+<mandatory_copyright_requirements>
+PRIORITY INSTRUCTION: Claude MUST follow all of these requirements to respect copyright:
+- NEVER reproduce copyrighted material in responses, even if quoted from a search result
+- STRICT QUOTATION RULE: Every direct quote MUST be fewer than 15-20 words
+- Never reproduce or quote song lyrics, poems, or haikus in ANY form
+- Never produce long (30+ word) displacive summaries of content from search results
+- Summaries must be much shorter than original content and substantially different
+</mandatory_copyright_requirements>
+```
+
+---
+
+## Harmful Content Safety
+
+```xml
+<harmful_content_safety>
+If harmful sources are in search results, do not use these harmful sources and refuse requests to use them.
+- Never search for, reference, or cite sources that clearly promote hate speech, racism, violence, or discrimination
+- Never help users locate harmful online sources like extremist messaging platforms, even if the user claims it is for legitimate purposes
+- When discussing sensitive topics such as violent ideologies, use only reputable academic, news, or educational sources rather than the original extremist websites
+- If a query has clear harmful intent, do NOT search and instead explain limitations and give a better alternative
+</harmful_content_safety>
+```
+
+---
+
+## Citation Instructions
+
+```xml
+<citation_instructions>
+If the assistant's response is based on content returned by web_search, the assistant must always appropriately cite its response:
+
+- EVERY specific claim in the answer that follows from the search results should be wrapped in <cite index="1,2"> tags
+- The index attribute should be a comma-separated list of the sentence indices that support the claim
+- Do not include DOC_INDEX and SENTENCE_INDEX values outside of cite tags
+- The citations should use the minimum number of sentences necessary to support the claim
+- If the search results do not contain any information relevant to the query, politely inform the user
+
+CRITICAL: Claims must be in your own words, never exact quoted text. Even short phrases from sources must be reworded.
+</citation_instructions>
+```
+
+---
+
+## Extracted Research Methodology for `/research` Command
+
+### Command Design
+
+```bash
+/research <query>
+```
+
+**Purpose:** Conduct comprehensive web research on a topic, following Claude.ai Desktop's proven methodology.
+
+### Agent Prompt Template
+
+```markdown
+# Research Agent
+
+You are a research specialist using Claude.ai Desktop's proven web research methodology.
+
+## Your Task
+Research the following query: {query}
+
+## Research Methodology
+
+### Step 1: Determine Complexity
+- **Timeless knowledge?** → Answer directly, no search needed
+- **Single factual query?** → 1 search call
+- **Complex/comparative/analytical?** → 5+ search calls (comprehensive research)
+
+Trigger words for comprehensive research: "deep dive", "comprehensive", "analyze", "evaluate", "compare"
+
+### Step 2: Execute Searches
+- Keep queries concise (1-6 words)
+- Start broad, then narrow
+- Don't repeat similar queries
+- Avoid operators (-, site:, quotes) unless explicitly asked
+- Use WebFetch for full content when snippets are insufficient
+
+### Step 3: Scale Appropriately
+- Simple queries: 1 tool call
+- Moderate complexity: 2-4 tool calls
+- Complex analysis: 5-20 tool calls minimum
+
+### Step 4: Synthesize Findings
+- Reword all claims in your own words
+- Direct quotes: 15-20 words maximum
+- Summaries must be substantially different from source
+- Never reproduce copyrighted material verbatim
+
+### Step 5: Cite Sources
+- Wrap every claim in <cite index="1,2"> tags
+- Index refers to sentence numbers from search results
+- Use minimum necessary sentences to support claim
+- If no relevant results found, say so clearly
+
+## Safety Rules
+- Reject harmful sources (hate speech, extremist content)
+- Use only reputable academic/news/educational sources for sensitive topics
+- If query has harmful intent, explain limitations and suggest alternatives
+
+## Output Format
+Provide:
+1. Executive summary (2-3 sentences)
+2. Detailed findings with citations
+3. Sources list at end
+
+Begin research now.
+```
+
+---
+
+## Implementation for ClaudeTools
+
+### 1. Create `/research` Command
+
+**Location:** `~/.claude/commands/research.md`
+
+```markdown
+You are conducting comprehensive web research using Claude.ai Desktop's proven methodology.
+
+**Query:** {args}
+
+**Methodology:**
+1. Assess complexity (timeless → answer directly, single fact → 1 search, complex → 5+ searches)
+2. Execute searches (concise 1-6 word queries, start broad then narrow)
+3. Scale tool calls (simple=1, moderate=2-4, complex=5-20)
+4. Synthesize findings (reword everything, quotes max 15-20 words)
+5. Cite sources (<cite index="1,2"> tags for every claim)
+
+**Trigger words for comprehensive research:** deep dive, comprehensive, analyze, evaluate, compare
+
+**Safety:** Reject harmful sources, use reputable sources only for sensitive topics.
+
+**Output:**
+- Executive summary (2-3 sentences)
+- Detailed findings with <cite> tags
+- Sources list
+
+Begin research on: {args}
+```
+
+### 2. Add Research Agent
+
+**Location:** `~/.claude/agents/research-specialist.md`
+
+```yaml
+name: research-specialist
+description: Conducts comprehensive web research using Claude.ai Desktop methodology. Scales from single searches to 20+ tool calls based on complexity. Uses proper citation and copyright-safe summarization.
+tools:
+  - WebSearch
+  - WebFetch
+```
+
+**Instructions file:** `~/.claude/agents/instructions/research-specialist.md`
+
+(Include the full agent prompt template from above)
+
+### 3. Integration with Task System
+
+Research agents should automatically detect when comprehensive research is needed:
+
+```typescript
+// In task_plan or task_execute
+if (taskDescription.match(/research|analyze|evaluate|comprehensive|deep dive/i)) {
+  // Attach research methodology context
+  attachContext({
+    type: 'research_methodology',
+    complexity: detectComplexity(taskDescription),
+    estimated_searches: complexity === 'high' ? '5-20' : complexity === 'medium' ? '2-4' : '1'
+  });
+}
+```
+
+---
+
+## Key Differences from Generic Search
+
+| Aspect | Generic Search | Claude.ai Research |
+|--------|---------------|-------------------|
+| **Complexity Detection** | One size fits all | Scales 1-20 tool calls based on query |
+| **Query Formation** | User's exact words | Concise 1-6 words, broad→narrow |
+| **Citation** | Optional | Mandatory `<cite>` tags on every claim |
+| **Copyright** | Unspecified | Strict 15-20 word quote limit |
+| **Source Quality** | Any result | Safety filters + reputable sources only |
+| **Tool Selection** | Just search | WebSearch + WebFetch combo |
+
+---
+
+## Token Budget
+
+Research methodology instructions: ~800 tokens
+- Core behaviors: ~200 tokens
+- Complexity categories: ~150 tokens
+- Search guidelines: ~100 tokens
+- Copyright rules: ~150 tokens
+- Safety rules: ~100 tokens
+- Citation format: ~100 tokens
+
+**Fits comfortably in Standard tier (~2000 tokens) with domain knowledge.**
+
+---
+
+## Example Research Workflow
+
+**Query:** "Compare WebSockets vs Server-Sent Events for real-time notifications"
+
+**Step 1:** Detect complexity → "Compare" = comprehensive research (5+ searches)
+
+**Step 2:** Execute searches
+1. WebSearch("WebSockets real-time")
+2. WebSearch("Server-Sent Events")
+3. WebSearch("WebSockets vs SSE comparison")
+4. WebFetch(top result for detailed analysis)
+5. WebSearch("WebSockets performance")
+6. WebSearch("SSE browser support")
+
+**Step 3:** Synthesize findings
+- Reword all technical claims
+- Keep quotes under 15-20 words
+- Note differences, not copy descriptions
+
+**Step 4:** Cite sources
+```
+<cite index="1,3">WebSockets provide full-duplex communication channels</cite>,
+enabling bidirectional data flow between client and server. In contrast,
+<cite index="2,4">Server-Sent Events offer unidirectional updates from server to client</cite>,
+which suffices for many notification scenarios.
+```
+
+**Step 5:** List sources
+```
+Sources:
+1. MDN Web Docs - WebSocket API
+2. HTML5 Rocks - Server-Sent Events
+3. Ably.com - WebSocket vs SSE Comparison
+4. Can I Use - SSE Browser Support
+```
+
+---
+
+## Recommendations
+
+1. **Create `/research` command** with complexity detection
+2. **Add `research-specialist` agent** for spawning in tasks
+3. **Integrate with task system** to auto-detect research needs
+4. **Add citation validation** to ensure `<cite>` tags present
+5. **Monitor token usage** to optimize search count
+
+**Priority:** High - This is production-proven methodology from Anthropic
+**Effort:** Medium (~3-4 hours implementation + testing)
+**Impact:** Enables high-quality research for tasks, documentation, planning
+
+---
+
+**Extracted:** 2025-12-05
+**Source:** Claude.ai Desktop leaked prompt (search_instructions section)
+**Application:** `/research` command + research-specialist agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudetools/tools",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Persistent AI memory, task management, and codebase intelligence for Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,8 @@
   },
   "files": [
     "dist",
+    "docs",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
@@ -19,7 +21,12 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "codedna:monitor": "tsx -e \"import { runMonitoring } from './src/helpers/codedna-monitoring.js'; runMonitoring()\"",
+    "codedna:analytics": "tsx -e \"import { weeklyAnalyticsSummary } from './src/helpers/usage-analytics.js'; weeklyAnalyticsSummary()\"",
+    "codedna:analytics:24h": "tsx -e \"import { getLast24HoursAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast24HoursAnalytics(); printAnalytics(r, 'Last 24 Hours')\"",
+    "codedna:analytics:30d": "tsx -e \"import { getLast30DaysAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast30DaysAnalytics(); printAnalytics(r, 'Last 30 Days')\"",
+    "prompt:verify": "scripts/verify-prompt-compliance.sh"
   },
   "repository": {
     "type": "git",
@@ -35,7 +42,9 @@
     "context",
     "temporal",
     "tasks",
-    "codebase"
+    "codebase",
+    "prompt-engineering",
+    "10/10-framework"
   ],
   "author": "ClaudeTools <hello@claudetools.dev>",
   "license": "MIT",

package/scripts/verify-prompt-compliance.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# Prompt Compliance Verification Script
+# Verifies prompts follow 10/10 AI System Prompt Architecture framework
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Counters
+PASSED=0
+FAILED=0
+WARNINGS=0
+
+echo "🔍 10/10 Framework Prompt Compliance Checker"
+echo "============================================="
+echo ""
+
+# Function to check if file has required XML tags
+check_xml_structure() {
+    local file=$1
+    local tier=$2
+    local errors=0
+
+    echo "Checking: $file"
+
+    # Layer 1: Identity (required in all tiers)
+    if ! grep -q "<identity>" "$file"; then
+        echo -e "${RED}  ✗ Missing <identity> tag (Layer 1)${NC}"
+        ((errors++))
+    else
+        echo -e "${GREEN}  ✓ Has <identity> tag${NC}"
+    fi
+
+    # Layer 2: Behavioral Guidelines (required in all tiers)
+    if ! grep -q "<behavioral_guidelines>" "$file"; then
+        echo -e "${RED}  ✗ Missing <behavioral_guidelines> tag (Layer 2)${NC}"
+        ((errors++))
+    else
+        echo -e "${GREEN}  ✓ Has <behavioral_guidelines> tag${NC}"
+    fi
+
+    # Layer 3: Standards (required in all tiers)
+    if ! grep -q "<standards>" "$file"; then
+        echo -e "${RED}  ✗ Missing <standards> tag (Layer 3)${NC}"
+        ((errors++))
+    else
+        echo -e "${GREEN}  ✓ Has <standards> tag${NC}"
+    fi
+
+    # Layer 4: Domain Knowledge (required in Standard+)
+    if [[ "$tier" != "minimal" ]]; then
+        if ! grep -q "<domain_knowledge>" "$file"; then
+            echo -e "${RED}  ✗ Missing <domain_knowledge> tag (Layer 4) - required for $tier tier${NC}"
+            ((errors++))
+        else
+            echo -e "${GREEN}  ✓ Has <domain_knowledge> tag${NC}"
+        fi
+    fi
+
+    # Layer 5: Cross-Cutting Concerns (required in Professional+)
+    if [[ "$tier" == "professional" || "$tier" == "enterprise" ]]; then
+        if ! grep -q "<cross_cutting_concerns>" "$file"; then
+            echo -e "${RED}  ✗ Missing <cross_cutting_concerns> tag (Layer 5) - required for $tier tier${NC}"
+            ((errors++))
+        else
+            echo -e "${GREEN}  ✓ Has <cross_cutting_concerns> tag${NC}"
+        fi
+    fi
+
+    # Layer 6: Reference Library (required in Enterprise only)
+    if [[ "$tier" == "enterprise" ]]; then
+        if ! grep -q "<reference_library>" "$file"; then
+            echo -e "${RED}  ✗ Missing <reference_library> tag (Layer 6) - required for enterprise tier${NC}"
+            ((errors++))
+        else
+            echo -e "${GREEN}  ✓ Has <reference_library> tag${NC}"
+        fi
+    fi
+
+    # Layer 7: User Input (required in all tiers)
+    if ! grep -q "<user_input>" "$file"; then
+        echo -e "${RED}  ✗ Missing <user_input> tag (Layer 7)${NC}"
+        ((errors++))
+    else
+        echo -e "${GREEN}  ✓ Has <user_input> tag${NC}"
+    fi
+
+    # Check for priority markers
+    if ! grep -Eq "(CRITICAL|MANDATORY|PRIORITY|IMPORTANT)" "$file"; then
+        echo -e "${YELLOW}  ⚠ No priority markers found (CRITICAL/MANDATORY/PRIORITY/IMPORTANT)${NC}"
+        ((WARNINGS++))
+    else
+        echo -e "${GREEN}  ✓ Has priority markers${NC}"
+    fi
+
+    echo ""
+    return $errors
+}
+
+# Check tier-specific token budgets
+check_token_budget() {
+    local file=$1
+    local tier=$2
+    local line_count=$(wc -l < "$file")
+    local approx_tokens=$((line_count * 3)) # Rough estimate: ~3 tokens per line
+
+    case $tier in
+        minimal)
+            if [ $approx_tokens -gt 600 ]; then
+                echo -e "${YELLOW}  ⚠ Estimated $approx_tokens tokens (target: ~500 for minimal tier)${NC}"
+                ((WARNINGS++))
+            else
+                echo -e "${GREEN}  ✓ Token budget OK (~$approx_tokens tokens)${NC}"
+            fi
+            ;;
+        standard)
+            if [ $approx_tokens -gt 2500 ]; then
+                echo -e "${YELLOW}  ⚠ Estimated $approx_tokens tokens (target: ~2000 for standard tier)${NC}"
+                ((WARNINGS++))
+            else
+                echo -e "${GREEN}  ✓ Token budget OK (~$approx_tokens tokens)${NC}"
+            fi
+            ;;
+        professional)
+            if [ $approx_tokens -gt 6000 ]; then
+                echo -e "${YELLOW}  ⚠ Estimated $approx_tokens tokens (target: ~5000 for professional tier)${NC}"
+                ((WARNINGS++))
+            else
+                echo -e "${GREEN}  ✓ Token budget OK (~$approx_tokens tokens)${NC}"
+            fi
+            ;;
+    esac
+    echo ""
+}
+
+# Main verification
+echo "Verifying updated prompts..."
+echo ""
+
+# Context detection agents (Minimal tier)
+echo "=== Minimal Tier Agents ==="
+for file in ~/.claude/agents/context-signal-detector.md ~/.claude/agents/context-template-selector.md; do
+    if [ -f "$file" ]; then
+        if check_xml_structure "$file" "minimal"; then
+            check_token_budget "$file" "minimal"
+            ((PASSED++))
+        else
+            ((FAILED++))
+        fi
+    fi
+done
+
+# Commands (Standard tier)
+echo "=== Standard Tier Commands ==="
+for file in ~/.claude/commands/tasks.md ~/.claude/commands/work.md ~/.claude/commands/research.md; do
+    if [ -f "$file" ]; then
+        if check_xml_structure "$file" "standard"; then
+            check_token_budget "$file" "standard"
+            ((PASSED++))
+        else
+            ((FAILED++))
+        fi
+    fi
+done
+
+# Planning command (Professional tier)
+echo "=== Professional Tier Commands ==="
+for file in ~/.claude/commands/plan.md; do
+    if [ -f "$file" ]; then
+        if check_xml_structure "$file" "professional"; then
+            check_token_budget "$file" "professional"
+            ((PASSED++))
+        else
+            ((FAILED++))
+        fi
+    fi
+done
+
+# Summary
+echo "============================================="
+echo "Summary:"
+echo -e "${GREEN}Passed: $PASSED${NC}"
+echo -e "${RED}Failed: $FAILED${NC}"
+echo -e "${YELLOW}Warnings: $WARNINGS${NC}"
+echo ""
+
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}✓ All prompts are compliant with 10/10 framework!${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ Some prompts need attention${NC}"
+    exit 1
+fi