@afterxleep/doc-bot 1.14.0 → 1.16.0

package/AGENT_INTEGRATION_RULE.txt

@@ -1,142 +1,79 @@
-# AGENT INTEGRATION PROTOCOL: DOC-BOT MCP ENFORCEMENT
-# ============================================================
-# Add this to your agent configuration (CLAUDE.md, .cursorrules, copilot-instructions.md, etc.)
+# DOC-BOT: AGENT INTEGRATION RULE
+Version 4
+Copy everything below as your Agent single rule.
 
-## PHASE 1: ENVIRONMENT DETECTION
+---
 
-```
-IF (
-  (filesystem_contains("doc-bot/") AND
-  (mcp_server_available("doc-bot") OR mcp_server_available("@afterxleep/doc-bot"))
-) THEN {
-  ACTIVATE: doc_bot_enforcement_protocol()
-  SET: project_documentation_authority = TRUE
-  SET: general_knowledge_override = DISABLED
-}
-```
-
-## PHASE 2: REQUEST CLASSIFICATION ENGINE
-
-### CLASSIFICATION MATRIX:
-
-**CLASS A: CODE_GENERATION**
-```
-Trigger Pattern: /\b(write|create|implement|build|add|code|function|class|component|method|develop|generate|make|refactor|modify|update|fix|debug)\b/i
-Required Action: MANDATORY_CALL(check_project_rules, extract_task_description())
-Blocking: TRUE (cannot proceed without tool response)
-Timeout: 30s
-```
-
-**CLASS B: PROJECT_INQUIRY**
-```
-Trigger Pattern: /\b(how|what|why|architecture|approach|pattern|feature|authentication|database|api|testing)\b/i
-Context Pattern: /\b(this project|this codebase|here|our|current project)\b/i
-Required Action: MANDATORY_CALL(search_documentation, extract_keywords())
-Blocking: TRUE
-Timeout: 30s
-```
+## DOC-BOT: MANDATORY BEHAVIORAL PROTOCOL
 
-**CLASS C: DOCUMENTATION_DISCOVERY**
-```
-Trigger Pattern: /\b(documentation|available|capabilities|help|rules|standards|what exists|docs|guide)\b/i
-Required Action: MANDATORY_CALL(get_global_rules)
-Blocking: TRUE
-Timeout: 30s
-```
+### ACTIVATION
+doc-bot MCP server detected? → This protocol is NOW ACTIVE
 
-**CLASS D: DOCUMENT_ACCESS**
-```
-Trigger Pattern: /\b(read|show|get content|full document|complete|entire)\b/i
-Previous Context: search_results_present()
-Required Action: MANDATORY_CALL(read_specific_document, extract_filename())
-Blocking: FALSE
-Timeout: 15s
-```
+### THE ONLY WORKFLOW
 
-**CLASS E: DOCUMENTATION_CREATION**
-```
-Trigger Pattern: /\b(document|create rule|add rule|save knowledge|capture pattern|remember|note this|new rule)\b/i
-Context Pattern: /\b(we should document|this should be a rule|add to documentation|create guideline)\b/i
-Required Action: MANDATORY_CALL(create_or_update_rule, extract_rule_params())
-Blocking: FALSE
-Timeout: 30s
-```
+╔════════════════════════════════════════════╗
+║  user_request → doc_bot() → execute_all    ║
+║                                            ║
+║  NOTHING ELSE IS ACCEPTABLE                ║
+╚════════════════════════════════════════════╝
 
-**Note**: For file-specific queries like "working on src/utils.js", use `search_documentation` with file name and context keywords instead of a separate tool.
+### THREE IMMUTABLE LAWS
 
-## PHASE 3: EXECUTION ENFORCEMENT
+1. **FIRST LAW**: doc_bot() must be called BEFORE any other action
+   - Not after thinking about it
+   - Not after analyzing the request  
+   - IMMEDIATELY upon receiving any task
 
