@vfarcic/dot-ai 0.36.0 → 0.38.0

package/README.md

@@ -6,7 +6,7 @@
 
 </div>
 
-DevOps AI Toolkit provides two powerful AI-driven capabilities: **Kubernetes deployment recommendations** that discover your cluster's capabilities and suggest optimal deployment approaches, and **automated documentation testing** that validates documentation accuracy by executing commands and testing examples.
+DevOps AI Toolkit provides three powerful AI-driven capabilities: **Kubernetes deployment recommendations** that discover your cluster's capabilities and suggest optimal deployment approaches, **automated documentation testing** that validates documentation accuracy by executing commands and testing examples, and **shared prompts library** that enables centralized prompt sharing via native slash commands across development teams.
 
 ## Who is this for?
 
@@ -19,8 +19,13 @@ DevOps AI Toolkit provides two powerful AI-driven capabilities: **Kubernetes dep
 - **Technical Writers**: Identify which sections need updates and prioritize work effectively
 - **Open Source Maintainers**: Ensure documentation works correctly for new contributors
 
+### Shared Prompts Library
+- **Development Teams**: Share proven prompts across projects without file management
+- **Project Managers**: Standardize workflows with consistent prompt usage across teams
+- **Individual Developers**: Access curated prompt library via native slash commands
+
 ### AI Integration
-- **AI Agents**: Integrate both capabilities with Claude Code, Cursor, or VS Code for conversational workflows
+- **AI Agents**: Integrate all capabilities with Claude Code, Cursor, or VS Code for conversational workflows
 
 ## Key Features
 
@@ -36,19 +41,31 @@ DevOps AI Toolkit provides two powerful AI-driven capabilities: **Kubernetes dep
 🛠️ **Fix Application**: User-driven selection and application of recommended documentation improvements  
 💾 **Session Management**: Resumable testing workflows for large documentation sets
 
+### Shared Prompts Library
+🎯 **Native Slash Commands**: Prompts appear as `/dot-ai:prompt-name` in your coding agent  
+📚 **Curated Library**: Access proven prompts for code review, documentation, architecture, and project management  
+🔄 **Zero Setup**: Connect to MCP server and prompts are immediately available across all projects  
+🤝 **Team Consistency**: Standardized prompt usage with centralized management
+
 ### AI Integration
 ⚡ **MCP Integration**: Works seamlessly with Claude Code, Cursor, or VS Code through Model Context Protocol  
-🤖 **Conversational Interface**: Natural language interaction for both deployment and documentation testing workflows
+🤖 **Conversational Interface**: Natural language interaction for deployment, documentation testing, and shared prompt workflows
+
+**Setup Required**: See the [MCP Setup Guide](./docs/mcp-setup.md) for complete configuration instructions.
 
 ## Quick Start
 
 ### Prerequisites
 
-**For both features:**
+**For Kubernetes deployment and documentation testing:**
 - **Claude API key** (required for AI analysis)