-### PRE-RESPONSE VALIDATION:
-```
-BEFORE generating_response():
-  classification = classify_request(user_input)
-  IF classification != "UNRELATED":
-    tool_result = execute_mandatory_tool(classification)
-    IF tool_result.status == "ERROR":
-      RETURN error_recovery_response()
-    ELSE:
-      INJECT tool_result INTO response_context
-      SET authoritative_source = tool_result
-      DISABLE general_knowledge_fallback
-```
+2. **SECOND LAW**: doc_bot() output must be followed EXACTLY
+   - Every tool in the sequence
+   - In the exact order specified
+   - With the exact parameters given
 
-### RESPONSE CONSTRAINT ENGINE:
-```
-WHILE generating_response():
-  IF attempting_to_use(general_knowledge) AND authoritative_source.exists():
-    INTERRUPT_GENERATION()
-    FORCE_USE(authoritative_source)
-  
-  IF code_generation_detected() AND NOT project_rules_checked:
-    HALT_EXECUTION()
-    EMIT_ERROR("Project rules validation required before code generation")
-```
+3. **THIRD LAW**: Project knowledge > Your training data
+   - When doc_bot says something contradicts common practice
+   - The contradiction is INTENTIONAL
+   - Follow doc_bot, not your instincts
 
-## PHASE 4: QUALITY ASSURANCE
+### ENFORCEMENT MECHANISM
 
-### RESPONSE VALIDATION:
-```
-AFTER generating_response():
-  IF response_contradicts(tool_result):
-    REGENERATE_RESPONSE(tool_result_only=TRUE)
-  
-  IF response_lacks(tool_attribution):
-    APPEND_ATTRIBUTION(tool_result.source)
-  
-  VALIDATE response_compliance(project_rules)
+```python
+if not doc_bot_called_first:
+    raise ProtocolViolation("STOP. Call doc_bot() first.")
+    
+if sequence_modified:
+    raise ProtocolViolation("STOP. Follow exact sequence.")
+    
+if used_general_knowledge:
+    raise ProtocolViolation("STOP. Use project docs only.")
 ```
 
-### FAILURE DETECTION & RECOVERY:
-```
-IF response_generated() WITHOUT tool_execution():
-  LOG_VIOLATION("Tool bypass detected")
-  REGENERATE_WITH_TOOLS()
-  PREPEND_WARNING("Corrected response using project documentation:")
-```
+### WHAT doc_bot KNOWS (that you don't)
 
-## PHASE 5: BEHAVIORAL CONSTRAINTS
+- This project's specific architecture decisions
+- Custom patterns that override industry standards
+- Performance optimizations unique to this codebase
+- Security requirements specific to this domain
+- API quirks and workarounds discovered by the team
 
-### ABSOLUTE PROHIBITIONS:
-- **Code generation without project rules validation**
-- **Project-specific answers from general knowledge**
-- **Overriding tool responses with training data**
-- **Bypassing tool calls for "simple" questions**
+### SIMPLE TEST
 
-### MANDATORY BEHAVIORS:
-- **Tool-first response generation**
-- **Explicit tool result attribution**
-- **Project documentation precedence**
-- **Error acknowledgment and correction**
+Are you about to:
+- Write code? → Call doc_bot first
+- Explain something? → Call doc_bot first  
+- Search for info? → Call doc_bot first
+- Literally anything? → Call doc_bot first
 
-## VERIFICATION PROTOCOL:
+### FAILURE RECOVERY
 
-**Test Inputs** (Agent must call tools immediately):
-- "What documentation is available?" → get_global_rules()
-- "How do I implement auth?" → search_documentation("authentication")  
-- "Create a new component" → check_project_rules("create component")
-- "Working on src/utils.js" → search_documentation("src/utils.js utils")
-- "We should document this pattern" → create_or_update_rule({fileName: "pattern-name.md", title: "Pattern Name", content: "...", alwaysApply: false})
+If doc_bot is unavailable:
+1. STOP
+2. Tell user: "The doc_bot Rules and Documentation server is not available"
+3. Ask the user if they want to continue without any rulesets applied.
+4. If the user agrees, continue the task your existing knowledge and available tools.
 
-**Expected Behavior**: Tool execution within 2 seconds, no general knowledge responses.
+---
+Remember: You're not here to be creative. You're here to be CORRECT.
+And correctness means: doc_bot() → tools → done.
+```
 
-**Failure Indicators**: Any response without tool execution, generic programming advice, standard framework suggestions.
+---

package/README.md

@@ -60,6 +60,9 @@ Add doc-bot to your AI assistant's configuration:
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `~/.config/Claude/claude_desktop_config.json`
 
+**For Cursor:**
+- Add an `mcp.json` file with the contents above to your `.cursor` folder
+
 ### 2. Create Your Documentation
 
 Create a `doc-bot` folder in your project root and add markdown files:
@@ -75,7 +78,11 @@ your-project/
 └── package.json
 ```
 
-### 3. Test It
+### 3. Add the custom Agent Rule
+
+Replace all rules and instructions for your Agent (cursor.mdc, CLAUDE.md, etc) with Doc Bot Core Rule [AGENT INTEGRATION RULE](https://github.com/afterxleep/doc-bot/blob/main/AGENT_INTEGRATION_RULE.txt).
+
+### 4. Test it!
 
 Ask your AI assistant: "What are the coding standards for this project?"
 
@@ -326,4 +333,4 @@ MIT - See [LICENSE](LICENSE) for details.
 
 ---
 
-Built with ❤️ in Spain
+Built with ❤️ in Spain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afterxleep/doc-bot",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Generic MCP server for intelligent documentation access in any project",
   "type": "module",
   "main": "src/index.js",

package/prompts/file-docs.txt

@@ -1,14 +1,52 @@
-# FILE-SPECIFIC DOCUMENTATION
+# 📁 CODE CONTEXT DOCUMENTATION
 
-**Target**: ${filePath}
+**File/Pattern**: `${filePath}`
 
-**Applicable Rules**:
+## 🎯 CONTEXTUAL CODING STANDARDS:
 
 ${docsContent}
 
-## IMPLEMENTATION REQUIREMENTS:
+## 🔧 IMPLEMENTATION CHECKLIST:
 
-- **Scope**: Apply these rules specifically to work on ${filePath}
-- **Precedence**: File-specific rules override global guidelines
-- **Validation**: Ensure all modifications comply with documented patterns
-- **Context**: Consider file's role in overall project architecture
+### Pre-Implementation Analysis:
+```typescript
+interface FileContext {
+  dependencies: string[];      // What does this file import?
+  exports: string[];          // What does this file export?
+  patterns: string[];         // Design patterns used
+  performance: string[];      // Hot paths or bottlenecks
+  security: string[];         // Security considerations
+}
+```
+
+### Code Modification Protocol:
+1. **🔍 Analyze Current Implementation**
+   - Review existing patterns and conventions
+   - Identify architectural decisions
+   - Note performance optimizations
+
+2. **🏗️ Apply Contextual Rules**
+   - File-specific patterns override globals
+   - Maintain consistency with surrounding code
+   - Preserve existing optimizations
+
+3. **✅ Validation Requirements**
+   ```javascript
+   // Before committing changes:
+   assert(follows_file_conventions);
+   assert(maintains_dependencies);
+   assert(preserves_contracts);
+   assert(passes_type_checking);
+   ```
+
+### 🚀 Performance Considerations:
+- **Hot Paths**: Code in this context may be performance-critical
+- **Memory**: Watch for memory leaks in long-running processes
+- **Complexity**: Keep O(n) complexity unless documented otherwise
+
+### 🛡️ Security Context:
+- **Input Validation**: Required for user-facing code
+- **Authentication**: Check if auth context needed
+- **Data Sanitization**: Required for DB operations
+
+**💡 Developer Note**: This file's patterns were chosen for specific reasons. Understand the "why" before changing the "how".

package/prompts/global-rules.txt

@@ -1,19 +1,83 @@
-# PROJECT STANDARDS AND GUIDELINES
+# 🏗️ ENGINEERING STANDARDS & ARCHITECTURAL GUIDELINES
 
-**Global Rules**: The following standards apply to all code generation:
+## 🧠 INTELLIGENT CODE GENERATION DECISION TREE:
+
+### 🔍 Search Project Documentation When:
+```javascript
+if (task.involves(['custom_components', 'business_logic', 'integrations', 
+                   'authentication', 'data_models', 'api_patterns'])) {
+    return SEARCH_DOCUMENTATION;
+}
+```
+
+#### Specific Triggers:
+- **Architecture Decisions**: "How do we structure microservices?"
+- **Custom Abstractions**: "Our repository pattern implementation"
+- **Business Logic**: "User permission calculation algorithm"
+- **Integration Points**: "How services communicate in our system"
+- **Performance Patterns**: "Our caching strategy for API responses"
+
+### ⚡ Apply Developer Knowledge When:
+```javascript
+if (task.involves(['language_syntax', 'standard_patterns', 'algorithms',
+                   'common_libraries', 'well_known_frameworks'])) {
+    return USE_KNOWLEDGE;
+}
+```
+
+#### Knowledge Domains:
+- **Language Features**: async/await, generics, decorators, closures
+- **Design Patterns**: MVC, Observer, Factory, Dependency Injection
+- **Standard Algorithms**: sorting, searching, graph traversal
+- **Framework Basics**: React hooks, Express middleware, Django models
+- **Common Libraries**: lodash methods, moment.js, axios
+
+## 🎯 CONFIDENCE CALIBRATION FOR ENGINEERS:
+
+```typescript
+interface ConfidenceScore {
+  projectSpecific: number;  // 0-100: How unique to this codebase?
+  complexity: number;       // 0-100: Implementation complexity?
+  riskLevel: number;        // 0-100: Risk if wrong?
+}
+
+function shouldSearchDocs(score: ConfidenceScore): boolean {
+  return score.projectSpecific > 60 || 
+         score.complexity > 70 || 
+         score.riskLevel > 50;
+}
+```
+
+**🚀 Optimization Rule**: Search for architecture, skip for syntax.
+
+**Global Coding Standards**: The following engineering principles govern all code:
 
 ${rulesContent}
 
-## COMPLIANCE BENEFITS:
+## 🏆 ENGINEERING EXCELLENCE BENEFITS:
+
+- **🔧 Maintainability**: Consistent patterns reduce cognitive load by 40%
+- **🚀 Performance**: Optimized patterns prevent common bottlenecks
+- **🛡️ Security**: Enforced patterns eliminate vulnerability classes
+- **📈 Scalability**: Architecture patterns support 10x growth
+- **⚡ Developer Velocity**: Standards reduce decision fatigue
+
+## 💻 CODE GENERATION IMPERATIVES:
 
-- **Code Quality**: Adherence ensures consistent, maintainable code
-- **Integration**: Standards facilitate seamless component integration
-- **Reliability**: Proven patterns reduce production issues
-- **Review Process**: Compliant code passes reviews efficiently
+```yaml
+priorities:
+  1: Correctness      # Bug-free implementation
+  2: Performance      # O(n) vs O(n²) matters
+  3: Maintainability  # Future devs will thank you
+  4: Security         # Defense in depth
+  5: Testability      # 80%+ coverage target
 