-  - Get your API key from [Anthropic Console](https://console.anthropic.com/)
+  - Get your API key from [Anthropic Console](https://console.anthropic.com/) (requires account login)
+  <!-- dotai-ignore: Console URL may return 403 - expected behavior for auth-protected endpoint -->
   - Set it as environment variable: `export ANTHROPIC_API_KEY=your_api_key_here`
 
+**For shared prompts library:**
+- **No API key required** - Works with any MCP-enabled coding agent
+
 **For Kubernetes deployment recommendations:**
 - **kubectl** configured with cluster access
   - Verify cluster access with: `kubectl get nodes`
@@ -63,12 +80,13 @@ DevOps AI Toolkit provides two powerful AI-driven capabilities: **Kubernetes dep
 
 DevOps AI Toolkit is designed to be used through AI development tools via MCP (Model Context Protocol). No direct installation needed - simply configure your AI tool to connect to the MCP server.
 
-### Choose Your Usage Path
+### Usage
 
-#### Option A: AI Agent Integration (Claude Code Example)
-Perfect for conversational deployments with AI agents:
+**AI Agent Integration (Claude Code Example)**
+Perfect for conversational AI-driven workflows:
 
 1. **Create `.mcp.json` in your project:**
+<!-- dotai-ignore: MCP server binary (dot-ai-mcp) not testable as CLI - only works through MCP client connections -->
 ```json
 {
   "mcpServers": {
@@ -96,6 +114,9 @@ Perfect for conversational deployments with AI agents:
 mkdir -p tmp/sessions
 
 claude
+
+# Verify MCP server connection
+# You should see "dot-ai" listed as an available MCP server
 ```
 
 3. **Use conversational workflows:**
@@ -138,6 +159,24 @@ User: Fix the port number directly in the doc, and I'll create a GitHub issue fo
 Agent: ✅ Documentation testing complete! Fixed 1 issue directly, 1 issue tracked externally.
 ```
 
+*Note: Conversational examples are illustrative - actual AI responses will vary based on specific context and implementation.*
+
+**Example: Shared Prompts Library**
+```
+# Conversational approach
+User: I want to create a new PRD for a feature
+
+Agent: I'll help you create a documentation-first PRD. Let me start the process.
+[Uses prd-create prompt via /dot-ai:prd-create]
+
+Agent: Great! I've created GitHub issue #34 and the PRD file. What feature would you like to document?
+
+# Direct slash command approach  
+User: /dot-ai:prd-create
+
+Agent: I'm executing the PRD creation workflow. Please describe the feature you want to create a PRD for...
+```
+
 📖 **[Complete MCP Setup Guide →](docs/mcp-setup.md)** - Detailed configuration, troubleshooting, and examples
 
 
@@ -147,7 +186,7 @@ Agent: ✅ Documentation testing complete! Fixed 1 issue directly, 1 issue track
 ### MCP Issues
 
 **MCP server won't start:**
-- Verify environment variables are set in `.mcp.json`
+- Verify environment variables are correctly configured in `.mcp.json` env section
 - Check session directory exists and is writable
 - Ensure `ANTHROPIC_API_KEY` is valid
 
@@ -162,6 +201,7 @@ Agent: ✅ Documentation testing complete! Fixed 1 issue directly, 1 issue track
 - **[MCP Setup Guide](docs/mcp-setup.md)** - AI tools integration (Claude Code, Cursor)
 - **[MCP Recommendation Guide](docs/mcp-recommendation-guide.md)** - Kubernetes deployment recommendations  
 - **[MCP Documentation Testing Guide](docs/mcp-documentation-testing-guide.md)** - Automated documentation validation
+- **[MCP Prompts Guide](docs/mcp-prompts-guide.md)** - Shared prompt library and slash commands
 
 ### 👩‍💻 Development  
 - **[API Reference](docs/API.md)** - TypeScript interfaces and programmatic usage
@@ -169,17 +209,12 @@ Agent: ✅ Documentation testing complete! Fixed 1 issue directly, 1 issue track
 
 ### 🏗️ Architecture
 - **[Design Overview](docs/design.md)** - Technical design and principles  
-- **[Stage-Based API](docs/STAGE_BASED_API.md)** - Workflow stages and API design
 - **[Discovery Engine](docs/discovery-engine.md)** - Cluster resource discovery
 
 ### 🤖 AI & Integration
 - **[Error Handling](docs/error-handling.md)** - Error management and debugging
 - **[Function Registration](docs/function-registration.md)** - Tool and function management
 
-### 📋 Reference
-- **[Context & Background](docs/CONTEXT.md)** - Project context and inspiration
-- **[Next Steps & Roadmap](docs/NEXT_STEPS.md)** - Planned features and future vision
-
 **Quick Navigation:**
 - **New to DevOps AI Toolkit?** → Start with [MCP Setup Guide](docs/mcp-setup.md)
 - **Building integrations?** → See [API Reference](docs/API.md)

package/dist/interfaces/mcp.d.ts

@@ -22,6 +22,10 @@ export declare class MCPServer {
      * Register all tools with McpServer
      */
     private registerTools;
+    /**
+     * Register prompts capability with McpServer
+     */
+    private registerPrompts;
     private generateRequestId;
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/interfaces/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/interfaces/mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAgDtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAa;gBAEzB,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe;IA2BjD;;OAEG;IACH,OAAO,CAAC,aAAa;IAmGrB,OAAO,CAAC,iBAAiB;IAKnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,OAAO,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/interfaces/mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAoDtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAa;gBAEzB,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe;IA6BjD;;OAEG;IACH,OAAO,CAAC,aAAa;IAmGrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAoBvB,OAAO,CAAC,iBAAiB;IAKnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,OAAO,IAAI,OAAO;CAGnB"}

package/dist/interfaces/mcp.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCPServer = void 0;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const error_handling_1 = require("../core/error-handling");
 const recommend_1 = require("../tools/recommend");
 const choose_solution_1 = require("../tools/choose-solution");
@@ -17,6 +18,7 @@ const generate_manifests_1 = require("../tools/generate-manifests");
 const deploy_manifests_1 = require("../tools/deploy-manifests");
 const version_1 = require("../tools/version");
 const test_docs_1 = require("../tools/test-docs");
+const prompts_1 = require("../tools/prompts");
 class MCPServer {
     server;
     dotAI;
@@ -32,7 +34,8 @@ class MCPServer {
             version: config.version
         }, {
             capabilities: {
-                tools: {}
+                tools: {},
+                prompts: {}
             }
         });
         this.logger.info('Initializing MCP Server', {
@@ -40,8 +43,9 @@ class MCPServer {
             version: config.version,
             author: config.author
         });
-        // Register all tools directly with McpServer
+        // Register all tools and prompts directly with McpServer
         this.registerTools();
+        this.registerPrompts();
     }
     /**
      * Register all tools with McpServer
@@ -102,6 +106,26 @@ class MCPServer {
             totalTools: 7
         });
     }
+    /**
+     * Register prompts capability with McpServer
+     */
+    registerPrompts() {
+        // Register prompts/list handler
+        this.server.server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async (request) => {
+            const requestId = this.generateRequestId();
+            this.logger.info('Processing prompts/list request', { requestId });
+            return await (0, prompts_1.handlePromptsListRequest)(request.params || {}, this.logger, requestId);
+        });
+        // Register prompts/get handler
+        this.server.server.setRequestHandler(types_js_1.GetPromptRequestSchema, async (request) => {
+            const requestId = this.generateRequestId();
+            this.logger.info('Processing prompts/get request', { requestId, promptName: request.params?.name });
+            return await (0, prompts_1.handlePromptsGetRequest)(request.params || {}, this.logger, requestId);
+        });
+        this.logger.info('Registered prompts capability with McpServer', {
+            endpoints: ['prompts/list', 'prompts/get']
+        });
+    }
     generateRequestId() {
         return `mcp_${Date.now()}_${++this.requestIdCounter}`;
     }

package/dist/tools/prompts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP Prompts Handler - Manages shared prompt library
+ */
+import { Logger } from '../core/error-handling';
+export interface PromptMetadata {
+    name: string;
+    description: string;
+    category: string;
+}
+export interface Prompt {
+    name: string;
+    description: string;
+    content: string;
+}
+/**
+ * Loads and parses a prompt file with YAML frontmatter
+ */
+export declare function loadPromptFile(filePath: string): Prompt;
+/**
+ * Loads all prompts from the shared-prompts directory
+ */
+export declare function loadAllPrompts(logger: Logger): Prompt[];
+/**
+ * Handle prompts/list MCP request
+ */
+export declare function handlePromptsListRequest(args: any, logger: Logger, requestId: string): Promise<any>;
+/**
+ * Handle prompts/get MCP request
+ */
+export declare function handlePromptsGetRequest(args: any, logger: Logger, requestId: string): Promise<any>;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/tools/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/tools/prompts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGhD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAsCvD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAmCvD;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,CAAC,CAmCd;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,CAAC,CAiEd"}

package/dist/tools/prompts.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * MCP Prompts Handler - Manages shared prompt library
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPromptFile = loadPromptFile;
+exports.loadAllPrompts = loadAllPrompts;
+exports.handlePromptsListRequest = handlePromptsListRequest;
+exports.handlePromptsGetRequest = handlePromptsGetRequest;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const error_handling_1 = require("../core/error-handling");
+/**
+ * Loads and parses a prompt file with YAML frontmatter
+ */
+function loadPromptFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        // Parse YAML frontmatter
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+        if (!frontmatterMatch) {
+            throw new Error(`Invalid prompt file format: missing YAML frontmatter in ${filePath}`);
+        }
+        const [, frontmatterYaml, promptContent] = frontmatterMatch;
+        // Simple YAML parsing for our specific format
+        const metadata = {};
+        const lines = frontmatterYaml.split('\n');
+        for (const line of lines) {
+            const match = line.match(/^([^:]+):\s*(.+)$/);
+            if (match) {
+                const [, key, value] = match;
+                // Remove quotes if present
+                const cleanValue = value.trim().replace(/^["']|["']$/g, '');
+                metadata[key.trim()] = cleanValue;
+            }
+        }
+        if (!metadata.name || !metadata.description || !metadata.category) {
+            throw new Error(`Missing required metadata in ${filePath}: name, description, category`);
+        }
+        return {
+            name: metadata.name,
+            description: metadata.description,
+            content: promptContent.trim()
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to load prompt file ${filePath}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Loads all prompts from the shared-prompts directory
+ */
+function loadAllPrompts(logger) {
+    try {
+        const promptsDir = path.join(process.cwd(), 'shared-prompts');
+        if (!fs.existsSync(promptsDir)) {
+            logger.warn('Shared prompts directory not found', { path: promptsDir });
+            return [];
+        }
+        const files = fs.readdirSync(promptsDir);
+        const promptFiles = files.filter(file => file.endsWith('.md'));
+        const prompts = [];
+        for (const file of promptFiles) {
+            try {
+                const filePath = path.join(promptsDir, file);
+                const prompt = loadPromptFile(filePath);
+                prompts.push(prompt);
+                logger.debug('Loaded prompt', { name: prompt.name, file });
+            }
+            catch (error) {
+                logger.error(`Failed to load prompt file ${file}`, error);
+            }
+        }
+        logger.info('Loaded prompts from shared library', {
+            total: prompts.length,
+            promptsDir
+        });
+        return prompts;
+    }
+    catch (error) {
+        logger.error('Failed to load prompts directory', error);
+        return [];
+    }
+}
+/**
+ * Handle prompts/list MCP request
+ */
+async function handlePromptsListRequest(args, logger, requestId) {
+    try {
+        logger.info('Processing prompts/list request', { requestId });
+        const prompts = loadAllPrompts(logger);
+        // Convert to MCP prompts/list response format
+        const promptList = prompts.map(prompt => ({
+            name: prompt.name,
+            description: prompt.description
+        }));
+        logger.info('Prompts list generated', {
+            requestId,
+            promptCount: promptList.length
+        });
+        return {
+            prompts: promptList
+        };
+    }
+    catch (error) {
+        logger.error('Prompts list request failed', error);
+        throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.OPERATION, error_handling_1.ErrorSeverity.HIGH, error instanceof Error ? error.message : 'Unknown error in prompts list', {
+            operation: 'prompts_list',
+            component: 'PromptsHandler',
+            requestId,
+            input: args
+        });
+    }
+}
+/**
+ * Handle prompts/get MCP request
+ */
+async function handlePromptsGetRequest(args, logger, requestId) {
+    try {
+        logger.info('Processing prompts/get request', {
+            requestId,
+            promptName: args.name
+        });
+        if (!args.name) {
+            throw new Error('Missing required parameter: name');
+        }
+        const prompts = loadAllPrompts(logger);
+        const prompt = prompts.find(p => p.name === args.name);
+        if (!prompt) {
+            throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.MEDIUM, `Prompt not found: ${args.name}`, {
+                operation: 'prompts_get',
+                component: 'PromptsHandler',
+                requestId
+            });
+        }
+        logger.info('Prompt found and returned', {
+            requestId,
+            promptName: prompt.name
+        });
+        // Convert to MCP prompts/get response format
+        return {
+            description: prompt.description,
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: prompt.content
+                    }
+                }
+            ]
+        };
+    }
+    catch (error) {
+        logger.error('Prompts get request failed', error);
+        // Re-throw if already an AppError
+        if (error instanceof Error && 'category' in error) {
+            throw error;
+        }
+        throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.OPERATION, error_handling_1.ErrorSeverity.HIGH, error instanceof Error ? error.message : 'Unknown error in prompts get', {
+            operation: 'prompts_get',
+            component: 'PromptsHandler',
+            requestId,
+            input: args
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vfarcic/dot-ai",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Universal Kubernetes application deployment agent with CLI and MCP interfaces",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -69,6 +69,7 @@
   "files": [
     "dist",
     "prompts",
+    "shared-prompts",
     "README.md",
     "LICENSE"
   ],

package/prompts/doc-testing-test-section.md

@@ -37,6 +37,30 @@ Execute everything testable in this section:
 □ **User Experience Claims**: Would a typical user get the promised experience?
 □ **Code/Architecture Claims**: When documentation makes claims about code, files, or system architecture, validate them against the actual codebase
 
+### Cross-File Terminology Validation (When Applicable)
+
+**When testing documentation that references related files**, validate terminology consistency:
+
+#### Terminology Consistency Check
+**For files that are part of a documentation set** (e.g., setup guides, user guides, API references):
+
+1. **Identify Key Terms**: Extract important technical terms, feature names, and concepts from current section
+2. **Find Related Files**: Identify documentation files that should use consistent terminology
+3. **Cross-Reference Validation**: Check if the same concepts use identical terms across files
+4. **Flag Inconsistencies**: Report terminology mismatches that could confuse users
+
+**Common Terminology Issues:**
+- Same feature called different names in different files
+- Inconsistent capitalization (e.g., "MCP Server" vs "mcp server") 
+- Different terms for same concept (e.g., "slash commands" vs "command shortcuts")
+- Inconsistent format examples (e.g., `/dot-ai:name` vs `/mcp.dot-ai.name`)
+
+**How to Perform Cross-File Validation:**
+1. **Extract key terms** from current section being tested
+2. **Read related documentation files** mentioned in cross-references or logically related
+3. **Compare terminology usage** across files for consistency
+4. **Report discrepancies** that would confuse users navigating between files
+
 ### Code Analysis Validation (When Applicable)
 
 **When testing technical documentation in a code repository**, perform BOTH directions of validation:
@@ -199,7 +223,9 @@ Return your results as JSON in this exact format:
 - Mention how many items you tested in both phases
 - Example: "Tested 4 installation commands - npm install, API key setup, and 2 verification commands. All executed successfully with minor adaptations. Analyzed 6 documentation claims including 'easy installation' and 'automatic verification' - found installation complexity matches claimed simplicity but verification requires manual interpretation."
 
-**Both issues and recommendations should:**
+**Common Requirements for Both Issues and Recommendations:**
+- **MUST include precise location**: Section headings, specific text snippets, or element descriptions (NOT line numbers)
+- **MUST be immediately actionable**: Clear enough for someone else to locate and address
 - Be specific and actionable items only
 - Do NOT include positive assessments like "section works well" or "documentation is accurate"
 - Use empty arrays if nothing to report
@@ -207,14 +233,22 @@ Return your results as JSON in this exact format:
 - Focus on user impact and success
 
 **issues** (array of strings):
-- Specific problems that prevent or hinder user success
-- Include both functional problems (doesn't work) and semantic problems (inaccurate descriptions)
-- Examples: "npm install command requires global flag but documentation doesn't mention it", "Verification step expects specific output that doesn't match actual output"
+- **Purpose**: Specific problems that prevent or hinder user success
+- **Include**: Both functional problems (doesn't work) and semantic problems (inaccurate descriptions)
+- **Must explain user impact**: What fails or misleads users
+- Examples: 
+  - "In 'Quick Start' section: npm install command requires global flag but documentation doesn't mention it"
+  - "Under 'Verification' heading: Expected output 'Success: Ready' but actual output shows 'Status: OK'"
+  - "The phrase 'automatically detects' in Prerequisites: Claims automatic detection but requires manual configuration file editing"
 
 **recommendations** (array of strings):
-- Specific actionable improvements that would help users succeed
-- Only suggest concrete changes or additions to the documentation
-- Examples: "Add --global flag to npm install command", "Update expected output example to match actual command output", "Include verification command example"
+- **Purpose**: Specific actionable improvements that would help users succeed
+- **Include**: Only concrete changes or additions to the documentation
+- **Must specify exact action**: What text to add, remove, or modify
+- Examples:
+  - "In 'Quick Start' section: Change 'npm install' command to 'npm install --global'"
+  - "Under 'Verification' heading: Update expected output example from 'Success: Ready' to 'Status: OK'"
+  - "In Prerequisites section: Add note after 'automatically detects' phrase: 'Requires manual editing of config.json file before detection works'"
 
 **Important**: 
 - Use only this JSON format - do not include additional text before or after

package/shared-prompts/context-load.md

@@ -0,0 +1,19 @@
+---
+name: context-load
+description: Load context from tmp/context.md to continue previous work session
+category: session-management
+---
+
+# Load Context
+
+Load context from tmp/context.md to continue previous work session.
+
+Steps:
+1. Read the context file from `tmp/context.md`
+2. Analyze the saved context to understand:
+   - What work was completed previously
+   - Current status and next steps
+   - Available test data and file locations
+   - Technical implementation details
+3. Provide a brief summary of the loaded context
+4. Ask the user how they'd like to proceed based on the context

package/shared-prompts/context-save.md

@@ -0,0 +1,24 @@
+---
+name: context-save
+description: Save current context to tmp/context.md for session continuity
+category: session-management
+---
+
+# Save Context
+
+Save current context to tmp/context.md for session continuity.
+
+Steps:
+1. Clear existing context: Delete or empty tmp/context.md if it exists to ensure fresh state
+2. Analyze the current state of work, tasks completed, and next steps
+3. Create a comprehensive context summary including:
+   - Current status and what was accomplished
+   - Technical implementation details
+   - Test data and file locations
+   - Manual testing instructions
+   - Expected results and next steps
+   - Design decisions and architecture notes
+4. Save the fresh context to `tmp/context.md`
+5. Confirm the context has been saved successfully
+
+This ensures each context save represents only the current session state, preventing confusion from stale information and keeping context files manageable.