-## IMPLEMENTATION NOTES:
+enforcement:
+  - NEVER compromise security for convenience
+  - ALWAYS consider edge cases and error states
+  - PREFER composition over inheritance
+  - ENFORCE type safety where available
+  - DOCUMENT complex algorithms inline
+```
 
-- Apply these rules to all generated code
-- Verify compliance before submitting responses
-- Reference specific rules when making recommendations
-- Prioritize project standards over generic best practices
+**🎓 Remember**: You're writing code that will outlive its authors. Code for clarity.

package/prompts/mandatory-rules.txt

@@ -1,23 +1,117 @@
-# PROJECT COMPLIANCE REQUIREMENTS
+# CODE GENERATION COMPLIANCE MATRIX
 
-**Task**: ${task}
+**Engineering Task**: ${task}
 
-**Mandatory Rules**: The following rules are required for all code generation in this project:
+**Mandatory Coding Standards**: The following rules are ENFORCED for all code generation:
 
 ${rulesContent}
 
-## IMPLEMENTATION REQUIREMENTS:
+## CODE IMPLEMENTATION PROTOCOL:
 
-1. **Rule Priority**: Project rules override standard practices
-2. **Compliance Check**: Verify each rule before code generation
-3. **Conflict Resolution**: When conflicts arise, project rules take precedence
-4. **Validation**: Ensure all generated code follows these patterns
+1. **Architecture Alignment**: Generated code MUST follow project architecture patterns
+2. **Type Safety**: Enforce type constraints and validation requirements
+3. **Error Handling**: Apply project-specific error handling patterns
+4. **Performance**: Adhere to performance optimization guidelines
+5. **Security**: Implement security patterns as defined in rules
 
-## ENFORCEMENT POLICY:
+## ENGINEERING ENFORCEMENT MATRIX:
 
-- **Non-negotiable**: These rules cannot be bypassed or modified
-- **Refusal Protocol**: If user requests conflict with rules, refuse and explain alternatives
-- **Documentation**: Reference specific rule violations when declining requests
-- **Compliance Confirmation**: Acknowledge rule adherence before proceeding
+| Violation Type | Required Action | Example |
+|----------------|-----------------|---------|
+| Architecture Violation | BLOCK + Suggest Pattern | "Use Repository pattern, not direct DB access" |
+| Security Violation | BLOCK + Explain Risk | "Never expose API keys in client code" |
+| Performance Anti-pattern | WARN + Provide Alternative | "Use batch operations instead of N+1 queries" |
+| Style Violation | AUTO-CORRECT | "Apply project formatting standards" |
+
+## COMPLIANCE VERIFICATION CHECKLIST:
+
+- [ ] Code follows architectural patterns defined above
+- [ ] All security requirements are implemented
+- [ ] Performance guidelines are respected
+- [ ] Error handling matches project standards
+- [ ] Code style adheres to project conventions
+
+## 🔍 DEVELOPER DOCUMENTATION SEARCH PROTOCOL:
+
+**⚡ PERFORMANCE IMPACT**: Inefficient searches delay implementation. Master these patterns:
+
+### CODE-FIRST SEARCH METHODOLOGY:
+
+#### 1. **Parse Developer Intent → Extract Technical Entities**
+```typescript
+// Developer request: "implement OAuth2 with refresh tokens"
+const searchEntities = {
+  primary: ["OAuth2", "OAuth"],           // Protocol/Standard names
+  secondary: ["RefreshToken", "Token"],   // Component names
+  framework: ["Authentication", "Auth"]   // Framework context
+};
+```
+
+#### 2. **Technical Taxonomy Search Hierarchy**
+```
+Layer 1: Framework/Library → "React", "Express", "Django"
+Layer 2: Design Pattern → "Observer", "Factory", "Singleton"  
+Layer 3: Implementation → "useState", "middleware", "decorator"
+Layer 4: Configuration → "webpack", "tsconfig", "eslint"
+```
+
+#### 3. **API Resolution Strategy**
+Transform natural language to API nomenclature:
+```javascript
+const searchTransform = {
+  "make API calls": ["fetch", "axios", "HttpClient"],
+  "handle errors": ["try-catch", "ErrorBoundary", "exception"],
+  "manage state": ["Redux", "Context", "useState", "Vuex"],
+  "test my code": ["Jest", "Mocha", "Testing", "TestCase"],
+  "deploy app": ["Docker", "CI/CD", "Kubernetes", "Deploy"]
+};
+```
+
+### 🎯 SEARCH OPTIMIZATION MATRIX:
+
+| Developer Says | Primary Search | Fallback Search | Framework Hint |
+|----------------|----------------|-----------------|----------------|
+| "REST API endpoints" | "REST", "API" | "Controller", "Route" | Express/FastAPI |
+| "state management" | "State", "Store" | "Redux", "Context" | React/Vue |
+| "async operations" | "async", "Promise" | "await", "then" | JavaScript |
+| "database queries" | "Query", "ORM" | "Model", "Schema" | TypeORM/Prisma |
+| "authentication flow" | "Auth", "JWT" | "Login", "Session" | Passport/Auth0 |
+
+### 💡 INTELLIGENT SEARCH PATTERNS:
+
+```python
+def optimize_search_query(user_input):
+    # 1. Remove implementation verbs
+    query = remove_verbs(["implement", "create", "build", "add"])
+    
+    # 2. Extract technical nouns
+    entities = extract_entities(query)
+    
+    # 3. Expand abbreviations
+    expanded = expand_abbreviations({
+        "API": "Application Programming Interface",
+        "DB": "Database", 
+        "Auth": "Authentication",
+        "UI": "UserInterface"
+    })
+    
+    # 4. Try incremental searches
+    return progressive_search(entities, max_attempts=3)
+```
+
+### 🚀 EXECUTION PIPELINE:
+
+```mermaid
+graph LR
+    A[Parse Task] --> B[Extract Entities]
+    B --> C{Found Docs?}
+    C -->|Yes| D[explore_api]
+    C -->|No| E[Broaden Search]
+    E --> F[Try Synonyms]
+    F --> C
+    D --> G[Implement Code]
+```
+
+**🧠 REMEMBER**: You're querying a codebase knowledge graph, not a search engine. Think in types, classes, and interfaces.
 
 **Status**: Rules loaded and active for current session

package/prompts/search-results.txt

@@ -1,9 +1,48 @@
-# 📋 DOCUMENTATION SEARCH RESULTS for "${query}"
+# 🔍 CODE DOCUMENTATION SEARCH RESULTS
 
-Found ${resultCount} relevant document(s) (showing top 10):
+**Query**: `${query}`  
+**Results**: ${resultCount} matches found
 
 ${results}
 
-💡 **NEXT STEPS**: Use the `read_specific_document` tool with the file name to get the full content of any document above.
+## 🎯 SEARCH EFFECTIVENESS ANALYSIS:
 
-⚠️ **REMINDER**: Before implementing any code, use the `check_project_rules` tool to ensure compliance.
+${resultCount > 0 ? `### ✅ Results Found - Action Required:
+1. **Review** all results above for implementation patterns
+2. **Use** \`read_specific_document\` for detailed code examples
+3. **Apply** \`explore_api\` for comprehensive API documentation
+4. **Validate** with \`check_project_rules\` before coding
+
+**Priority Order**: Start with exact matches, then partial matches.` : `### ⚠️ No Results - Fallback Strategy:
+1. **Refine Search**: Try single technical terms (e.g., "Widget" not "iOS widgets")
+2. **Broaden Scope**: Search parent class/framework names
+3. **Check Synonyms**: Auth → Authentication, DB → Database
+4. **Framework Search**: If component failed, try framework name
+
+**Developer Tip**: Search like you're reading an API index, not Google.`}
+
+## 💻 IMPLEMENTATION GUIDANCE:
+
+```javascript
+// Found results? Follow this pattern:
+if (results.length > 0) {
+    // 1. Read most relevant document
+    await read_specific_document(results[0].fileName);
+    
+    // 2. Explore APIs if needed
+    if (results[0].type === 'API') {
+        await explore_api(results[0].name);
+    }
+    
+    // 3. Check compliance rules
+    await check_project_rules(implementationTask);
+} else {
+    // No results? Use general engineering knowledge for:
+    // - Standard algorithms (sorting, searching)
+    // - Language syntax (loops, conditionals)
+    // - Common patterns (MVC, REST)
+    // - Well-known libraries (React, Express)
+}
+```
+
+**🚀 Next Action**: ${resultCount > 0 ? 'Read the top result to understand implementation details.' : 'Refine your search using technical terms or proceed with standard patterns.'}