This is page 6 of 18. Use http://codebase.md/minipuft/claude-prompts-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .actrc
├── .gitattributes
├── .github
│ └── workflows
│ ├── ci.yml
│ ├── mcp-compliance.yml
│ └── pr-validation.yml
├── .gitignore
├── agent.md
├── assets
│ └── logo.png
├── CLAUDE.md
├── config
│ └── framework-state.json
├── docs
│ ├── architecture.md
│ ├── chain-modification-examples.md
│ ├── contributing.md
│ ├── enhanced-gate-system.md
│ ├── execution-architecture-guide.md
│ ├── installation-guide.md
│ ├── mcp-tool-usage-guide.md
│ ├── mcp-tools-reference.md
│ ├── prompt-format-guide.md
│ ├── prompt-management.md
│ ├── prompt-vs-template-guide.md
│ ├── README.md
│ ├── template-development-guide.md
│ ├── TODO.md
│ ├── troubleshooting.md
│ └── version-history.md
├── LICENSE
├── local-test.sh
├── plans
│ ├── nunjucks-dynamic-chain-orchestration.md
│ ├── outputschema-realtime-progress-and-validation.md
│ ├── parallel-conditional-execution-analysis.md
│ ├── sqlite-storage-migration.md
│ └── symbolic-command-language-implementation.md
├── README.md
├── scripts
│ ├── setup-windows-testing.sh
│ ├── test_server.js
│ ├── test-all-platforms.sh
│ └── windows-tests
│ ├── test-windows-paths.js
│ ├── test-windows-startup.sh
│ └── windows-env.sh
└── server
├── config
│ ├── framework-state.json
│ └── tool-descriptions.json
├── config.json
├── jest.config.cjs
├── LICENSE
├── package-lock.json
├── package.json
├── prompts
│ ├── analysis
│ │ ├── advanced_analysis_engine.md
│ │ ├── content_analysis.md
│ │ ├── deep_analysis.md
│ │ ├── deep_research.md
│ │ ├── markdown_notebook.md
│ │ ├── note_integration.md
│ │ ├── note_refinement.md
│ │ ├── notes.md
│ │ ├── progressive_research.md
│ │ ├── prompts.json
│ │ ├── query_refinement.md
│ │ └── review.md
│ ├── architecture
│ │ ├── prompts.json
│ │ └── strategic-system-alignment.md
│ ├── content_processing
│ │ ├── format_enhancement.md
│ │ ├── noteIntegration.md
│ │ ├── obsidian_metadata_optimizer.md
│ │ ├── prompts.json
│ │ ├── vault_related_notes_finder.md
│ │ └── video_notes_enhanced.md
│ ├── debugging
│ │ ├── analyze_logs.md
│ │ └── prompts.json
│ ├── development
│ │ ├── analyze_code_structure.md
│ │ ├── analyze_file_structure.md
│ │ ├── code_review_optimization_chain.md
│ │ ├── component_flow_analysis.md
│ │ ├── create_modularization_plan.md
│ │ ├── detect_code_issues.md
│ │ ├── detect_project_commands.md
│ │ ├── expert_code_implementation.md
│ │ ├── generate_comprehensive_claude_md.md
│ │ ├── prompts.json
│ │ ├── strategicImplement.md
│ │ ├── suggest_code_improvements.md
│ │ └── transform_code_to_modules.md
│ ├── documentation
│ │ ├── create_docs_chain.md
│ │ ├── docs-content-creation.md
│ │ ├── docs-content-planning.md
│ │ ├── docs-final-assembly.md
│ │ ├── docs-project-analysis.md
│ │ ├── docs-review-refinement.md
│ │ └── prompts.json
│ ├── education
│ │ ├── prompts.json
│ │ └── vault_integrated_notes.md
│ ├── general
│ │ ├── diagnose.md
│ │ └── prompts.json
│ ├── promptsConfig.json
│ └── testing
│ ├── final_verification_test.md
│ └── prompts.json
├── README.md
├── scripts
│ └── validate-dependencies.js
├── src
│ ├── api
│ │ └── index.ts
│ ├── chain-session
│ │ └── manager.ts
│ ├── config
│ │ └── index.ts
│ ├── Dockerfile
│ ├── execution
│ │ ├── context
│ │ │ ├── context-resolver.ts
│ │ │ ├── framework-injector.ts
│ │ │ └── index.ts
│ │ ├── index.ts
│ │ ├── parsers
│ │ │ ├── argument-parser.ts
│ │ │ ├── index.ts
│ │ │ └── unified-command-parser.ts
│ │ └── types.ts
│ ├── frameworks
│ │ ├── framework-manager.ts
│ │ ├── framework-state-manager.ts
│ │ ├── index.ts
│ │ ├── integration
│ │ │ ├── framework-semantic-integration.ts
│ │ │ └── index.ts
│ │ ├── methodology
│ │ │ ├── guides
│ │ │ │ ├── 5w1h-guide.ts
│ │ │ │ ├── cageerf-guide.ts
│ │ │ │ ├── react-guide.ts
│ │ │ │ └── scamper-guide.ts
│ │ │ ├── index.ts
│ │ │ ├── interfaces.ts
│ │ │ └── registry.ts
│ │ ├── prompt-guidance
│ │ │ ├── index.ts
│ │ │ ├── methodology-tracker.ts
│ │ │ ├── service.ts
│ │ │ ├── system-prompt-injector.ts
│ │ │ └── template-enhancer.ts
│ │ └── types
│ │ ├── index.ts
│ │ ├── integration-types.ts
│ │ ├── methodology-types.ts
│ │ └── prompt-guidance-types.ts
│ ├── gates
│ │ ├── constants.ts
│ │ ├── core
│ │ │ ├── gate-definitions.ts
│ │ │ ├── gate-loader.ts
│ │ │ ├── gate-validator.ts
│ │ │ ├── index.ts
│ │ │ └── temporary-gate-registry.ts
│ │ ├── definitions
│ │ │ ├── code-quality.json
│ │ │ ├── content-structure.json
│ │ │ ├── educational-clarity.json
│ │ │ ├── framework-compliance.json
│ │ │ ├── research-quality.json
│ │ │ ├── security-awareness.json
│ │ │ └── technical-accuracy.json
│ │ ├── gate-state-manager.ts
│ │ ├── guidance
│ │ │ ├── FrameworkGuidanceFilter.ts
│ │ │ └── GateGuidanceRenderer.ts
│ │ ├── index.ts
│ │ ├── intelligence
│ │ │ ├── GatePerformanceAnalyzer.ts
│ │ │ └── GateSelectionEngine.ts
│ │ ├── templates
│ │ │ ├── code_quality_validation.md
│ │ │ ├── educational_clarity_validation.md
│ │ │ ├── framework_compliance_validation.md
│ │ │ ├── research_self_validation.md
│ │ │ ├── security_validation.md
│ │ │ ├── structure_validation.md
│ │ │ └── technical_accuracy_validation.md
│ │ └── types.ts
│ ├── index.ts
│ ├── logging
│ │ └── index.ts
│ ├── mcp-tools
│ │ ├── config-utils.ts
│ │ ├── constants.ts
│ │ ├── index.ts
│ │ ├── prompt-engine
│ │ │ ├── core
│ │ │ │ ├── engine.ts
│ │ │ │ ├── executor.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── processors
│ │ │ │ ├── response-formatter.ts
│ │ │ │ └── template-processor.ts
│ │ │ └── utils
│ │ │ ├── category-extractor.ts
│ │ │ ├── classification.ts
│ │ │ ├── context-builder.ts
│ │ │ └── validation.ts
│ │ ├── prompt-manager
│ │ │ ├── analysis
│ │ │ │ ├── comparison-engine.ts
│ │ │ │ ├── gate-analyzer.ts
│ │ │ │ └── prompt-analyzer.ts
│ │ │ ├── core
│ │ │ │ ├── index.ts
│ │ │ │ ├── manager.ts
│ │ │ │ └── types.ts
│ │ │ ├── index.ts
│ │ │ ├── operations
│ │ │ │ └── file-operations.ts
│ │ │ ├── search
│ │ │ │ ├── filter-parser.ts
│ │ │ │ └── prompt-matcher.ts
│ │ │ └── utils
│ │ │ ├── category-manager.ts
│ │ │ └── validation.ts
│ │ ├── shared
│ │ │ └── structured-response-builder.ts
│ │ ├── system-control.ts
│ │ ├── tool-description-manager.ts
│ │ └── types
│ │ └── shared-types.ts
│ ├── metrics
│ │ ├── analytics-service.ts
│ │ ├── index.ts
│ │ └── types.ts
│ ├── performance
│ │ ├── index.ts
│ │ └── monitor.ts
│ ├── prompts
│ │ ├── category-manager.ts
│ │ ├── converter.ts
│ │ ├── file-observer.ts
│ │ ├── hot-reload-manager.ts
│ │ ├── index.ts
│ │ ├── loader.ts
│ │ ├── promptUtils.ts
│ │ ├── registry.ts
│ │ └── types.ts
│ ├── runtime
│ │ ├── application.ts
│ │ └── startup.ts
│ ├── semantic
│ │ ├── configurable-semantic-analyzer.ts
│ │ └── integrations
│ │ ├── index.ts
│ │ └── llm-clients.ts
│ ├── server
│ │ ├── index.ts
│ │ └── transport
│ │ └── index.ts
│ ├── smithery.yaml
│ ├── text-references
│ │ ├── conversation.ts
│ │ └── index.ts
│ ├── types
│ │ └── index.ts
│ ├── types.ts
│ └── utils
│ ├── chainUtils.ts
│ ├── errorHandling.ts
│ ├── global-resource-tracker.ts
│ ├── index.ts
│ └── jsonUtils.ts
├── tests
│ ├── ci-startup-validation.js
│ ├── enhanced-validation
│ │ ├── contract-validation
│ │ │ ├── contract-test-suite.js
│ │ │ ├── interface-contracts.js
│ │ │ └── interface-contracts.ts
│ │ ├── environment-validation
│ │ │ ├── environment-parity-checker.js
│ │ │ └── environment-test-suite.js
│ │ ├── lifecycle-validation
│ │ │ ├── lifecycle-test-suite.js
│ │ │ └── process-lifecycle-validator.js
│ │ └── validation-orchestrator.js
│ ├── helpers
│ │ └── test-helpers.js
│ ├── integration
│ │ ├── mcp-tools.test.ts
│ │ ├── server-startup.test.ts
│ │ └── unified-parsing-integration.test.ts
│ ├── performance
│ │ ├── parsing-system-benchmark.test.ts
│ │ └── server-performance.test.ts
│ ├── scripts
│ │ ├── consolidated-tools.js
│ │ ├── establish-performance-baselines.js
│ │ ├── functional-mcp-validation.js
│ │ ├── integration-mcp-tools.js
│ │ ├── integration-routing-system.js
│ │ ├── integration-server-startup.js
│ │ ├── integration-unified-parsing.js
│ │ ├── methodology-guides.js
│ │ ├── performance-memory.js
│ │ ├── runtime-integration.js
│ │ ├── unit-conversation-manager.js
│ │ ├── unit-semantic-analyzer.js
│ │ └── unit-unified-parsing.js
│ ├── setup.ts
│ ├── test-enhanced-parsing.js
│ └── unit
│ ├── conversation-manager.test.ts
│ ├── semantic-analyzer-three-tier.test.ts
│ └── unified-parsing-system.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/docs/execution-architecture-guide.md:
--------------------------------------------------------------------------------
```markdown
1 | # Three-Tier Execution System Guide
2 |
3 | ## Overview
4 |
5 | The Claude Prompts MCP Server implements a sophisticated **three-tier execution model** designed to handle different levels of complexity and user requirements. This guide explains how the system automatically selects the appropriate execution tier and what each tier provides.
6 |
7 | ## Related Documentation
8 |
9 | - **[Quick Start: Execution Modes](prompt-vs-template-guide.md)** - Quick decision guide for choosing execution modes
10 | - **[Template Development Guide](template-development-guide.md)** - Creating framework-aware templates (Tier 2)
11 | - **[Chain System Analysis](chain-system-analysis.md)** - Detailed analysis of chain execution (Tier 3)
12 | - **[System Architecture](architecture.md)** - Technical implementation details
13 | - **[MCP Tools Reference](mcp-tools-reference.md)** - Using the `prompt_engine` tool across all tiers
14 |
15 | ## The Three Execution Tiers
16 |
17 | ### Tier 1: Prompt Execution (Basic)
18 | **Best for**: Simple variable substitution and straightforward prompts
19 |
20 | - **Purpose**: Fast, lightweight execution for basic prompts
21 | - **Processing**: Direct Nunjucks template variable substitution
22 | - **Framework Integration**: Minimal - uses default settings
23 | - **Performance**: Fastest execution with minimal overhead
24 | - **Use Cases**: Quick queries, simple content generation, basic automation
25 |
26 | **Example**:
27 | ```markdown
28 | # Simple Greeting Prompt
29 | Hello {{name}}, welcome to {{service}}!
30 | ```
31 |
32 | ### Tier 2: Template Execution (Framework-Aware)
33 | **Best for**: Structured prompts requiring methodology guidance
34 |
35 | - **Purpose**: Enhanced execution with active framework methodology
36 | - **Processing**: Framework-specific system prompt injection + template processing
37 | - **Framework Integration**: Full integration with CAGEERF, ReACT, 5W1H, SCAMPER
38 | - **Performance**: Moderate overhead for enhanced quality
39 | - **Use Cases**: Structured analysis, systematic problem-solving, quality-assured content
40 |
41 | **Example**:
42 | ```markdown
43 | # Analysis Template
44 | **🔄 FRAMEWORK EXECUTION**: Uses {{framework}} methodology for systematic analysis
45 |
46 | Analyze the following content using structured approach:
47 | {{content}}
48 | ```
49 |
50 | ### Tier 3: Chain Execution (Multi-Step Workflows)
51 | **Best for**: Complex multi-step processes requiring orchestration
52 |
53 | - **Purpose**: LLM-driven iterative workflows with state management
54 | - **Processing**: Step-by-step execution with context passing between steps
55 | - **Framework Integration**: Framework guidance applies to each step
56 | - **Performance**: Highest overhead but maximum capability
57 | - **Use Cases**: Complex analysis workflows, multi-phase content creation, research processes
58 |
59 | **Example**:
60 | ```markdown
61 | # Content Analysis Chain
62 | ## Chain Steps
63 |
64 | 1. promptId: content_analysis
65 | stepName: Initial Content Analysis
66 |
67 | 2. promptId: deep_analysis
68 | stepName: Deep Analysis
69 | inputMapping:
70 | initial_analysis: step_0_output
71 | ```
72 |
73 | ## Execution Tier Selection
74 |
75 | ### Automatic Detection
76 |
77 | The system automatically detects the appropriate execution tier based on prompt characteristics:
78 |
79 | ```typescript
80 | // Execution type detection logic
81 | if (prompt.isChain && prompt.chainSteps?.length > 0) {
82 | return 'chain';
83 | } else if (hasFrameworkRequirements(prompt)) {
84 | return 'template';
85 | } else {
86 | return 'prompt';
87 | }
88 | ```
89 |
90 | ### Manual Override
91 |
92 | You can explicitly specify execution mode using the `execution_mode` parameter:
93 |
94 | ```bash
95 | # Force template execution
96 | prompt_engine >>my_prompt execution_mode=template
97 |
98 | # Force chain execution
99 | prompt_engine >>my_chain execution_mode=chain llm_driven_execution=true
100 | ```
101 |
102 | ## Architecture Components
103 |
104 | ### Execution Engine Flow
105 |
106 | ```mermaid
107 | graph TD
108 | A[MCP Client Request] --> B[ConsolidatedPromptEngine]
109 | B --> C{Execution Type Detection}
110 |
111 | C -->|Basic| D[Prompt Execution]
112 | C -->|Enhanced| E[Template Execution]
113 | C -->|Complex| F[Chain Execution]
114 |
115 | D --> G[Nunjucks Processing]
116 | E --> H[Framework Injection + Nunjucks]
117 | F --> I[LLM-Driven Step Orchestration]
118 |
119 | G --> J[Direct Response]
120 | H --> K[Framework-Enhanced Response]
121 | I --> L[Chain Progress Instructions]
122 | ```
123 |
124 | ### Core Components
125 |
126 | #### ConsolidatedPromptEngine
127 | **Location**: `server/src/mcp-tools/prompt-engine.ts`
128 |
129 | - **Role**: Central execution coordinator
130 | - **Responsibilities**:
131 | - Execution tier detection and selection
132 | - Framework integration coordination
133 | - Chain state management and instruction generation
134 | - Quality gate validation
135 |
136 | #### ExecutionCoordinator
137 | **Location**: `server/src/execution/execution-coordinator.ts`
138 |
139 | - **Role**: Thin orchestration layer
140 | - **Responsibilities**:
141 | - Legacy compatibility
142 | - Statistics tracking across execution tiers
143 | - Delegation to ConsolidatedPromptEngine
144 |
145 | #### Framework Manager
146 | **Location**: `server/src/frameworks/framework-manager.ts`
147 |
148 | - **Role**: Methodology guide orchestration
149 | - **Responsibilities**:
150 | - Active framework state management
151 | - System prompt generation for templates
152 | - Framework-specific quality guidance
153 |
154 | ## Framework Integration Across Tiers
155 |
156 | ### Available Frameworks
157 | - **CAGEERF**: Context, Analysis, Goals, Execution, Evaluation, Refinement, Framework
158 | - **ReACT**: Reasoning and Acting systematic approach
159 | - **5W1H**: Who, What, When, Where, Why, How analysis
160 | - **SCAMPER**: Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse
161 |
162 | ### Framework Application by Tier
163 |
164 | #### Prompt Tier (Minimal Integration)
165 | - Framework selection tracked but not actively applied
166 | - Uses framework defaults for any quality gates
167 | - No system prompt modification
168 |
169 | #### Template Tier (Full Integration)
170 | - Active framework methodology guides applied
171 | - Framework-specific system prompts injected
172 | - Quality gates adapted to framework criteria
173 | - Enhanced validation and guidance
174 |
175 | #### Chain Tier (Per-Step Integration)
176 | - Framework guidance applied to each chain step
177 | - Consistent methodology throughout multi-step process
178 | - Framework-aware context passing between steps
179 | - Comprehensive quality validation per step
180 |
181 | ## Quality Gates by Tier
182 |
183 | ### Prompt Tier Gates
184 | - Basic content validation (length, format)
185 | - Template variable validation
186 | - Simple structure checks
187 |
188 | ### Template Tier Gates
189 | - All prompt tier gates
190 | - Framework methodology compliance
191 | - Enhanced content quality validation
192 | - Argument structure validation
193 |
194 | ### Chain Tier Gates
195 | - All template tier gates applied per step
196 | - Chain structure validation
197 | - Step dependency validation
198 | - Context continuity validation
199 |
200 | ## Performance Characteristics
201 |
202 | ### Execution Time Comparison
203 |
204 | | Tier | Typical Execution | Overhead | Best For |
205 | |------|------------------|----------|----------|
206 | | Prompt | 50-200ms | Minimal | Quick queries |
207 | | Template | 200-800ms | Moderate | Structured work |
208 | | Chain | 2-10s per step | High | Complex workflows |
209 |
210 | ### Memory Usage
211 |
212 | - **Prompt**: Minimal memory footprint
213 | - **Template**: Moderate memory for framework context
214 | - **Chain**: Higher memory for state management and step context
215 |
216 | ## Best Practices
217 |
218 | ### When to Use Each Tier
219 |
220 | #### Choose Prompt Tier When:
221 | - Simple content generation needs
222 | - Performance is critical
223 | - No structural requirements
224 | - Straightforward variable substitution
225 |
226 | #### Choose Template Tier When:
227 | - Need systematic methodology application
228 | - Quality validation is important
229 | - Structured output required
230 | - Working within established frameworks
231 |
232 | #### Choose Chain Tier When:
233 | - Multi-step processes required
234 | - Complex workflows with dependencies
235 | - Need context passing between steps
236 | - Iterative refinement processes
237 |
238 | ### Performance Optimization
239 |
240 | #### Prompt Tier Optimization
241 | - Minimize template complexity
242 | - Use simple variable substitution
243 | - Avoid unnecessary processing
244 |
245 | #### Template Tier Optimization
246 | - Choose appropriate framework for task
247 | - Use efficient template structures
248 | - Enable only necessary quality gates
249 |
250 | #### Chain Tier Optimization
251 | - Design efficient step sequences
252 | - Minimize context accumulation
253 | - Use auto-execution for simple chains
254 | - Plan for context window management
255 |
256 | ## Configuration
257 |
258 | ### Global Execution Settings
259 |
260 | ```json
261 | {
262 | "execution": {
263 | "defaultMode": "auto",
264 | "enableGateValidation": true,
265 | "chainAutoExecution": true,
266 | "performanceMonitoring": true
267 | }
268 | }
269 | ```
270 |
271 | ### Per-Prompt Configuration
272 |
273 | ```markdown
274 | # Prompt with tier preference
275 | **⚡ EXECUTION REQUIRED**: This prompt uses template execution for framework integration
276 |
277 | Your content here...
278 | ```
279 |
280 | ## Troubleshooting
281 |
282 | ### Common Issues
283 |
284 | #### Wrong Tier Selection
285 | **Problem**: System selects inappropriate execution tier
286 | **Solution**: Use explicit `execution_mode` parameter
287 |
288 | #### Performance Issues
289 | **Problem**: Slow execution times
290 | **Solution**: Check execution tier - consider lower tier for simpler tasks
291 |
292 | #### Chain State Issues
293 | **Problem**: Chain execution loses state between steps
294 | **Solution**: Verify ConversationManager state tracking is active
295 |
296 | ### Debug Information
297 |
298 | Enable verbose logging to see execution tier selection:
299 | ```bash
300 | npm run start:verbose
301 | ```
302 |
303 | This will show:
304 | - Execution tier detection reasoning
305 | - Framework selection process
306 | - Performance metrics by tier
307 | - State management activities
308 |
309 | ## Migration Guide
310 |
311 | ### From Legacy Single-Tier System
312 |
313 | If migrating from older single-tier execution:
314 |
315 | 1. **Review existing prompts** for tier appropriateness
316 | 2. **Add framework markers** for prompts needing template tier
317 | 3. **Convert multi-step processes** to chain format
318 | 4. **Test execution tier detection** with your prompt library
319 |
320 | ### Updating Existing Prompts
321 |
322 | ```markdown
323 | # Before (legacy)
324 | Your prompt content
325 |
326 | # After (tier-aware)
327 | **🔄 TEMPLATE EXECUTION**: Framework-aware processing
328 | Your prompt content with {{variables}}
329 |
330 | # Chain format
331 | ## Chain Steps
332 | 1. promptId: step_one
333 | stepName: First Step
334 | ```
335 |
336 | This three-tier system provides the flexibility to handle everything from simple queries to complex multi-step workflows while maintaining optimal performance for each use case.
```
--------------------------------------------------------------------------------
/server/src/gates/intelligence/GateSelectionEngine.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Gate Selection Engine - Intelligent Gate Selection
3 | *
4 | * Single responsibility: Select appropriate gates based on semantic analysis and context.
5 | * Clean dependencies: Only content analysis types and framework definitions.
6 | */
7 |
8 | import type { Logger } from '../../logging/index.js';
9 | import { GateSelectionCriteria, GateSelectionResult } from '../core/gate-definitions.js';
10 | import type { ContentAnalysisResult } from '../../semantic/configurable-semantic-analyzer.js';
11 | import type { FrameworkDefinition } from '../../frameworks/types/index.js';
12 |
13 | /**
14 | * User preferences for gate selection
15 | */
16 | export interface UserPreferences {
17 | strictValidation?: boolean;
18 | performanceMode?: boolean;
19 | qualityFocus?: 'speed' | 'accuracy' | 'balanced';
20 | }
21 |
22 | /**
23 | * Extended gate selection criteria with semantic analysis
24 | * Explicitly includes all base properties for strict TypeScript compilation compatibility
25 | */
26 | export interface ExtendedGateSelectionCriteria extends GateSelectionCriteria {
27 | // Explicitly defined for GitHub Actions TypeScript compatibility
28 | framework?: string;
29 | category?: string;
30 | promptId?: string;
31 | executionMode?: 'prompt' | 'template' | 'chain';
32 | complexityLevel?: 'low' | 'medium' | 'high';
33 |
34 | // Extended properties
35 | semanticAnalysis?: ContentAnalysisResult;
36 | frameworkContext?: FrameworkDefinition;
37 | userPreferences?: UserPreferences;
38 | }
39 |
40 | /**
41 | * Gate selection engine with semantic awareness
42 | */
43 | export class GateSelectionEngine {
44 | private logger: Logger;
45 | private selectionHistory: GateSelectionResult[] = [];
46 |
47 | constructor(logger: Logger) {
48 | this.logger = logger;
49 | this.logger.debug('[GATE SELECTION ENGINE] Initialized');
50 | }
51 |
52 | /**
53 | * Select appropriate gates based on criteria and semantic analysis
54 | *
55 | * @param criteria - Extended selection criteria with semantic analysis
56 | * @returns Gate selection result with reasoning
57 | */
58 | async selectGates(criteria: ExtendedGateSelectionCriteria): Promise<GateSelectionResult> {
59 | const startTime = Date.now();
60 |
61 | this.logger.info('🧠 [GATE SELECTION ENGINE] selectGates called:', {
62 | framework: criteria.framework,
63 | category: criteria.category,
64 | executionMode: criteria.executionMode,
65 | complexityLevel: criteria.complexityLevel,
66 | hasSemanticAnalysis: !!criteria.semanticAnalysis,
67 | hasFrameworkContext: !!criteria.frameworkContext
68 | });
69 |
70 | // Primary gate selection based on framework and category
71 | const primaryGates = this.selectPrimaryGates(criteria);
72 |
73 | // Semantic-enhanced gate selection
74 | const semanticGates = this.selectSemanticGates(criteria);
75 |
76 | // Merge and deduplicate
77 | const selectedGates = this.mergeGateSelections(primaryGates, semanticGates);
78 |
79 | // Generate reasoning
80 | const reasoning = this.generateSelectionReasoning(criteria, primaryGates, semanticGates);
81 |
82 | // Calculate confidence
83 | const confidence = this.calculateSelectionConfidence(criteria, selectedGates);
84 |
85 | // Estimate execution time
86 | const estimatedExecutionTime = this.estimateExecutionTime(selectedGates, criteria);
87 |
88 | // Determine fallback gates
89 | const fallbackGates = this.determineFallbackGates(criteria);
90 |
91 | const result: GateSelectionResult = {
92 | selectedGates,
93 | reasoning,
94 | confidence,
95 | estimatedExecutionTime,
96 | fallbackGates
97 | };
98 |
99 | // Track selection history
100 | this.selectionHistory.push(result);
101 | if (this.selectionHistory.length > 50) {
102 | this.selectionHistory = this.selectionHistory.slice(-50);
103 | }
104 |
105 | const executionTime = Date.now() - startTime;
106 | this.logger.debug('[GATE SELECTION ENGINE] Selection completed:', {
107 | selectedGates: selectedGates.length,
108 | confidence,
109 | estimatedExecutionTime,
110 | actualSelectionTime: executionTime
111 | });
112 |
113 | return result;
114 | }
115 |
116 | /**
117 | * Select primary gates based on framework and category
118 | */
119 | private selectPrimaryGates(criteria: ExtendedGateSelectionCriteria): string[] {
120 | const gates: string[] = [];
121 |
122 | // Framework-based selection
123 | if (criteria.framework) {
124 | switch (criteria.framework) {
125 | case 'ReACT':
126 | gates.push('framework-compliance', 'educational-clarity');
127 | break;
128 | case 'CAGEERF':
129 | gates.push('framework-compliance', 'research-quality');
130 | break;
131 | case '5W1H':
132 | gates.push('framework-compliance', 'technical-accuracy');
133 | break;
134 | case 'SCAMPER':
135 | gates.push('framework-compliance', 'content-structure');
136 | break;
137 | default:
138 | gates.push('framework-compliance');
139 | }
140 | }
141 |
142 | // Category-based selection
143 | if (criteria.category) {
144 | switch (criteria.category) {
145 | case 'analysis':
146 | gates.push('research-quality', 'technical-accuracy');
147 | break;
148 | case 'education':
149 | gates.push('educational-clarity', 'content-structure');
150 | break;
151 | case 'development':
152 | gates.push('code-quality', 'security-awareness');
153 | break;
154 | case 'research':
155 | gates.push('research-quality', 'technical-accuracy');
156 | break;
157 | default:
158 | gates.push('content-structure');
159 | }
160 | }
161 |
162 | return [...new Set(gates)]; // Remove duplicates
163 | }
164 |
165 | /**
166 | * Select gates based on semantic analysis
167 | */
168 | private selectSemanticGates(criteria: ExtendedGateSelectionCriteria): string[] {
169 | if (!criteria.semanticAnalysis) {
170 | return [];
171 | }
172 |
173 | const gates: string[] = [];
174 | const analysis = criteria.semanticAnalysis;
175 |
176 | // Example semantic-based selection (would be expanded with real analysis)
177 | if (analysis.confidence && analysis.confidence > 0.8) {
178 | gates.push('technical-accuracy');
179 | }
180 |
181 | if (criteria.executionMode === 'chain') {
182 | gates.push('educational-clarity');
183 | }
184 |
185 | if (criteria.complexityLevel === 'high') {
186 | gates.push('research-quality');
187 | }
188 |
189 | return gates;
190 | }
191 |
192 | /**
193 | * Merge multiple gate selections and remove duplicates
194 | */
195 | private mergeGateSelections(...selections: string[][]): string[] {
196 | const allGates = selections.flat();
197 | return [...new Set(allGates)];
198 | }
199 |
200 | /**
201 | * Generate human-readable reasoning for gate selection
202 | */
203 | private generateSelectionReasoning(
204 | criteria: ExtendedGateSelectionCriteria,
205 | primaryGates: string[],
206 | semanticGates: string[]
207 | ): string[] {
208 | const reasoning: string[] = [];
209 |
210 | if (criteria.framework) {
211 | reasoning.push(`Selected framework-specific gates for ${criteria.framework} methodology`);
212 | }
213 |
214 | if (criteria.category) {
215 | reasoning.push(`Applied category-specific gates for ${criteria.category} content`);
216 | }
217 |
218 | if (semanticGates.length > 0) {
219 | reasoning.push(`Enhanced selection with semantic analysis recommendations`);
220 | }
221 |
222 | if (criteria.complexityLevel) {
223 | reasoning.push(`Adjusted for ${criteria.complexityLevel} complexity level`);
224 | }
225 |
226 | if (criteria.userPreferences?.performanceMode) {
227 | reasoning.push(`Optimized for performance mode`);
228 | }
229 |
230 | return reasoning;
231 | }
232 |
233 | /**
234 | * Calculate confidence score for gate selection
235 | */
236 | private calculateSelectionConfidence(
237 | criteria: ExtendedGateSelectionCriteria,
238 | selectedGates: string[]
239 | ): number {
240 | let confidence = 0.5; // Base confidence
241 |
242 | // Increase confidence with more context
243 | if (criteria.framework) confidence += 0.2;
244 | if (criteria.category) confidence += 0.2;
245 | if (criteria.semanticAnalysis) confidence += 0.1;
246 |
247 | // Adjust based on gate count
248 | if (selectedGates.length >= 2 && selectedGates.length <= 4) {
249 | confidence += 0.1; // Good balance
250 | } else if (selectedGates.length > 4) {
251 | confidence -= 0.1; // Too many gates might be overwhelming
252 | }
253 |
254 | return Math.min(Math.max(confidence, 0), 1);
255 | }
256 |
257 | /**
258 | * Estimate execution time for selected gates
259 | */
260 | private estimateExecutionTime(selectedGates: string[], criteria: ExtendedGateSelectionCriteria): number {
261 | // Base time per gate (in milliseconds)
262 | const baseTimePerGate = 100;
263 |
264 | // Complexity multipliers
265 | const complexityMultipliers = {
266 | low: 0.8,
267 | medium: 1.0,
268 | high: 1.5
269 | };
270 |
271 | const multiplier = complexityMultipliers[criteria.complexityLevel || 'medium'];
272 |
273 | return selectedGates.length * baseTimePerGate * multiplier;
274 | }
275 |
276 | /**
277 | * Determine fallback gates if primary selection fails
278 | */
279 | private determineFallbackGates(criteria: ExtendedGateSelectionCriteria): string[] {
280 | // Default fallback gates
281 | const fallbacks = ['content-structure'];
282 |
283 | // Add framework-specific fallback if available
284 | if (criteria.framework) {
285 | fallbacks.push('framework-compliance');
286 | }
287 |
288 | return fallbacks;
289 | }
290 |
291 | /**
292 | * Get selection history for analysis
293 | */
294 | getSelectionHistory(): GateSelectionResult[] {
295 | return [...this.selectionHistory];
296 | }
297 |
298 | /**
299 | * Clear selection history
300 | */
301 | clearHistory(): void {
302 | this.selectionHistory = [];
303 | this.logger.debug('[GATE SELECTION ENGINE] Selection history cleared');
304 | }
305 |
306 | /**
307 | * Get selection statistics
308 | */
309 | getStatistics() {
310 | const totalSelections = this.selectionHistory.length;
311 | const averageGatesSelected = totalSelections > 0
312 | ? this.selectionHistory.reduce((sum, result) => sum + result.selectedGates.length, 0) / totalSelections
313 | : 0;
314 | const averageConfidence = totalSelections > 0
315 | ? this.selectionHistory.reduce((sum, result) => sum + result.confidence, 0) / totalSelections
316 | : 0;
317 |
318 | return {
319 | totalSelections,
320 | averageGatesSelected: Math.round(averageGatesSelected * 10) / 10,
321 | averageConfidence: Math.round(averageConfidence * 100) / 100,
322 | historySize: this.selectionHistory.length
323 | };
324 | }
325 | }
326 |
327 | /**
328 | * Factory function for creating gate selection engine
329 | */
330 | export function createGateSelectionEngine(logger: Logger): GateSelectionEngine {
331 | return new GateSelectionEngine(logger);
332 | }
333 |
334 | // Interfaces are already exported via declaration above
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/shared/structured-response-builder.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Unified MCP Structured Response Builder
3 | *
4 | * Provides consistent structured response creation across all MCP tools
5 | * to ensure MCP protocol compliance when outputSchema is defined.
6 | *
7 | * This addresses the issue where tools must provide structuredContent
8 | * when they declare an outputSchema, as required by MCP protocol.
9 | */
10 |
11 | import { ToolResponse } from "../../types/index.js";
12 | import { ErrorContext } from "../types/shared-types.js";
13 |
14 | /**
15 | * Metadata for creating structured responses
16 | */
17 | export interface ResponseMetadata {
18 | /** Tool name (prompt_manager, prompt_engine, system_control) */
19 | tool: string;
20 |
21 | /** Operation being performed (create, update, delete, execute, etc.) */
22 | operation: string;
23 |
24 | /** Type of execution for this operation */
25 | executionType?: "prompt" | "template" | "chain";
26 |
27 | /** Execution time in milliseconds */
28 | executionTime?: number;
29 |
30 | /** Whether framework processing was enabled */
31 | frameworkEnabled?: boolean;
32 |
33 | /** Framework that was used (if any) */
34 | frameworkUsed?: string;
35 |
36 | /** Number of steps executed (for chain operations) */
37 | stepsExecuted?: number;
38 |
39 | /** Session ID for tracking related operations */
40 | sessionId?: string;
41 |
42 | /** Tool-specific operation data */
43 | operationData?: Record<string, any>;
44 |
45 | /** Analytics data to include */
46 | analytics?: {
47 | totalExecutions: number;
48 | successRate: number;
49 | averageExecutionTime: number;
50 | frameworkSwitches?: number;
51 | gateValidationCount?: number;
52 | errorCount?: number;
53 | uptime: number;
54 | } | Record<string, any>;
55 |
56 | /** Gate validation results */
57 | gateValidation?: {
58 | enabled: boolean;
59 | passed: boolean;
60 | totalGates: number;
61 | failedGates: Array<any>;
62 | passedGates?: Array<any>;
63 | executionTime: number;
64 | retryCount?: number;
65 | };
66 | }
67 |
68 | /**
69 | * Context for error responses
70 | */
71 |
72 | /**
73 | * Unified structured response builder for MCP tools
74 | */
75 | export class StructuredResponseBuilder {
76 | /**
77 | * Create a structured tool response with consistent metadata
78 | */
79 | static createToolResponse(content: string, metadata: ResponseMetadata): ToolResponse {
80 | const startTime = Date.now();
81 | const executionId = `${metadata.tool.toLowerCase()}-${metadata.operation}-${startTime}`;
82 |
83 | const response: ToolResponse = {
84 | content: [{ type: "text", text: content }],
85 | isError: false,
86 | structuredContent: {
87 | executionMetadata: {
88 | executionId,
89 | executionType: metadata.executionType || "prompt",
90 | startTime,
91 | endTime: startTime + (metadata.executionTime || 0),
92 | executionTime: metadata.executionTime || 0,
93 | frameworkEnabled: metadata.frameworkEnabled || false,
94 | frameworkUsed: metadata.frameworkUsed,
95 | stepsExecuted: metadata.stepsExecuted,
96 | sessionId: metadata.sessionId
97 | }
98 | }
99 | };
100 |
101 | // Add optional structured content fields
102 | if (metadata.analytics) {
103 | response.structuredContent!.analytics = metadata.analytics as any;
104 | }
105 |
106 | if (metadata.gateValidation) {
107 | response.structuredContent!.gateValidation = metadata.gateValidation;
108 | }
109 |
110 | // Add tool-specific operation data
111 | if (metadata.operationData) {
112 | response.structuredContent = {
113 | ...response.structuredContent,
114 | operationData: {
115 | tool: metadata.tool,
116 | operation: metadata.operation,
117 | ...metadata.operationData
118 | }
119 | };
120 | }
121 |
122 | return response;
123 | }
124 |
125 | /**
126 | * Create a structured error response
127 | */
128 | static createErrorResponse(error: Error | string, context: ErrorContext): ToolResponse {
129 | const timestamp = Date.now();
130 | const toolName = context.tool || 'unknown';
131 | const executionId = `${toolName.toLowerCase()}-error-${timestamp}`;
132 | const errorMessage = error instanceof Error ? error.message : error;
133 |
134 | return {
135 | content: [{ type: "text", text: `Error: ${errorMessage}` }],
136 | isError: true,
137 | structuredContent: {
138 | executionMetadata: {
139 | executionId,
140 | executionType: "prompt",
141 | startTime: timestamp,
142 | endTime: timestamp,
143 | executionTime: 0,
144 | frameworkEnabled: false
145 | },
146 | errorInfo: {
147 | errorCode: toolName.toUpperCase() + "_ERROR",
148 | errorType: context.errorType || "system",
149 | message: errorMessage,
150 | details: context.details,
151 | timestamp,
152 | severity: context.severity || "medium",
153 | suggestedActions: context.suggestedActions,
154 | relatedComponents: context.relatedComponents
155 | }
156 | }
157 | };
158 | }
159 |
160 | /**
161 | * Create a simple response with minimal metadata (for backward compatibility)
162 | */
163 | static createSimpleResponse(content: string, tool: string, operation: string): ToolResponse {
164 | return this.createToolResponse(content, {
165 | tool,
166 | operation,
167 | executionType: "prompt",
168 | frameworkEnabled: false
169 | });
170 | }
171 |
172 | /**
173 | * Create a response for prompt operations with analysis data
174 | */
175 | static createPromptResponse(
176 | content: string,
177 | operation: string,
178 | promptData?: {
179 | promptId?: string;
180 | category?: string;
181 | analysisResult?: any;
182 | affectedFiles?: string[];
183 | },
184 | includeStructuredContent: boolean = false
185 | ): ToolResponse {
186 | // Return simple text response by default for Claude Code visibility
187 | if (!includeStructuredContent) {
188 | return {
189 | content: [{ type: "text", text: content }],
190 | isError: false
191 | };
192 | }
193 |
194 | // Include structured metadata when explicitly requested
195 | return this.createToolResponse(content, {
196 | tool: "prompt_manager",
197 | operation,
198 | executionType: "prompt",
199 | frameworkEnabled: false,
200 | operationData: {
201 | promptId: promptData?.promptId,
202 | category: promptData?.category,
203 | analysisResult: promptData?.analysisResult,
204 | affectedFiles: promptData?.affectedFiles
205 | }
206 | });
207 | }
208 |
209 | /**
210 | * Create a response for execution operations
211 | */
212 | static createExecutionResponse(
213 | content: string,
214 | operation: string,
215 | executionData?: {
216 | executionType?: "prompt" | "template" | "chain";
217 | executionTime?: number;
218 | frameworkUsed?: string;
219 | stepsExecuted?: number;
220 | sessionId?: string;
221 | gateResults?: any;
222 | },
223 | includeStructuredContent: boolean = true
224 | ): ToolResponse {
225 | // For template/prompt execution, return simple text response so Claude Code can see instructions
226 | if (!includeStructuredContent) {
227 | return {
228 | content: [{ type: "text", text: content }],
229 | isError: false
230 | };
231 | }
232 |
233 | // For other operations (chains, etc.), include full structured metadata
234 | return this.createToolResponse(content, {
235 | tool: "prompt_engine",
236 | operation,
237 | executionType: executionData?.executionType || "prompt",
238 | executionTime: executionData?.executionTime,
239 | frameworkEnabled: !!executionData?.frameworkUsed,
240 | frameworkUsed: executionData?.frameworkUsed,
241 | stepsExecuted: executionData?.stepsExecuted,
242 | sessionId: executionData?.sessionId,
243 | gateValidation: executionData?.gateResults
244 | });
245 | }
246 |
247 | /**
248 | * Create a response for system control operations
249 | */
250 | static createSystemResponse(
251 | content: string,
252 | operation: string,
253 | systemData?: {
254 | frameworkState?: any;
255 | systemHealth?: any;
256 | configChanges?: any;
257 | analytics?: any;
258 | },
259 | includeStructuredContent: boolean = false
260 | ): ToolResponse {
261 | // Return simple text response by default for Claude Code visibility
262 | if (!includeStructuredContent) {
263 | return {
264 | content: [{ type: "text", text: content }],
265 | isError: false
266 | };
267 | }
268 |
269 | // Include structured metadata when explicitly requested
270 | return this.createToolResponse(content, {
271 | tool: "system_control",
272 | operation,
273 | executionType: "prompt",
274 | frameworkEnabled: true,
275 | analytics: systemData?.analytics,
276 | operationData: {
277 | frameworkState: systemData?.frameworkState,
278 | systemHealth: systemData?.systemHealth,
279 | configChanges: systemData?.configChanges
280 | }
281 | });
282 | }
283 | }
284 |
285 | // Export convenience functions for easier usage (using function wrappers to avoid class reference timing issues)
286 | export function createToolResponse(content: string, metadata: ResponseMetadata): ToolResponse {
287 | return StructuredResponseBuilder.createToolResponse(content, metadata);
288 | }
289 |
290 | export function createErrorResponse(error: Error | string, context: ErrorContext): ToolResponse {
291 | return StructuredResponseBuilder.createErrorResponse(error, context);
292 | }
293 |
294 | export function createSimpleResponse(content: string, tool: string, operation: string): ToolResponse {
295 | return StructuredResponseBuilder.createSimpleResponse(content, tool, operation);
296 | }
297 |
298 | export function createPromptResponse(
299 | content: string,
300 | operation: string,
301 | promptData?: {
302 | promptId?: string;
303 | category?: string;
304 | analysisResult?: any;
305 | affectedFiles?: string[];
306 | },
307 | includeStructuredContent: boolean = false
308 | ): ToolResponse {
309 | return StructuredResponseBuilder.createPromptResponse(content, operation, promptData, includeStructuredContent);
310 | }
311 |
312 | export function createExecutionResponse(
313 | content: string,
314 | operation: string,
315 | executionData?: {
316 | executionType?: "prompt" | "template" | "chain";
317 | executionTime?: number;
318 | frameworkUsed?: string;
319 | stepsExecuted?: number;
320 | sessionId?: string;
321 | gateResults?: any;
322 | },
323 | includeStructuredContent: boolean = true
324 | ): ToolResponse {
325 | return StructuredResponseBuilder.createExecutionResponse(content, operation, executionData, includeStructuredContent);
326 | }
327 |
328 | export function createSystemResponse(
329 | content: string,
330 | operation: string,
331 | systemData?: {
332 | frameworkState?: any;
333 | systemHealth?: any;
334 | configChanges?: any;
335 | analytics?: any;
336 | },
337 | includeStructuredContent: boolean = false
338 | ): ToolResponse {
339 | return StructuredResponseBuilder.createSystemResponse(content, operation, systemData, includeStructuredContent);
340 | }
```
--------------------------------------------------------------------------------
/server/src/frameworks/methodology/registry.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Methodology Registry - Phase 2 Implementation
3 | *
4 | * Centralized registry for loading and managing methodology guides.
5 | * Extracted from FrameworkManager to provide clear separation of concerns
6 | * and enable better methodology guide management.
7 | */
8 |
9 | import { Logger } from "../../logging/index.js";
10 | import {
11 | IMethodologyGuide,
12 | FrameworkDefinition,
13 | FrameworkMethodology
14 | } from "../types/index.js";
15 | import { CAGEERFMethodologyGuide } from "./guides/cageerf-guide.js";
16 | import { ReACTMethodologyGuide } from "./guides/react-guide.js";
17 | import { FiveW1HMethodologyGuide } from "./guides/5w1h-guide.js";
18 | import { SCAMPERMethodologyGuide } from "./guides/scamper-guide.js";
19 |
20 | /**
21 | * Methodology registry configuration
22 | */
23 | export interface MethodologyRegistryConfig {
24 | /** Whether to auto-load built-in methodology guides */
25 | autoLoadBuiltIn: boolean;
26 | /** Custom methodology guides to load */
27 | customGuides?: IMethodologyGuide[];
28 | /** Whether to validate guides on registration */
29 | validateOnRegistration: boolean;
30 | }
31 |
32 | /**
33 | * Methodology guide registry entry
34 | */
35 | export interface MethodologyGuideEntry {
36 | guide: IMethodologyGuide;
37 | registeredAt: Date;
38 | isBuiltIn: boolean;
39 | enabled: boolean;
40 | metadata: {
41 | loadTime: number;
42 | validationStatus: 'passed' | 'failed' | 'not_validated';
43 | lastUsed?: Date;
44 | };
45 | }
46 |
47 | /**
48 | * Methodology Registry
49 | *
50 | * Manages the loading, registration, and lifecycle of methodology guides.
51 | * Provides a clean separation between guide management and framework orchestration.
52 | */
53 | export class MethodologyRegistry {
54 | private guides = new Map<string, MethodologyGuideEntry>();
55 | private logger: Logger;
56 | private config: MethodologyRegistryConfig;
57 | private initialized = false;
58 |
59 | constructor(logger: Logger, config: Partial<MethodologyRegistryConfig> = {}) {
60 | this.logger = logger;
61 | this.config = {
62 | autoLoadBuiltIn: config.autoLoadBuiltIn ?? true,
63 | customGuides: config.customGuides ?? [],
64 | validateOnRegistration: config.validateOnRegistration ?? true
65 | };
66 | }
67 |
68 | /**
69 | * Initialize the methodology registry
70 | */
71 | async initialize(): Promise<void> {
72 | if (this.initialized) {
73 | this.logger.debug("MethodologyRegistry already initialized");
74 | return;
75 | }
76 |
77 | this.logger.info("Initializing MethodologyRegistry...");
78 | const startTime = performance.now();
79 |
80 | try {
81 | // Load built-in methodology guides if enabled
82 | if (this.config.autoLoadBuiltIn) {
83 | await this.loadBuiltInGuides();
84 | }
85 |
86 | // Load custom guides if provided
87 | if (this.config.customGuides && this.config.customGuides.length > 0) {
88 | await this.loadCustomGuides(this.config.customGuides);
89 | }
90 |
91 | const loadTime = performance.now() - startTime;
92 | this.initialized = true;
93 |
94 | this.logger.info(
95 | `MethodologyRegistry initialized with ${this.guides.size} guides in ${loadTime.toFixed(1)}ms`
96 | );
97 | } catch (error) {
98 | this.logger.error("Failed to initialize MethodologyRegistry:", error);
99 | throw error;
100 | }
101 | }
102 |
103 | /**
104 | * Register a methodology guide
105 | */
106 | async registerGuide(
107 | guide: IMethodologyGuide,
108 | isBuiltIn: boolean = false
109 | ): Promise<boolean> {
110 | const startTime = performance.now();
111 |
112 | try {
113 | // Validate guide if required
114 | if (this.config.validateOnRegistration) {
115 | const validationResult = this.validateGuide(guide);
116 | if (!validationResult.valid) {
117 | this.logger.warn(
118 | `Guide validation failed for ${guide.frameworkId}: ${validationResult.errors.join(', ')}`
119 | );
120 | return false;
121 | }
122 | }
123 |
124 | // Check for existing guide with same ID
125 | if (this.guides.has(guide.frameworkId)) {
126 | this.logger.warn(`Guide with ID '${guide.frameworkId}' already registered, replacing...`);
127 | }
128 |
129 | // Create registry entry
130 | const entry: MethodologyGuideEntry = {
131 | guide,
132 | registeredAt: new Date(),
133 | isBuiltIn,
134 | enabled: true,
135 | metadata: {
136 | loadTime: performance.now() - startTime,
137 | validationStatus: this.config.validateOnRegistration ? 'passed' : 'not_validated'
138 | }
139 | };
140 |
141 | this.guides.set(guide.frameworkId, entry);
142 |
143 | this.logger.debug(
144 | `Registered ${isBuiltIn ? 'built-in' : 'custom'} methodology guide: ${guide.frameworkName} (${guide.frameworkId})`
145 | );
146 |
147 | return true;
148 | } catch (error) {
149 | this.logger.error(`Failed to register methodology guide ${guide.frameworkId}:`, error);
150 | return false;
151 | }
152 | }
153 |
154 | /**
155 | * Get a methodology guide by ID
156 | */
157 | getGuide(guideId: string): IMethodologyGuide | undefined {
158 | this.ensureInitialized();
159 |
160 | const entry = this.guides.get(guideId.toLowerCase());
161 | if (entry && entry.enabled) {
162 | // Update last used timestamp
163 | entry.metadata.lastUsed = new Date();
164 | return entry.guide;
165 | }
166 |
167 | return undefined;
168 | }
169 |
170 | /**
171 | * Get all registered methodology guides
172 | */
173 | getAllGuides(enabledOnly: boolean = true): IMethodologyGuide[] {
174 | this.ensureInitialized();
175 |
176 | const guides: IMethodologyGuide[] = [];
177 | for (const [_, entry] of this.guides) {
178 | if (!enabledOnly || entry.enabled) {
179 | guides.push(entry.guide);
180 | }
181 | }
182 |
183 | return guides;
184 | }
185 |
186 | /**
187 | * Get guide entries with metadata
188 | */
189 | getGuideEntries(enabledOnly: boolean = true): MethodologyGuideEntry[] {
190 | this.ensureInitialized();
191 |
192 | const entries: MethodologyGuideEntry[] = [];
193 | for (const [_, entry] of this.guides) {
194 | if (!enabledOnly || entry.enabled) {
195 | entries.push(entry);
196 | }
197 | }
198 |
199 | return entries;
200 | }
201 |
202 | /**
203 | * Check if a guide is registered
204 | */
205 | hasGuide(guideId: string): boolean {
206 | this.ensureInitialized();
207 | return this.guides.has(guideId.toLowerCase());
208 | }
209 |
210 | /**
211 | * Enable or disable a methodology guide
212 | */
213 | setGuideEnabled(guideId: string, enabled: boolean): boolean {
214 | this.ensureInitialized();
215 |
216 | const entry = this.guides.get(guideId.toLowerCase());
217 | if (entry) {
218 | entry.enabled = enabled;
219 | this.logger.info(`Methodology guide '${guideId}' ${enabled ? 'enabled' : 'disabled'}`);
220 | return true;
221 | }
222 |
223 | this.logger.warn(`Cannot ${enabled ? 'enable' : 'disable'} guide '${guideId}': not found`);
224 | return false;
225 | }
226 |
227 | /**
228 | * Get registry statistics
229 | */
230 | getRegistryStats() {
231 | this.ensureInitialized();
232 |
233 | const entries = Array.from(this.guides.values());
234 | const enabledCount = entries.filter(e => e.enabled).length;
235 | const builtInCount = entries.filter(e => e.isBuiltIn).length;
236 |
237 | return {
238 | totalGuides: entries.length,
239 | enabledGuides: enabledCount,
240 | builtInGuides: builtInCount,
241 | customGuides: entries.length - builtInCount,
242 | averageLoadTime: entries.reduce((sum, e) => sum + e.metadata.loadTime, 0) / entries.length || 0,
243 | initialized: this.initialized
244 | };
245 | }
246 |
247 | // Private implementation methods
248 |
249 | /**
250 | * Load built-in methodology guides
251 | */
252 | private async loadBuiltInGuides(): Promise<void> {
253 | this.logger.debug("Loading built-in methodology guides...");
254 |
255 | const builtInGuides = [
256 | new CAGEERFMethodologyGuide(),
257 | new ReACTMethodologyGuide(),
258 | new FiveW1HMethodologyGuide(),
259 | new SCAMPERMethodologyGuide()
260 | ];
261 |
262 | for (const guide of builtInGuides) {
263 | const success = await this.registerGuide(guide, true);
264 | if (!success) {
265 | this.logger.warn(`Failed to register built-in guide: ${guide.frameworkName}`);
266 | }
267 | }
268 |
269 | this.logger.info(`Loaded ${builtInGuides.length} built-in methodology guides`);
270 | }
271 |
272 | /**
273 | * Load custom methodology guides
274 | */
275 | private async loadCustomGuides(customGuides: IMethodologyGuide[]): Promise<void> {
276 | this.logger.debug(`Loading ${customGuides.length} custom methodology guides...`);
277 |
278 | for (const guide of customGuides) {
279 | const success = await this.registerGuide(guide, false);
280 | if (!success) {
281 | this.logger.warn(`Failed to register custom guide: ${guide.frameworkName}`);
282 | }
283 | }
284 |
285 | this.logger.info(`Loaded ${customGuides.length} custom methodology guides`);
286 | }
287 |
288 | /**
289 | * Validate a methodology guide
290 | */
291 | private validateGuide(guide: IMethodologyGuide): { valid: boolean; errors: string[] } {
292 | const errors: string[] = [];
293 |
294 | // Check required properties
295 | if (!guide.frameworkId || typeof guide.frameworkId !== 'string') {
296 | errors.push('frameworkId is required and must be a string');
297 | }
298 |
299 | if (!guide.frameworkName || typeof guide.frameworkName !== 'string') {
300 | errors.push('frameworkName is required and must be a string');
301 | }
302 |
303 | if (!guide.methodology || typeof guide.methodology !== 'string') {
304 | errors.push('methodology is required and must be a string');
305 | }
306 |
307 | if (!guide.version || typeof guide.version !== 'string') {
308 | errors.push('version is required and must be a string');
309 | }
310 |
311 | // Check required methods exist
312 | const requiredMethods = [
313 | 'guidePromptCreation',
314 | 'guideTemplateProcessing',
315 | 'guideExecutionSteps',
316 | 'enhanceWithMethodology',
317 | 'validateMethodologyCompliance',
318 | 'getSystemPromptGuidance'
319 | ];
320 |
321 | for (const method of requiredMethods) {
322 | if (typeof (guide as any)[method] !== 'function') {
323 | errors.push(`Required method '${method}' is missing or not a function`);
324 | }
325 | }
326 |
327 | return {
328 | valid: errors.length === 0,
329 | errors
330 | };
331 | }
332 |
333 | /**
334 | * Ensure registry is initialized
335 | */
336 | private ensureInitialized(): void {
337 | if (!this.initialized) {
338 | throw new Error("MethodologyRegistry not initialized. Call initialize() first.");
339 | }
340 | }
341 |
342 | /**
343 | * Get initialization status
344 | */
345 | get isInitialized(): boolean {
346 | return this.initialized;
347 | }
348 | }
349 |
350 | /**
351 | * Create and initialize a MethodologyRegistry instance
352 | */
353 | export async function createMethodologyRegistry(
354 | logger: Logger,
355 | config?: Partial<MethodologyRegistryConfig>
356 | ): Promise<MethodologyRegistry> {
357 | const registry = new MethodologyRegistry(logger, config);
358 | await registry.initialize();
359 | return registry;
360 | }
```
--------------------------------------------------------------------------------
/server/tests/scripts/unit-semantic-analyzer.js:
--------------------------------------------------------------------------------
```javascript
1 | #!/usr/bin/env node
2 | /**
3 | * Semantic Analyzer Unit Tests - Node.js Script Version
4 | * Tests the enhanced semantic analyzer for prompt/template/chain/workflow classification
5 | */
6 |
7 | async function runSemanticAnalyzerTests() {
8 | try {
9 | console.log('🧪 Running Semantic Analyzer unit tests...');
10 | console.log('📋 Testing prompt classification and analysis functionality');
11 |
12 | // Import modules - use configurable semantic analyzer which exists
13 | const semanticModule = await import('../../dist/analysis/configurable-semantic-analyzer.js');
14 |
15 | // Get SemanticAnalyzer from available exports
16 | const ConfigurableSemanticAnalyzer = semanticModule.ConfigurableSemanticAnalyzer;
17 |
18 | // Mock logger
19 | const mockLogger = {
20 | debug: () => {},
21 | info: () => {},
22 | warn: () => {},
23 | error: () => {}
24 | };
25 |
26 | let analyzer;
27 |
28 | // Setup for each test
29 | function setupTest() {
30 | analyzer = new ConfigurableSemanticAnalyzer(mockLogger, {
31 | enableCaching: false // Disable caching for consistent testing
32 | });
33 | }
34 |
35 | // Simple assertion helpers
36 | function assertEqual(actual, expected, testName) {
37 | if (actual === expected) {
38 | console.log(`✅ ${testName}: PASSED`);
39 | return true;
40 | } else {
41 | console.error(`❌ ${testName}: FAILED`);
42 | console.error(` Expected: ${expected}`);
43 | console.error(` Actual: ${actual}`);
44 | return false;
45 | }
46 | }
47 |
48 | function assertGreaterThan(actual, expected, testName) {
49 | if (actual > expected) {
50 | console.log(`✅ ${testName}: PASSED (${actual} > ${expected})`);
51 | return true;
52 | } else {
53 | console.error(`❌ ${testName}: FAILED (${actual} <= ${expected})`);
54 | return false;
55 | }
56 | }
57 |
58 | function assertTruthy(value, testName) {
59 | if (value) {
60 | console.log(`✅ ${testName}: PASSED`);
61 | return true;
62 | } else {
63 | console.error(`❌ ${testName}: FAILED - Expected truthy value, got: ${value}`);
64 | return false;
65 | }
66 | }
67 |
68 | let testResults = [];
69 |
70 | // Test 1: Basic Prompt Classification
71 | console.log('🔍 Test 1: Simple Prompt Classification');
72 |
73 | setupTest();
74 | const simplePrompt = {
75 | id: 'test_simple',
76 | name: 'Simple Test',
77 | description: 'Simple variable substitution',
78 | category: 'test',
79 | userMessageTemplate: 'Hello {{name}}, how are you?',
80 | arguments: [{ name: 'name', required: true, description: 'User name' }]
81 | };
82 |
83 | const simpleAnalysis = await analyzer.analyzePrompt(simplePrompt);
84 |
85 | testResults.push(assertEqual(simpleAnalysis.executionType, 'prompt', 'Simple prompt classified as "prompt"'));
86 | testResults.push(assertEqual(simpleAnalysis.requiresFramework, false, 'Simple prompt requires no framework'));
87 | testResults.push(assertGreaterThan(simpleAnalysis.confidence, 0.5, 'Simple prompt confidence > 0.5'));
88 | testResults.push(assertEqual(simpleAnalysis.frameworkRecommendation?.shouldUseFramework, false, 'No framework recommended for simple prompt'));
89 |
90 | // Test 2: Template Classification
91 | console.log('🔍 Test 2: Template Classification');
92 |
93 | setupTest();
94 | const templatePrompt = {
95 | id: 'test_template',
96 | name: 'Template Test',
97 | description: 'Complex template with conditional logic',
98 | category: 'test',
99 | userMessageTemplate: `
100 | {% if analysis_type == 'detailed' %}
101 | Perform detailed analysis of {{content}} considering:
102 | {% for aspect in aspects %}
103 | - {{aspect}}
104 | {% endfor %}
105 | {% else %}
106 | Quick analysis of {{content}}
107 | {% endif %}
108 | `,
109 | arguments: [
110 | { name: 'content', required: true, description: 'Content to analyze' },
111 | { name: 'analysis_type', required: false, description: 'Type of analysis' },
112 | { name: 'aspects', required: false, description: 'Analysis aspects' }
113 | ]
114 | };
115 |
116 | const templateAnalysis = await analyzer.analyzePrompt(templatePrompt);
117 |
118 | // ConfigurableSemanticAnalyzer analyzes based on content structure - 'chain' is valid for conditional logic
119 | testResults.push(assertTruthy(['template', 'prompt', 'chain'].includes(templateAnalysis.executionType), `Template classified appropriately (got: ${templateAnalysis.executionType})`));
120 | testResults.push(assertGreaterThan(templateAnalysis.confidence, 0.3, 'Template confidence reasonable'));
121 |
122 | // Test 3: Chain Classification
123 | console.log('🔍 Test 3: Chain Classification');
124 |
125 | setupTest();
126 | const chainPrompt = {
127 | id: 'test_chain',
128 | name: 'Chain Test',
129 | description: 'Multi-step chain execution with dependencies',
130 | category: 'test',
131 | userMessageTemplate: `
132 | Step 1: Analyze {{input_data}}
133 | Step 2: Based on the analysis from step 1, generate {{output_format}}
134 | Step 3: Validate the output and provide {{final_result}}
135 | `,
136 | arguments: [
137 | { name: 'input_data', required: true, description: 'Initial data' },
138 | { name: 'output_format', required: true, description: 'Desired output format' },
139 | { name: 'final_result', required: false, description: 'Final result type' }
140 | ]
141 | };
142 |
143 | const chainAnalysis = await analyzer.analyzePrompt(chainPrompt);
144 |
145 | testResults.push(assertTruthy(['chain', 'template', 'prompt'].includes(chainAnalysis.executionType), 'Chain classified to valid type'));
146 | testResults.push(assertGreaterThan(chainAnalysis.confidence, 0.3, 'Chain confidence reasonable'));
147 |
148 | // Test 4: Workflow Classification
149 | console.log('🔍 Test 4: Workflow Classification');
150 |
151 | setupTest();
152 | const workflowPrompt = {
153 | id: 'test_workflow',
154 | name: 'Workflow Test',
155 | description: 'Complex workflow with decision points and branching logic',
156 | category: 'test',
157 | userMessageTemplate: `
158 | WORKFLOW: Complex Decision Process
159 |
160 | IF condition_a THEN:
161 | EXECUTE branch_a WITH {{param_a}}
162 | VALIDATE result_a
163 | IF valid THEN continue ELSE abort
164 | ELSE:
165 | EXECUTE branch_b WITH {{param_b}}
166 | LOOP through {{items}} and process each
167 | MERGE results and finalize
168 |
169 | FINALLY: Generate {{final_output}}
170 | `,
171 | arguments: [
172 | { name: 'condition_a', required: true, description: 'Primary condition' },
173 | { name: 'param_a', required: false, description: 'Branch A parameter' },
174 | { name: 'param_b', required: false, description: 'Branch B parameter' },
175 | { name: 'items', required: false, description: 'Items to process' },
176 | { name: 'final_output', required: true, description: 'Final output type' }
177 | ]
178 | };
179 |
180 | const workflowAnalysis = await analyzer.analyzePrompt(workflowPrompt);
181 |
182 | testResults.push(assertTruthy(['workflow', 'chain', 'template', 'prompt'].includes(workflowAnalysis.executionType), 'Workflow classified to valid type'));
183 | testResults.push(assertGreaterThan(workflowAnalysis.confidence, 0.2, 'Workflow confidence reasonable'));
184 |
185 | // Test 5: Framework Requirements
186 | console.log('🔍 Test 5: Framework Requirements Analysis');
187 |
188 | setupTest();
189 | const complexPrompt = {
190 | id: 'test_complex',
191 | name: 'Complex Analysis',
192 | description: 'Requires systematic analysis with CAGEERF methodology',
193 | category: 'analysis',
194 | userMessageTemplate: `
195 | Conduct comprehensive analysis using systematic approach:
196 | 1. CONTEXT: Understand the situation {{situation}}
197 | 2. ANALYSIS: Deep dive into {{subject}}
198 | 3. GOALS: Define clear objectives
199 | 4. EXECUTION: Implement solution
200 | 5. EVALUATION: Assess outcomes
201 | 6. REFINEMENT: Iterate and improve
202 | `,
203 | arguments: [
204 | { name: 'situation', required: true, description: 'Situation to analyze' },
205 | { name: 'subject', required: true, description: 'Analysis subject' }
206 | ]
207 | };
208 |
209 | const complexAnalysis = await analyzer.analyzePrompt(complexPrompt);
210 |
211 | testResults.push(assertTruthy(typeof complexAnalysis.requiresFramework === 'boolean', 'Framework requirement determined'));
212 | testResults.push(assertTruthy(complexAnalysis.frameworkRecommendation, 'Framework recommendation provided'));
213 |
214 | // Test 6: Confidence Scoring
215 | console.log('🔍 Test 6: Confidence Scoring Validation');
216 |
217 | // Test that confidence is always within valid range
218 | const analysisResults = [simpleAnalysis, templateAnalysis, chainAnalysis, workflowAnalysis, complexAnalysis];
219 |
220 | for (let i = 0; i < analysisResults.length; i++) {
221 | const analysis = analysisResults[i];
222 | testResults.push(assertGreaterThan(analysis.confidence, 0, `Analysis ${i+1} confidence > 0`));
223 | testResults.push(assertTruthy(analysis.confidence <= 1, `Analysis ${i+1} confidence <= 1`));
224 | }
225 |
226 | // Test 7: Reasoning Provided
227 | console.log('🔍 Test 7: Analysis Reasoning');
228 |
229 | for (let i = 0; i < analysisResults.length; i++) {
230 | const analysis = analysisResults[i];
231 | testResults.push(assertTruthy(Array.isArray(analysis.reasoning), `Analysis ${i+1} has reasoning array`));
232 | testResults.push(assertTruthy(analysis.reasoning.length > 0, `Analysis ${i+1} reasoning not empty`));
233 | }
234 |
235 | // Results Summary
236 | const passedTests = testResults.filter(result => result).length;
237 | const totalTests = testResults.length;
238 |
239 | console.log('\n📊 Semantic Analyzer Unit Tests Summary:');
240 | console.log(` ✅ Passed: ${passedTests}/${totalTests} tests`);
241 | console.log(` 📊 Success Rate: ${((passedTests/totalTests)*100).toFixed(1)}%`);
242 |
243 | if (passedTests === totalTests) {
244 | console.log('🎉 All Semantic Analyzer unit tests passed!');
245 | return true;
246 | } else {
247 | console.error('❌ Some Semantic Analyzer tests failed');
248 | return false;
249 | }
250 |
251 | } catch (error) {
252 | console.error('❌ Semantic Analyzer tests failed with error:', error.message);
253 | if (error.stack) {
254 | console.error('Stack trace:', error.stack);
255 | }
256 | return false;
257 | }
258 | }
259 |
260 | // Run the tests
261 | if (import.meta.url === `file://${process.argv[1]}`) {
262 | runSemanticAnalyzerTests().catch(error => {
263 | console.error('❌ Test execution failed:', error);
264 | process.exit(1);
265 | });
266 | }
267 |
268 | export { runSemanticAnalyzerTests };
```
--------------------------------------------------------------------------------
/server/prompts/development/prompts.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "prompts": [
3 | {
4 | "id": "expert_code_implementation",
5 | "name": "Expert Code Implementation",
6 | "category": "development",
7 | "description": "Expert implementation of refined coding requirements with comprehensive explanation and best practices.",
8 | "file": "expert_code_implementation.md",
9 | "arguments": [
10 | {
11 | "name": "refined_query",
12 | "description": "The refined coding request",
13 | "required": true
14 | },
15 | {
16 | "name": "language",
17 | "description": "The programming language to use",
18 | "required": true
19 | },
20 | {
21 | "name": "requirements",
22 | "description": "The functional requirements",
23 | "required": true
24 | },
25 | {
26 | "name": "constraints",
27 | "description": "Any performance/security/quality considerations",
28 | "required": false
29 | }
30 | ],
31 | "gates": [
32 | "security-awareness",
33 | "code-quality",
34 | "technical-accuracy"
35 | ]
36 | },
37 | {
38 | "id": "code_review_optimization_chain",
39 | "name": "Comprehensive Code Review",
40 | "category": "development",
41 | "description": "Systematic 6-step code review covering structure, functionality, security, performance, optimization, and quality assurance",
42 | "file": "code_review_optimization_chain.md",
43 | "arguments": [
44 | {
45 | "name": "target_code",
46 | "description": "The code to be reviewed and optimized",
47 | "required": true
48 | },
49 | {
50 | "name": "language_framework",
51 | "description": "Programming language and framework being used",
52 | "required": true
53 | },
54 | {
55 | "name": "performance_goals",
56 | "description": "Specific performance targets or optimization goals",
57 | "required": false
58 | }
59 | ]
60 | },
61 | {
62 | "id": "detect_project_commands",
63 | "name": "Project Commands Detection",
64 | "category": "development",
65 | "description": "Intelligently detects and configures project validation commands (lint, test, build) for different project types with Enhanced CAGEERF integration",
66 | "file": "detect_project_commands.md",
67 | "arguments": [
68 | {
69 | "name": "project_path",
70 | "description": "Path to the project directory",
71 | "required": true
72 | },
73 | {
74 | "name": "project_type",
75 | "description": "Type of project (nodejs, rust, python, go, etc.)",
76 | "required": true
77 | }
78 | ]
79 | },
80 | {
81 | "id": "generate_comprehensive_claude_md",
82 | "name": "Comprehensive CLAUDE.md Generator",
83 | "category": "development",
84 | "description": "Generates comprehensive CLAUDE.md files with all 6 development criteria, Enhanced CAGEERF integration, and project-specific configurations",
85 | "file": "generate_comprehensive_claude_md.md",
86 | "arguments": [
87 | {
88 | "name": "project_path",
89 | "description": "Path to the project directory",
90 | "required": true
91 | },
92 | {
93 | "name": "project_name",
94 | "description": "Name of the project",
95 | "required": true
96 | },
97 | {
98 | "name": "project_type",
99 | "description": "Type of project",
100 | "required": true
101 | },
102 | {
103 | "name": "architecture_level",
104 | "description": "Architecture sophistication level 1-10",
105 | "required": true
106 | },
107 | {
108 | "name": "project_commands",
109 | "description": "JSON object with detected project commands",
110 | "required": true
111 | }
112 | ]
113 | },
114 | {
115 | "id": "analyze_file_structure",
116 | "name": "Analyze File Structure",
117 | "category": "development",
118 | "description": "Analyzes a file's structure to identify potential modules, dependencies, and organization patterns for refactoring.",
119 | "file": "analyze_file_structure.md",
120 | "arguments": [
121 | {
122 | "name": "code",
123 | "description": "The source code to analyze",
124 | "required": true
125 | },
126 | {
127 | "name": "language",
128 | "description": "Programming language of the code",
129 | "required": true
130 | },
131 | {
132 | "name": "file_path",
133 | "description": "Path to the file being analyzed",
134 | "required": true
135 | }
136 | ]
137 | },
138 | {
139 | "id": "create_modularization_plan",
140 | "name": "Create Modularization Plan",
141 | "category": "development",
142 | "description": "Creates a detailed plan for splitting a file into smaller, more maintainable modules based on analysis of its structure and dependencies.",
143 | "file": "create_modularization_plan.md",
144 | "arguments": [
145 | {
146 | "name": "language",
147 | "description": "Programming language of the code",
148 | "required": true
149 | },
150 | {
151 | "name": "file_path",
152 | "description": "Path to the file being modularized",
153 | "required": true
154 | },
155 | {
156 | "name": "analysis_results",
157 | "description": "Results from the file structure analysis",
158 | "required": true
159 | }
160 | ]
161 | },
162 | {
163 | "id": "transform_code_to_modules",
164 | "name": "Transform Code to Modules",
165 | "category": "development",
166 | "description": "Transforms a large file into multiple smaller module files according to a modularization plan, ensuring proper imports/exports and maintaining functionality.",
167 | "file": "transform_code_to_modules.md",
168 | "arguments": [
169 | {
170 | "name": "language",
171 | "description": "Programming language of the code",
172 | "required": true
173 | },
174 | {
175 | "name": "file_path",
176 | "description": "Path to the original file",
177 | "required": true
178 | },
179 | {
180 | "name": "original_code",
181 | "description": "The original source code to be modularized",
182 | "required": true
183 | },
184 | {
185 | "name": "modularization_plan",
186 | "description": "The detailed plan for how to split the code",
187 | "required": true
188 | }
189 | ]
190 | },
191 | {
192 | "id": "test_temporary_gates",
193 | "name": "Test Temporary Gates Implementation",
194 | "category": "development",
195 | "description": "Test prompt for validating the enhanced gate system with temporary gates. Demonstrates 5-level precedence, execution-scoped lifecycle management, and multiple gate types.",
196 | "file": "test-temporary-gates.md",
197 | "arguments": [
198 | {
199 | "name": "analysis_type",
200 | "description": "Type of analysis to perform (e.g., 'technical specification', 'architectural design', 'implementation plan')",
201 | "required": true
202 | },
203 | {
204 | "name": "topic",
205 | "description": "The main subject to analyze",
206 | "required": true
207 | },
208 | {
209 | "name": "content",
210 | "description": "The content or scenario to analyze",
211 | "required": true
212 | },
213 | {
214 | "name": "focus_area",
215 | "description": "Specific area to emphasize in the analysis",
216 | "required": true
217 | },
218 | {
219 | "name": "context",
220 | "description": "The broader context or use case for the analysis",
221 | "required": true
222 | }
223 | ],
224 | "gates": [
225 | "content-structure",
226 | "technical-accuracy"
227 | ]
228 | },
229 | {
230 | "id": "strategicImplement",
231 | "name": "Strategic Implementation",
232 | "category": "development",
233 | "description": "Systematically implement a plan phase with architectural alignment, compatibility checking, and progress tracking",
234 | "file": "strategicImplement.md",
235 | "arguments": [
236 | {
237 | "name": "plan_path",
238 | "type": "string",
239 | "description": "Path to the plan document to implement (e.g., plans/current/feature-plan.md)"
240 | },
241 | {
242 | "name": "phase_identifier",
243 | "type": "string",
244 | "description": "Specific phase to implement (e.g., 'Phase 1', 'Phase 2A', 'Step 3: Integration')"
245 | }
246 | ]
247 | },
248 | {
249 | "id": "component_flow_analysis",
250 | "name": "Component Flow Analysis",
251 | "category": "development",
252 | "description": "Comprehensive component review that tracks data flow, lifecycle, dependencies, and integration points",
253 | "file": "component_flow_analysis.md",
254 | "arguments": [
255 | {
256 | "name": "component_path",
257 | "type": "string",
258 | "description": "Path to the component file (e.g., src/components/UserProfile.tsx)"
259 | },
260 | {
261 | "name": "component_code",
262 | "type": "string",
263 | "description": "The complete component source code to analyze"
264 | },
265 | {
266 | "name": "framework",
267 | "type": "string",
268 | "description": "Framework being used (React, Vue, Angular, Svelte, etc.)"
269 | },
270 | {
271 | "name": "language",
272 | "type": "string",
273 | "description": "Programming language (JavaScript, TypeScript, etc.)"
274 | }
275 | ]
276 | },
277 | {
278 | "id": "test_concise_format",
279 | "name": "Test Concise Format",
280 | "category": "development",
281 | "description": "Testing the new concise message format",
282 | "file": "test_concise_format.md",
283 | "arguments": [
284 | {
285 | "name": "test_param",
286 | "type": "string",
287 | "description": "Test parameter"
288 | }
289 | ]
290 | },
291 | {
292 | "id": "test_concise_v2",
293 | "name": "Test Concise Format V2",
294 | "category": "development",
295 | "description": "Testing the simplified concise message format after restart",
296 | "file": "test_concise_v2.md",
297 | "arguments": [
298 | {
299 | "name": "input",
300 | "type": "string",
301 | "description": "Test input"
302 | }
303 | ]
304 | },
305 | {
306 | "id": "test_final_concise",
307 | "name": "Test Final Concise Format",
308 | "category": "development",
309 | "description": "Final test of concise message format with isLLMEnabled() fix",
310 | "file": "test_final_concise.md",
311 | "arguments": [
312 | {
313 | "name": "test_input",
314 | "type": "string",
315 | "description": "Test input parameter"
316 | }
317 | ]
318 | }
319 | ]
320 | }
```
--------------------------------------------------------------------------------
/server/src/gates/guidance/GateGuidanceRenderer.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Gate Guidance Renderer - User-Facing Guidance Generation
3 | *
4 | * Single responsibility: Generate and format gate guidance for users.
5 | * Clean dependencies: Only imports what it needs for guidance rendering.
6 | */
7 |
8 | import * as fs from 'fs/promises';
9 | import * as path from 'path';
10 | import { fileURLToPath } from 'url';
11 | import type { Logger } from '../../logging/index.js';
12 | import { GateDefinition, GateContext } from '../core/gate-definitions.js';
13 | import { filterFrameworkGuidance, hasFrameworkSpecificContent } from './FrameworkGuidanceFilter.js';
14 | import type { TemporaryGateRegistry } from '../core/temporary-gate-registry.js';
15 |
16 | /**
17 | * Gate guidance renderer with framework-specific filtering and temporary gate support
18 | */
19 | export class GateGuidanceRenderer {
20 | private gateCache = new Map<string, GateDefinition>();
21 | private gatesDirectory: string;
22 | private logger: Logger;
23 | private temporaryGateRegistry?: TemporaryGateRegistry;
24 |
25 | constructor(logger: Logger, gatesDirectory?: string, temporaryGateRegistry?: TemporaryGateRegistry) {
26 | this.logger = logger;
27 | // Use same directory resolution pattern as existing system
28 | const __filename = fileURLToPath(import.meta.url);
29 | const __dirname = path.dirname(__filename);
30 | this.gatesDirectory = gatesDirectory || path.join(__dirname, '../../gates/definitions');
31 | this.temporaryGateRegistry = temporaryGateRegistry;
32 |
33 | this.logger.debug('[GATE GUIDANCE RENDERER] Initialized with directory:', this.gatesDirectory);
34 | if (temporaryGateRegistry) {
35 | this.logger.debug('[GATE GUIDANCE RENDERER] Temporary gate registry enabled');
36 | }
37 | }
38 |
39 | /**
40 | * Generate formatted gate guidance for display to users
41 | *
42 | * @param gateIds - Array of gate IDs to render
43 | * @param context - Context for gate activation and framework filtering
44 | * @returns Formatted guidance text ready for display
45 | */
46 | async renderGuidance(gateIds: string[], context: GateContext = {}): Promise<string> {
47 | this.logger.info('🎨 [GATE GUIDANCE RENDERER] renderGuidance called:', {
48 | gateIds,
49 | framework: context.framework,
50 | category: context.category,
51 | gatesDirectory: this.gatesDirectory
52 | });
53 |
54 | if (gateIds.length === 0) {
55 | this.logger.debug('[GATE GUIDANCE RENDERER] No gates provided, returning empty guidance');
56 | return '';
57 | }
58 |
59 | const guidanceTexts: string[] = [];
60 |
61 | for (const gateId of gateIds) {
62 | try {
63 | const gate = await this.loadGateDefinition(gateId);
64 | if (gate) {
65 | if (this.shouldActivateGate(gate, context)) {
66 | guidanceTexts.push(this.formatGateGuidance(gate, context));
67 | this.logger.debug('[GATE GUIDANCE RENDERER] Added guidance for gate:', gateId);
68 | } else {
69 | this.logger.debug('[GATE GUIDANCE RENDERER] Skipped gate (not applicable):', gateId);
70 | }
71 | } else {
72 | this.logger.debug('[GATE GUIDANCE RENDERER] Failed to load gate:', gateId);
73 | }
74 | } catch (error) {
75 | this.logger.warn('[GATE GUIDANCE RENDERER] Failed to load gate:', gateId, error);
76 | }
77 | }
78 |
79 | if (guidanceTexts.length === 0) {
80 | this.logger.debug('[GATE GUIDANCE RENDERER] No applicable gates found, returning empty guidance');
81 | return '';
82 | }
83 |
84 | // Format as supplemental guidance section (clean formatting)
85 | // NOTE: Framework is already described in tool descriptions and system prompt
86 | // so we don't duplicate the framework reference in the header
87 | const supplementalGuidance = `
88 |
89 | ---
90 |
91 | ## 🎯 Quality Enhancement Gates
92 |
93 | ${guidanceTexts.join('\n\n')}
94 |
95 | ---`;
96 |
97 | this.logger.debug('[GATE GUIDANCE RENDERER] Generated supplemental guidance:', {
98 | gateCount: guidanceTexts.length,
99 | guidanceLength: supplementalGuidance.length
100 | });
101 |
102 | return supplementalGuidance;
103 | }
104 |
105 | /**
106 | * Load gate definition from temporary registry or file system
107 | */
108 | private async loadGateDefinition(gateId: string): Promise<GateDefinition | null> {
109 | // Check cache first (performance optimization)
110 | if (this.gateCache.has(gateId)) {
111 | return this.gateCache.get(gateId)!;
112 | }
113 |
114 | // Phase 3 Enhancement: Check temporary gate registry first for temp_ prefixed gates
115 | if (gateId.startsWith('temp_') && this.temporaryGateRegistry) {
116 | this.logger.debug('[GATE GUIDANCE RENDERER] Attempting to load temporary gate:', gateId);
117 | const tempGate = this.temporaryGateRegistry.getTemporaryGate(gateId);
118 |
119 | if (tempGate) {
120 | // Convert temporary gate to standard gate definition format
121 | const gate: GateDefinition = {
122 | id: tempGate.id,
123 | name: tempGate.name,
124 | guidance: tempGate.guidance,
125 | activation: {
126 | explicit_request: true // Temporary gates are explicitly requested
127 | }
128 | };
129 |
130 | // Cache for reuse during this execution
131 | this.gateCache.set(gateId, gate);
132 | this.logger.info('[GATE GUIDANCE RENDERER] ✅ Loaded temporary gate:', {
133 | gateId,
134 | name: tempGate.name,
135 | guidanceLength: tempGate.guidance.length
136 | });
137 |
138 | return gate;
139 | } else {
140 | this.logger.warn('[GATE GUIDANCE RENDERER] ⚠️ Temporary gate not found in registry:', gateId);
141 | }
142 | }
143 |
144 | // Fall back to filesystem for non-temporary gates or if registry lookup fails
145 | try {
146 | const gateFile = path.join(this.gatesDirectory, `${gateId}.json`);
147 | const fileContent = await fs.readFile(gateFile, 'utf-8');
148 | const gateData = JSON.parse(fileContent);
149 |
150 | // Extract essential fields for guidance rendering
151 | const gate: GateDefinition = {
152 | id: gateData.id,
153 | name: gateData.name,
154 | guidance: gateData.guidance || '',
155 | activation: gateData.activation || {}
156 | };
157 |
158 | // Cache for reuse (performance optimization)
159 | this.gateCache.set(gateId, gate);
160 | this.logger.debug('[GATE GUIDANCE RENDERER] Loaded and cached gate definition from filesystem:', gateId);
161 |
162 | return gate;
163 | } catch (error) {
164 | this.logger.error('[GATE GUIDANCE RENDERER] Failed to load gate definition:', gateId, error);
165 | return null;
166 | }
167 | }
168 |
169 | /**
170 | * Check if gate should be activated for current context
171 | *
172 | * Framework gates (gate_type: "framework") bypass category checks and activate
173 | * based on framework context alone. This ensures framework methodology guidance
174 | * applies universally across all categories.
175 | */
176 | private shouldActivateGate(gate: GateDefinition, context: GateContext): boolean {
177 | const activation = gate.activation;
178 | const isFrameworkGate = gate.gate_type === 'framework' || gate.id === 'framework-compliance';
179 |
180 | this.logger.debug('[GATE GUIDANCE RENDERER] shouldActivateGate called:', {
181 | gateId: gate.id,
182 | gateType: gate.gate_type,
183 | isFrameworkGate,
184 | contextFramework: context.framework,
185 | activationFrameworkContext: activation.framework_context,
186 | contextCategory: context.category,
187 | activationPromptCategories: activation.prompt_categories
188 | });
189 |
190 | // Check framework context match
191 | if (context.framework && activation.framework_context) {
192 | if (!activation.framework_context.includes(context.framework)) {
193 | this.logger.debug('[GATE GUIDANCE RENDERER] Gate not activated - framework mismatch:', {
194 | gateId: gate.id,
195 | expectedFrameworks: activation.framework_context,
196 | actualFramework: context.framework
197 | });
198 | return false;
199 | }
200 |
201 | // Framework gates activate on framework match alone (bypass category checks)
202 | if (isFrameworkGate) {
203 | this.logger.info('[GATE GUIDANCE RENDERER] ✅ Framework gate activated (universal):', {
204 | gateId: gate.id,
205 | framework: context.framework,
206 | category: context.category
207 | });
208 | return true;
209 | }
210 | }
211 |
212 | // Category gates check category context match
213 | if (context.category && activation.prompt_categories) {
214 | if (!activation.prompt_categories.includes(context.category)) {
215 | this.logger.debug('[GATE GUIDANCE RENDERER] Gate not activated - category mismatch:', {
216 | gateId: gate.id,
217 | expectedCategories: activation.prompt_categories,
218 | actualCategory: context.category
219 | });
220 | return false;
221 | }
222 | }
223 |
224 | // If no specific criteria or all criteria match, activate
225 | this.logger.debug('[GATE GUIDANCE RENDERER] Gate activated:', gate.id);
226 | return true;
227 | }
228 |
229 | /**
230 | * Format gate guidance for display with framework-specific filtering
231 | */
232 | private formatGateGuidance(gate: GateDefinition, context: GateContext): string {
233 | let guidance = gate.guidance;
234 |
235 | // Apply framework filtering if framework is specified and guidance has framework content
236 | if (context.framework && hasFrameworkSpecificContent(guidance)) {
237 | guidance = filterFrameworkGuidance(guidance, context.framework);
238 | this.logger.debug('[GATE GUIDANCE RENDERER] Applied framework filtering for:', context.framework);
239 | }
240 |
241 | return `### ${gate.name}\n${guidance}`;
242 | }
243 |
244 | /**
245 | * Get available gate IDs (for testing and diagnostics)
246 | */
247 | async getAvailableGates(): Promise<string[]> {
248 | try {
249 | const files = await fs.readdir(this.gatesDirectory);
250 | const gateIds = files
251 | .filter(file => file.endsWith('.json'))
252 | .map(file => file.replace('.json', ''));
253 |
254 | this.logger.debug('[GATE GUIDANCE RENDERER] Available gates:', gateIds);
255 | return gateIds;
256 | } catch (error) {
257 | this.logger.error('[GATE GUIDANCE RENDERER] Failed to list gate definitions:', error);
258 | return [];
259 | }
260 | }
261 |
262 | /**
263 | * Clear cache (for hot-reloading support)
264 | */
265 | clearCache(): void {
266 | this.gateCache.clear();
267 | this.logger.debug('[GATE GUIDANCE RENDERER] Cache cleared for hot-reloading');
268 | }
269 |
270 | /**
271 | * Get renderer statistics (for monitoring)
272 | */
273 | getStatistics(): { cachedGates: number; gatesDirectory: string } {
274 | return {
275 | cachedGates: this.gateCache.size,
276 | gatesDirectory: this.gatesDirectory
277 | };
278 | }
279 | }
280 |
281 | /**
282 | * Factory function for creating gate guidance renderer
283 | */
284 | export function createGateGuidanceRenderer(logger: Logger, gatesDirectory?: string, temporaryGateRegistry?: TemporaryGateRegistry): GateGuidanceRenderer {
285 | return new GateGuidanceRenderer(logger, gatesDirectory, temporaryGateRegistry);
286 | }
```
--------------------------------------------------------------------------------
/server/src/mcp-tools/prompt-engine/utils/context-builder.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Context Builder - Handles execution context building
3 | *
4 | * Extracted from ConsolidatedPromptEngine to provide focused
5 | * context building capabilities with clear separation of concerns.
6 | */
7 |
8 | import { createLogger } from "../../../logging/index.js";
9 | import { FrameworkManager } from "../../../frameworks/framework-manager.js";
10 | import { FrameworkExecutionContext } from "../../../frameworks/types/index.js";
11 | import { FrameworkStateManager } from "../../../frameworks/framework-state-manager.js";
12 | import { ConvertedPrompt } from "../../../types/index.js";
13 | import { ExecutionContext } from "../../../execution/parsers/index.js";
14 |
15 | const logger = createLogger({
16 | logFile: '/tmp/context-builder.log',
17 | transport: 'stdio',
18 | enableDebug: false,
19 | configuredLevel: 'info'
20 | });
21 |
22 | export interface EnhancedExecutionContext extends ExecutionContext {
23 | promptId: string;
24 | promptArgs: Record<string, any>;
25 | executionMode: string;
26 | sessionId: string;
27 | forceRestart: boolean;
28 | enableGates: boolean;
29 | frameworkId?: string;
30 | contextData: Record<string, any>;
31 | frameworkContext?: FrameworkExecutionContext;
32 | metadata?: Record<string, any>;
33 | performance?: {
34 | startTime: number;
35 | memoryUsage?: number;
36 | };
37 | }
38 |
39 | /**
40 | * ContextBuilder handles all execution context building
41 | *
42 | * This class provides:
43 | * - Execution context creation and enhancement
44 | * - Framework integration and context injection
45 | * - Performance tracking and metadata collection
46 | * - Context validation and preparation
47 | */
48 | export class ContextBuilder {
49 | private frameworkManager?: FrameworkManager;
50 | private frameworkStateManager?: FrameworkStateManager;
51 |
52 | constructor(
53 | frameworkManager?: FrameworkManager,
54 | frameworkStateManager?: FrameworkStateManager
55 | ) {
56 | this.frameworkManager = frameworkManager;
57 | this.frameworkStateManager = frameworkStateManager;
58 | }
59 |
60 | /**
61 | * Build enhanced execution context
62 | */
63 | public buildExecutionContext(
64 | promptId: string,
65 | promptArgs: Record<string, any>,
66 | convertedPrompt: ConvertedPrompt,
67 | options: Record<string, any> = {}
68 | ): EnhancedExecutionContext {
69 | try {
70 | logger.debug('🔧 [ContextBuilder] Building execution context', {
71 | promptId,
72 | argsCount: Object.keys(promptArgs).length,
73 | hasFrameworkManager: !!this.frameworkManager
74 | });
75 |
76 | const startTime = Date.now();
77 | const memoryUsage = this.getMemoryUsage();
78 |
79 | // Build base context - properly typed for execution parsers
80 | const baseExecutionContext: ExecutionContext = {
81 | conversationHistory: options.conversationHistory,
82 | environmentVars: options.environmentVars,
83 | promptDefaults: options.promptDefaults,
84 | userSession: options.userSession,
85 | systemContext: options.systemContext
86 | };
87 |
88 | // Build enhanced context
89 | const enhancedContext: EnhancedExecutionContext = {
90 | ...baseExecutionContext,
91 | promptId,
92 | promptArgs,
93 | executionMode: options.executionMode || 'auto',
94 | sessionId: options.sessionId || this.generateSessionId(),
95 | forceRestart: options.forceRestart || false,
96 | enableGates: options.enableGates !== false,
97 | frameworkId: options.frameworkId,
98 | contextData: options.contextData || {},
99 | metadata: this.buildMetadata(convertedPrompt, options),
100 | performance: {
101 | startTime,
102 | memoryUsage
103 | }
104 | };
105 |
106 | // Add framework context if available
107 | if (this.frameworkManager && this.frameworkStateManager) {
108 | enhancedContext.frameworkContext = this.buildFrameworkContext(
109 | convertedPrompt,
110 | promptArgs,
111 | options
112 | );
113 | }
114 |
115 | logger.debug('✅ [ContextBuilder] Execution context built successfully', {
116 | promptId,
117 | hasFrameworkContext: !!enhancedContext.frameworkContext,
118 | sessionId: enhancedContext.sessionId
119 | });
120 |
121 | return enhancedContext;
122 | } catch (error) {
123 | logger.error('❌ [ContextBuilder] Context building failed', {
124 | promptId,
125 | error: error instanceof Error ? error.message : String(error)
126 | });
127 |
128 | // Return minimal context on error
129 | return {
130 | promptId,
131 | promptArgs,
132 | executionMode: 'auto',
133 | sessionId: this.generateSessionId(),
134 | forceRestart: false,
135 | enableGates: true,
136 | contextData: {},
137 | metadata: { error: error instanceof Error ? error.message : String(error) },
138 | performance: { startTime: Date.now() }
139 | };
140 | }
141 | }
142 |
143 | /**
144 | * Build framework-specific execution context
145 | */
146 | private buildFrameworkContext(
147 | convertedPrompt: ConvertedPrompt,
148 | promptArgs: Record<string, any>,
149 | options: Record<string, any>
150 | ): FrameworkExecutionContext | undefined {
151 | try {
152 | if (!this.frameworkManager || !this.frameworkStateManager) {
153 | return undefined;
154 | }
155 |
156 | logger.debug('🎯 [ContextBuilder] Building framework context');
157 |
158 | const activeFramework = this.frameworkStateManager.getActiveFramework();
159 | const frameworkId = options.frameworkId || activeFramework;
160 |
161 | if (!frameworkId) {
162 | logger.debug('No framework specified, skipping framework context');
163 | return undefined;
164 | }
165 |
166 | const frameworkContext = this.frameworkManager.generateExecutionContext(
167 | convertedPrompt,
168 | {
169 | promptType: options.executionType || 'prompt',
170 | complexity: 'medium',
171 | userPreference: frameworkId as any
172 | }
173 | );
174 |
175 | logger.debug('✅ [ContextBuilder] Framework context built', {
176 | frameworkId,
177 | hasSystemPrompt: !!frameworkContext.systemPrompt
178 | });
179 |
180 | return frameworkContext;
181 | } catch (error) {
182 | logger.warn('⚠️ [ContextBuilder] Framework context building failed', {
183 | error: error instanceof Error ? error.message : String(error)
184 | });
185 | return undefined;
186 | }
187 | }
188 |
189 | /**
190 | * Build execution metadata
191 | */
192 | private buildMetadata(
193 | convertedPrompt: ConvertedPrompt,
194 | options: Record<string, any>
195 | ): Record<string, any> {
196 | return {
197 | promptId: convertedPrompt.id,
198 | promptTitle: convertedPrompt.name,
199 | promptCategory: convertedPrompt.category,
200 | promptVersion: '1.0', // ConvertedPrompt doesn't have version property
201 | executionId: this.generateExecutionId(),
202 | timestamp: new Date().toISOString(),
203 | userAgent: options.userAgent,
204 | clientInfo: options.clientInfo,
205 | environment: process.env.NODE_ENV || 'development',
206 | nodeVersion: process.version,
207 | platform: process.platform
208 | };
209 | }
210 |
211 | /**
212 | * Generate unique session ID
213 | */
214 | private generateSessionId(): string {
215 | return `session_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
216 | }
217 |
218 | /**
219 | * Generate unique execution ID
220 | */
221 | private generateExecutionId(): string {
222 | return `exec_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
223 | }
224 |
225 | /**
226 | * Get current memory usage
227 | */
228 | private getMemoryUsage(): number {
229 | try {
230 | return process.memoryUsage().heapUsed;
231 | } catch (error) {
232 | logger.warn('⚠️ [ContextBuilder] Failed to get memory usage', {
233 | error: error instanceof Error ? error.message : String(error)
234 | });
235 | return 0;
236 | }
237 | }
238 |
239 | /**
240 | * Validate execution context
241 | */
242 | public validateContext(context: EnhancedExecutionContext): {
243 | isValid: boolean;
244 | errors: string[];
245 | warnings: string[];
246 | } {
247 | const errors: string[] = [];
248 | const warnings: string[] = [];
249 |
250 | try {
251 | // Required fields validation
252 | if (!context.promptId) {
253 | errors.push("Prompt ID is required");
254 | }
255 |
256 | if (!context.sessionId) {
257 | errors.push("Session ID is required");
258 | }
259 |
260 | if (!context.promptArgs) {
261 | warnings.push("No prompt arguments provided");
262 | }
263 |
264 | // Context data validation
265 | if (context.contextData && typeof context.contextData !== 'object') {
266 | errors.push("Context data must be an object");
267 | }
268 |
269 | // Performance data validation
270 | if (context.performance && !context.performance.startTime) {
271 | warnings.push("Performance tracking missing start time");
272 | }
273 |
274 | // Framework context validation
275 | if (context.frameworkContext) {
276 | if (!context.frameworkContext.selectedFramework) {
277 | warnings.push("Framework context missing selected framework");
278 | }
279 | }
280 |
281 | const isValid = errors.length === 0;
282 |
283 | logger.debug('🔍 [ContextBuilder] Context validation completed', {
284 | isValid,
285 | errorsCount: errors.length,
286 | warningsCount: warnings.length
287 | });
288 |
289 | return { isValid, errors, warnings };
290 | } catch (error) {
291 | logger.error('❌ [ContextBuilder] Context validation failed', {
292 | error: error instanceof Error ? error.message : String(error)
293 | });
294 |
295 | return {
296 | isValid: false,
297 | errors: [`Validation error: ${error instanceof Error ? error.message : String(error)}`],
298 | warnings
299 | };
300 | }
301 | }
302 |
303 | /**
304 | * Clone context for reuse
305 | */
306 | public cloneContext(
307 | context: EnhancedExecutionContext,
308 | overrides: Partial<EnhancedExecutionContext> = {}
309 | ): EnhancedExecutionContext {
310 | try {
311 | const clonedContext: EnhancedExecutionContext = {
312 | ...context,
313 | ...overrides,
314 | promptArgs: { ...context.promptArgs, ...(overrides.promptArgs || {}) },
315 | contextData: { ...context.contextData, ...(overrides.contextData || {}) },
316 | metadata: { ...context.metadata, ...(overrides.metadata || {}) },
317 | performance: {
318 | startTime: context.performance?.startTime || Date.now(),
319 | memoryUsage: context.performance?.memoryUsage,
320 | ...(overrides.performance || {})
321 | }
322 | };
323 |
324 | // Update execution tracking
325 | if (clonedContext.metadata) {
326 | clonedContext.metadata.clonedFrom = context.metadata?.executionId;
327 | clonedContext.metadata.executionId = this.generateExecutionId();
328 | }
329 |
330 | logger.debug('🔄 [ContextBuilder] Context cloned successfully', {
331 | originalId: context.metadata?.executionId,
332 | clonedId: clonedContext.metadata?.executionId
333 | });
334 |
335 | return clonedContext;
336 | } catch (error) {
337 | logger.error('❌ [ContextBuilder] Context cloning failed', {
338 | error: error instanceof Error ? error.message : String(error)
339 | });
340 | throw error;
341 | }
342 | }
343 | }
```
--------------------------------------------------------------------------------
/server/config/tool-descriptions.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "version": "1.1.0",
3 | "lastUpdated": "2025-01-14T00:00:00Z",
4 | "tools": {
5 | "prompt_engine": {
6 | "description": "\ud83d\ude80 PROMPT ENGINE: Executes prompts with optional quality validation.\n\n\ud83d\udccb QUALITY GATE SYSTEM:\nQuality gates validate output before returning results. Use 'quality_gates' to apply validation rules, or 'custom_checks' for ad-hoc criteria.\n\n**Discover available gates**: Use `system_control({ action: 'gates', operation: 'list' })` to see all configured gates.\n\nGate modes:\n\u2022 enforce (default): Validates output, retries on failure with improvement hints (max 2 retries)\n\u2022 advise: Provides quality guidance without blocking\n\u2022 report: Validates and includes pass/fail status in response\n\nExample usage:\n{\n \"command\": \">>code_review code='...'\",\n \"quality_gates\": [\"gate-name-1\", \"gate-name-2\"],\n \"gate_mode\": \"enforce\"\n}",
7 | "shortDescription": "\ud83d\udd25 DYNAMICALLY UPDATED: Process prompt templates and return executable instructions",
8 | "category": "execution",
9 | "parameters": {
10 | "command": "Prompt name and arguments to process. WARNING: Will return instructions for YOU to execute, not just information. SIMPLE: >>prompt_name arguments (case-insensitive, hyphens converted to underscores). MULTI-LINE / RICH FORMATTING: {\"command\": \">>prompt_name\", \"args\": {\"content\": \"...\", \"execution_mode\": \"template\"}} keeps payload intact. ADVANCED: JSON with execution options",
11 | "execution_mode": "Override intelligent auto-detection (default: auto)",
12 | "gate_validation": "Quality gate validation (MANDATORY for chains, auto-detected by default, see metadata sections for gate details)",
13 | "quality_gates": {
14 | "type": "array",
15 | "description": "Array of quality gate names to apply. Discover available gates using system_control with action='gates', operation='list'. Gates validate output quality and provide improvement guidance."
16 | },
17 | "custom_checks": {
18 | "type": "array",
19 | "description": "Array of custom quality checks (each with 'name' and 'description'). Creates simple validation gates based on your criteria. Example: [{name: 'production-ready', description: 'Include error handling'}]"
20 | },
21 | "gate_mode": {
22 | "type": "string",
23 | "enum": [
24 | "enforce",
25 | "advise",
26 | "report"
27 | ],
28 | "description": "How to apply quality gates: 'enforce' (block on failure, retry with hints), 'advise' (guidance only), 'report' (validate and report). Default: 'enforce' when quality_gates specified."
29 | },
30 | "step_confirmation": "Require confirmation between chain steps",
31 | "llm_driven_execution": "Enable LLM-driven chain step coordination (requires semantic LLM integration)",
32 | "force_restart": "Force restart chain from beginning, clearing all existing state",
33 | "session_id": "Specific session ID to use or resume",
34 | "chain_uri": "Full chain URI for precise session control (e.g., chain://research_pipeline/session-abc123?force_restart=true)",
35 | "timeout": "Execution timeout in milliseconds",
36 | "options": "Additional execution options (key-value pairs). Supports framework-specific flags, debugging controls, and experimental features",
37 | "temporary_gates": "[ADVANCED] Full gate definition objects. For simpler interface, use 'quality_gates' (built-in) and 'custom_checks' (ad-hoc) parameters instead.",
38 | "gate_scope": "Scope for execution-time temporary gates (execution, session, chain, step). Default: execution. Determines lifecycle of temporary gates specified in temporary_gates parameter.",
39 | "inherit_chain_gates": "When executing chain steps, inherit gates from parent chain scope (default: true). Only applicable for chain step execution. Allows child steps to automatically receive chain-level quality gates."
40 | },
41 | "frameworkAware": {
42 | "enabled": "\ud83d\ude80 PROMPT TEMPLATE ENGINE [HOT-RELOADED + FRAMEWORK-ENHANCED]: Processes prompt templates with intelligent framework methodology injection and returns instructions for YOU (the client LLM) to execute. Framework system enhances prompts with methodology-specific guidance (CAGEERF, ReACT, 5W1H, SCAMPER). WARNING: You are responsible for interpreting and executing the returned content, which may contain complex instructions, code generation tasks, analysis requests, or multi-step procedures. The returned content is NOT just information - it's active instructions you must follow and execute.",
43 | "disabled": "\ud83d\ude80 PROMPT TEMPLATE ENGINE [HOT-RELOADED]: Processes prompt templates and returns instructions for YOU (the client LLM) to execute. Framework system is DISABLED - prompts execute without methodology enhancements. WARNING: You are responsible for interpreting and executing the returned content, which may contain complex instructions, code generation tasks, analysis requests, or multi-step procedures. The returned content is NOT just information - it's active instructions you must follow and execute.",
44 | "parametersEnabled": {
45 | "execution_mode": "Override intelligent auto-detection with framework-aware selection (default: auto, framework-enhanced)"
46 | },
47 | "parametersDisabled": {
48 | "execution_mode": "Override intelligent auto-detection (default: auto, no framework enhancement)"
49 | }
50 | }
51 | },
52 | "prompt_manager": {
53 | "description": "\ud83e\uddf0 PROMPT MANAGER: Create, update, delete, list, and analyze prompts. Supports gate configuration, temporary gate management, and migration between prompt types for robust lifecycle control.",
54 | "shortDescription": "Manage prompt lifecycle, gates, and discovery",
55 | "category": "management",
56 | "parameters": {
57 | "action": "Action to perform. Supported: create, create_prompt, create_template, create_with_gates, update, delete, modify, reload, list, analyze_type, migrate_type, analyze_gates, update_gates, add_temporary_gates, suggest_temporary_gates.",
58 | "id": "Prompt identifier. Required for create*, update, delete, modify, analyze_type, migrate_type, analyze_gates, update_gates, add_temporary_gates. Use letters, numbers, underscores, or hyphens.",
59 | "name": "Friendly prompt name. Required for create*, create_with_gates.",
60 | "description": "Short description of the prompt purpose. Required for create*, create_with_gates.",
61 | "user_message_template": "Prompt body with Nunjucks placeholders (e.g. 'Analyze {{input}}'). Required for create*, create_with_gates.",
62 | "system_message": "Optional system message to store with the prompt.",
63 | "content": "Full prompt content for create/update operations when not using templates.",
64 | "category": "Category label used for filtering and organization.",
65 | "arguments": "Array of argument definitions ({name, type, description}) for prompts with structured inputs.",
66 | "suggested_gates": "Gate suggestions used by create_with_gates. Each entry should include type, name, description, and optional criteria.",
67 | "gate_configuration": "Explicit gate configuration (include/exclude lists, temporary gates, framework_gates flag).",
68 | "temporary_gates": "Temporary gate definitions used by add_temporary_gates (include name, type, scope, description, guidance, pass_criteria).",
69 | "gate_scope": "Scope for temporary gates (execution, session, chain, step).",
70 | "inherit_chain_gates": "When true, inherit gates from the parent chain (default true for add_temporary_gates).",
71 | "search_query": "Search expression for list (e.g. 'category:code type:chain').",
72 | "force": "Bypass confirmation prompts for supported actions."
73 | },
74 | "frameworkAware": {
75 | "enabled": "\ud83e\uddf0 PROMPT MANAGER [FRAMEWORK-ENABLED]: Same functionality with framework-aware metadata exposed. Use when methodology switching is active.",
76 | "disabled": "\ud83e\uddf0 PROMPT MANAGER [FRAMEWORK-DISABLED]: Operates without applying methodology metadata or guidance.",
77 | "parametersEnabled": {
78 | "action": "Same as base mode; framework context is available for downstream processing"
79 | },
80 | "parametersDisabled": {
81 | "action": "Same as base mode"
82 | }
83 | }
84 | },
85 | "system_control": {
86 | "description": "\u2699\ufe0f SYSTEM CONTROL: Framework management, gate discovery, analytics, and system operations.\n\n**Discover quality gates**: Use `action='gates', operation='list'` to see all available validation gates.\n**Discover frameworks**: Use `action='framework', operation='list'` to see available methodologies.",
87 | "shortDescription": "Manage framework state, metrics, and maintenance",
88 | "category": "system",
89 | "parameters": {
90 | "action": "Top-level command. Supported values: status, framework, gates, analytics, config, maintenance.",
91 | "operation": "Sub-command for the selected action (e.g. framework: switch|list|enable|disable, analytics: view|reset|history).",
92 | "framework": "Framework identifier when switching (CAGEERF, ReACT, 5W1H, SCAMPER).",
93 | "config_path": "Configuration path or key for config operations.",
94 | "config_value": "Value to write when performing config updates.",
95 | "reason": "Audit-friendly explanation for switches, config changes, or restarts.",
96 | "restart_reason": "Specific reason recorded for maintenance/restart operations.",
97 | "confirm": "Set true to acknowledge confirmation-required operations (e.g. reset, restore, restart).",
98 | "include_history": "Include historical entries (where supported).",
99 | "include_metrics": "Include detailed metrics output (where supported).",
100 | "show_details": "Request an expanded response for list/status style commands."
101 | },
102 | "frameworkAware": {
103 | "enabled": "\u2699\ufe0f SYSTEM CONTROL [FRAMEWORK-ENABLED]: Framework switching and gate orchestration available.",
104 | "disabled": "\u2699\ufe0f SYSTEM CONTROL [FRAMEWORK-DISABLED]: Limited to status, analytics, config, and maintenance.",
105 | "parametersEnabled": {
106 | "action": "Same as base mode; framework operations succeed"
107 | },
108 | "parametersDisabled": {
109 | "action": "Same as base mode; framework operations return informative errors"
110 | }
111 | }
112 | }
113 | }
114 | }
```
--------------------------------------------------------------------------------
/server/src/gates/gate-state-manager.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Gate System Manager - Runtime State Management
3 | *
4 | * Provides runtime enable/disable functionality for the gates system,
5 | * following the same pattern as FrameworkStateManager for consistency.
6 | */
7 |
8 | import { EventEmitter } from 'events';
9 | import path from 'path';
10 | import fs from 'fs/promises';
11 | import { Logger } from '../logging/index.js';
12 |
13 | /**
14 | * Gate system state interface
15 | */
16 | export interface GateSystemState {
17 | enabled: boolean;
18 | enabledAt: Date;
19 | enableReason: string;
20 | isHealthy: boolean;
21 | validationMetrics: {
22 | totalValidations: number;
23 | successfulValidations: number;
24 | averageValidationTime: number;
25 | lastValidationTime: Date | null;
26 | };
27 | }
28 |
29 | /**
30 | * Gate system health status
31 | */
32 | export interface GateSystemHealth {
33 | status: "healthy" | "degraded" | "disabled";
34 | enabled: boolean;
35 | totalValidations: number;
36 | successRate: number;
37 | averageValidationTime: number;
38 | lastValidationTime: Date | null;
39 | issues: string[];
40 | }
41 |
42 | /**
43 | * Gate system enable/disable request
44 | */
45 | export interface GateSystemToggleRequest {
46 | enabled: boolean;
47 | reason?: string;
48 | }
49 |
50 | /**
51 | * Gate system events
52 | */
53 | export interface GateSystemEvents {
54 | 'system-enabled': [reason: string];
55 | 'system-disabled': [reason: string];
56 | 'health-changed': [health: GateSystemHealth];
57 | 'validation-completed': [success: boolean, executionTime: number];
58 | }
59 |
60 | /**
61 | * Gate System Manager - Runtime state management
62 | */
63 | export class GateSystemManager extends EventEmitter {
64 | private currentState: GateSystemState;
65 | private logger: Logger;
66 | private stateFilePath: string;
67 | private healthCheckInterval?: NodeJS.Timeout;
68 |
69 | constructor(logger: Logger, stateDirectory?: string) {
70 | super();
71 | this.logger = logger;
72 |
73 | // Default state - gates enabled by default
74 | this.currentState = {
75 | enabled: true,
76 | enabledAt: new Date(),
77 | enableReason: 'System initialization (default enabled)',
78 | isHealthy: true,
79 | validationMetrics: {
80 | totalValidations: 0,
81 | successfulValidations: 0,
82 | averageValidationTime: 0,
83 | lastValidationTime: null
84 | }
85 | };
86 |
87 | // Set up state file path
88 | const baseDir = stateDirectory || path.join(process.cwd(), 'runtime-state');
89 | this.stateFilePath = path.join(baseDir, 'gate-system-state.json');
90 |
91 | this.logger.debug(`GateSystemManager initialized with state file: ${this.stateFilePath}`);
92 | }
93 |
94 | /**
95 | * Initialize the gate system manager
96 | */
97 | async initialize(): Promise<void> {
98 | try {
99 | // Load persisted state if available
100 | await this.loadStateFromFile();
101 |
102 | // Start health monitoring
103 | this.startHealthMonitoring();
104 |
105 | this.logger.info(`🚪 Gate System Manager initialized - System ${this.currentState.enabled ? 'enabled' : 'disabled'}`);
106 | } catch (error) {
107 | this.logger.error('Failed to initialize GateSystemManager:', error);
108 | throw error;
109 | }
110 | }
111 |
112 | /**
113 | * Load state from persistent storage
114 | */
115 | private async loadStateFromFile(): Promise<void> {
116 | try {
117 | // Ensure state directory exists
118 | await fs.mkdir(path.dirname(this.stateFilePath), { recursive: true });
119 |
120 | // Try to load existing state
121 | const stateData = await fs.readFile(this.stateFilePath, 'utf-8');
122 | const persistedState = JSON.parse(stateData);
123 |
124 | // Validate and restore state
125 | if (this.isValidPersistedState(persistedState)) {
126 | this.currentState.enabled = persistedState.enabled;
127 | this.currentState.enabledAt = new Date(persistedState.enabledAt);
128 | this.currentState.enableReason = persistedState.enableReason;
129 | this.currentState.validationMetrics = {
130 | ...this.currentState.validationMetrics,
131 | ...persistedState.validationMetrics,
132 | lastValidationTime: persistedState.validationMetrics.lastValidationTime
133 | ? new Date(persistedState.validationMetrics.lastValidationTime)
134 | : null
135 | };
136 |
137 | this.logger.info(`✅ Loaded persisted gate system state: ${persistedState.enabled ? 'enabled' : 'disabled'}`);
138 | } else {
139 | this.logger.warn('⚠️ Invalid persisted gate state format, using defaults');
140 | await this.saveStateToFile(); // Save valid defaults
141 | }
142 | } catch (error) {
143 | if ((error as any).code === 'ENOENT') {
144 | // No state file exists yet - use defaults and create initial state
145 | this.logger.info('📁 No existing gate system state found, using defaults');
146 | await this.saveStateToFile();
147 | } else {
148 | this.logger.error('Failed to load gate system state:', error);
149 | // Continue with defaults but don't fail initialization
150 | }
151 | }
152 | }
153 |
154 | /**
155 | * Save current state to persistent storage
156 | */
157 | private async saveStateToFile(): Promise<void> {
158 | try {
159 | const stateToSave = {
160 | enabled: this.currentState.enabled,
161 | enabledAt: this.currentState.enabledAt.toISOString(),
162 | enableReason: this.currentState.enableReason,
163 | validationMetrics: {
164 | ...this.currentState.validationMetrics,
165 | lastValidationTime: this.currentState.validationMetrics.lastValidationTime?.toISOString() || null
166 | },
167 | savedAt: new Date().toISOString()
168 | };
169 |
170 | await fs.writeFile(this.stateFilePath, JSON.stringify(stateToSave, null, 2));
171 | this.logger.debug('Gate system state saved to file');
172 | } catch (error) {
173 | this.logger.error('Failed to save gate system state:', error);
174 | // Don't throw - this shouldn't break the system
175 | }
176 | }
177 |
178 | /**
179 | * Validate persisted state structure
180 | */
181 | private isValidPersistedState(state: any): boolean {
182 | return (
183 | state &&
184 | typeof state.enabled === 'boolean' &&
185 | typeof state.enabledAt === 'string' &&
186 | typeof state.enableReason === 'string' &&
187 | state.validationMetrics &&
188 | typeof state.validationMetrics.totalValidations === 'number'
189 | );
190 | }
191 |
192 | /**
193 | * Check if gate system is enabled
194 | */
195 | isGateSystemEnabled(): boolean {
196 | return this.currentState.enabled;
197 | }
198 |
199 | /**
200 | * Enable the gate system
201 | */
202 | async enableGateSystem(reason: string = 'User request'): Promise<void> {
203 | if (this.currentState.enabled) {
204 | this.logger.debug('Gate system already enabled');
205 | return;
206 | }
207 |
208 | this.currentState.enabled = true;
209 | this.currentState.enabledAt = new Date();
210 | this.currentState.enableReason = reason;
211 | this.currentState.isHealthy = true;
212 |
213 | // Save state to file
214 | await this.saveStateToFile();
215 |
216 | // Emit events
217 | this.emit('system-enabled', reason);
218 | this.emit('health-changed', this.getSystemHealth());
219 |
220 | this.logger.info(`🟢 Gate System enabled: ${reason}`);
221 | }
222 |
223 | /**
224 | * Disable the gate system
225 | */
226 | async disableGateSystem(reason: string = 'User request'): Promise<void> {
227 | if (!this.currentState.enabled) {
228 | this.logger.debug('Gate system already disabled');
229 | return;
230 | }
231 |
232 | this.currentState.enabled = false;
233 | this.currentState.enableReason = `Disabled: ${reason}`;
234 |
235 | // Save state to file
236 | await this.saveStateToFile();
237 |
238 | // Emit events
239 | this.emit('system-disabled', reason);
240 | this.emit('health-changed', this.getSystemHealth());
241 |
242 | this.logger.info(`🔴 Gate System disabled: ${reason}`);
243 | }
244 |
245 | /**
246 | * Get current system health
247 | */
248 | getSystemHealth(): GateSystemHealth {
249 | const metrics = this.currentState.validationMetrics;
250 | const successRate = metrics.totalValidations > 0
251 | ? (metrics.successfulValidations / metrics.totalValidations) * 100
252 | : 100;
253 |
254 | let status: "healthy" | "degraded" | "disabled" = "healthy";
255 | const issues: string[] = [];
256 |
257 | if (!this.currentState.enabled) {
258 | status = "disabled";
259 | } else if (successRate < 80 && metrics.totalValidations > 10) {
260 | status = "degraded";
261 | issues.push("Low validation success rate");
262 | } else if (metrics.averageValidationTime > 1000) {
263 | status = "degraded";
264 | issues.push("High validation latency");
265 | }
266 |
267 | return {
268 | status,
269 | enabled: this.currentState.enabled,
270 | totalValidations: metrics.totalValidations,
271 | successRate: Math.round(successRate * 100) / 100,
272 | averageValidationTime: Math.round(metrics.averageValidationTime * 100) / 100,
273 | lastValidationTime: metrics.lastValidationTime,
274 | issues
275 | };
276 | }
277 |
278 | /**
279 | * Record a validation execution for metrics
280 | */
281 | recordValidation(success: boolean, executionTime: number): void {
282 | const metrics = this.currentState.validationMetrics;
283 |
284 | metrics.totalValidations++;
285 | if (success) {
286 | metrics.successfulValidations++;
287 | }
288 |
289 | // Update average execution time using running average
290 | metrics.averageValidationTime =
291 | (metrics.averageValidationTime * (metrics.totalValidations - 1) + executionTime) /
292 | metrics.totalValidations;
293 |
294 | metrics.lastValidationTime = new Date();
295 |
296 | // Save state periodically (every 10 validations)
297 | if (metrics.totalValidations % 10 === 0) {
298 | this.saveStateToFile().catch(error => {
299 | this.logger.error('Failed to save validation metrics:', error);
300 | });
301 | }
302 |
303 | // Emit event
304 | this.emit('validation-completed', success, executionTime);
305 |
306 | this.logger.debug(`Validation recorded: ${success ? 'success' : 'failure'} (${executionTime}ms)`);
307 | }
308 |
309 | /**
310 | * Get current state for inspection
311 | */
312 | getCurrentState(): GateSystemState {
313 | return { ...this.currentState };
314 | }
315 |
316 | /**
317 | * Start health monitoring
318 | */
319 | private startHealthMonitoring(): void {
320 | // Check system health every 30 seconds
321 | this.healthCheckInterval = setInterval(() => {
322 | const health = this.getSystemHealth();
323 |
324 | // Only emit health changes if status actually changed
325 | const previousStatus = this.currentState.isHealthy;
326 | const currentlyHealthy = health.status === 'healthy';
327 |
328 | if (previousStatus !== currentlyHealthy) {
329 | this.currentState.isHealthy = currentlyHealthy;
330 | this.emit('health-changed', health);
331 |
332 | if (!currentlyHealthy) {
333 | this.logger.warn(`🚨 Gate system health degraded: ${health.issues.join(', ')}`);
334 | }
335 | }
336 | }, 30000);
337 | }
338 |
339 | /**
340 | * Cleanup resources
341 | */
342 | async cleanup(): Promise<void> {
343 | if (this.healthCheckInterval) {
344 | clearInterval(this.healthCheckInterval);
345 | }
346 |
347 | // Final state save
348 | await this.saveStateToFile();
349 |
350 | this.logger.debug('GateSystemManager cleanup completed');
351 | }
352 | }
353 |
354 | /**
355 | * Create a gate system manager instance
356 | */
357 | export function createGateSystemManager(
358 | logger: Logger,
359 | stateDirectory?: string
360 | ): GateSystemManager {
361 | return new GateSystemManager(logger, stateDirectory);
362 | }
```
--------------------------------------------------------------------------------
/server/tests/scripts/integration-routing-system.js:
--------------------------------------------------------------------------------
```javascript
1 | #!/usr/bin/env node
2 | /**
3 | * Routing System Integration Tests
4 | * Tests for the intelligent command routing functionality added to the prompt engine
5 | */
6 |
7 | async function runRoutingSystemTests() {
8 | try {
9 | console.log('🧪 Running Routing System Integration tests...');
10 | console.log('📋 Testing intelligent command routing and built-in command support');
11 |
12 | // Import global resource tracker for process cleanup
13 | const { globalResourceTracker } = await import('../../dist/utils/global-resource-tracker.js');
14 |
15 | // Test the routing pattern detection directly (simulating the logic from prompt engine)
16 | function testRoutingPatterns() {
17 | const patterns = [
18 | { command: '>>listprompts', expected: 'prompt_manager', description: 'listprompts command routing' },
19 | { command: 'listprompts', expected: 'prompt_manager', description: 'listprompts without >> prefix' },
20 | { command: '>>listprompts category:analysis', expected: 'prompt_manager', description: 'listprompts with filter' },
21 | { command: '>>help', expected: 'system_control', description: 'help command routing' },
22 | { command: 'help', expected: 'system_control', description: 'help without >> prefix' },
23 | { command: '>>status', expected: 'system_control', description: 'status command routing' },
24 | { command: '>>analytics', expected: 'system_control', description: 'analytics command routing' },
25 | { command: '>>framework switch CAGEERF', expected: 'system_control', description: 'framework switch routing' },
26 | { command: '>>some_prompt_name', expected: null, description: 'regular prompt should not route' },
27 | { command: '/listprompts', expected: 'prompt_manager', description: 'listprompts with / prefix' },
28 | { command: '/help', expected: 'system_control', description: 'help with / prefix' },
29 | ];
30 |
31 | console.log('🔍 Test 1: Routing Pattern Detection');
32 | let passedPatterns = 0;
33 |
34 | for (const test of patterns) {
35 | const trimmedCommand = test.command.trim();
36 | let matchedTool = null;
37 |
38 | // Built-in commands that route to prompt_manager
39 | if (/^(>>|\/)?listprompts?(\s.*)?$/i.test(trimmedCommand)) {
40 | matchedTool = 'prompt_manager';
41 | }
42 | // Help and status commands that route to system_control
43 | else if (/^(>>|\/)?help$/i.test(trimmedCommand)) {
44 | matchedTool = 'system_control';
45 | }
46 | else if (/^(>>|\/)?status$/i.test(trimmedCommand)) {
47 | matchedTool = 'system_control';
48 | }
49 | // Framework switch commands
50 | else if (trimmedCommand.match(/^(>>|\/)?framework\s+(switch|change)\s+(.+)$/i)) {
51 | matchedTool = 'system_control';
52 | }
53 | // Analytics/metrics commands
54 | else if (/^(>>|\/)?analytics?$/i.test(trimmedCommand)) {
55 | matchedTool = 'system_control';
56 | }
57 |
58 | const result = matchedTool === test.expected ? '✅' : '❌';
59 | const status = matchedTool === test.expected ? 'PASSED' : 'FAILED';
60 | console.log(`${result} ${test.description}: ${status}`);
61 |
62 | if (matchedTool === test.expected) {
63 | passedPatterns++;
64 | } else {
65 | console.log(` Expected: ${test.expected || 'none'}, Got: ${matchedTool || 'none'}`);
66 | }
67 | }
68 |
69 | return passedPatterns === patterns.length;
70 | }
71 |
72 | // Test parameter translation logic
73 | function testParameterTranslation() {
74 | console.log('🔍 Test 2: Parameter Translation');
75 | const testCases = [
76 | {
77 | command: '>>listprompts',
78 | expected: { action: 'list' },
79 | description: 'listprompts basic translation'
80 | },
81 | {
82 | command: '>>listprompts category:analysis',
83 | expected: { action: 'list', search_query: 'category:analysis' },
84 | description: 'listprompts with filter translation'
85 | },
86 | {
87 | command: '>>help',
88 | expected: { action: 'status', show_details: true },
89 | description: 'help command translation'
90 | },
91 | {
92 | command: '>>status',
93 | expected: { action: 'status' },
94 | description: 'status command translation'
95 | }
96 | ];
97 |
98 | let passedTranslations = 0;
99 |
100 | for (const test of testCases) {
101 | const trimmedCommand = test.command.trim();
102 | let translatedParams = null;
103 |
104 | // Simulate the parameter translation logic
105 | if (/^(>>|\/)?listprompts?(\s.*)?$/i.test(trimmedCommand)) {
106 | const args = trimmedCommand.replace(/^(>>|\/)?listprompts?\s*/i, '').trim();
107 | translatedParams = {
108 | action: 'list',
109 | ...(args && { search_query: args })
110 | };
111 | } else if (/^(>>|\/)?help$/i.test(trimmedCommand)) {
112 | translatedParams = {
113 | action: 'status',
114 | show_details: true
115 | };
116 | } else if (/^(>>|\/)?status$/i.test(trimmedCommand)) {
117 | translatedParams = {
118 | action: 'status'
119 | };
120 | }
121 |
122 | // Simple comparison for testing
123 | const paramsMatch = JSON.stringify(translatedParams) === JSON.stringify(test.expected);
124 | const result = paramsMatch ? '✅' : '❌';
125 | const status = paramsMatch ? 'PASSED' : 'FAILED';
126 | console.log(`${result} ${test.description}: ${status}`);
127 |
128 | if (paramsMatch) {
129 | passedTranslations++;
130 | } else {
131 | console.log(` Expected: ${JSON.stringify(test.expected)}`);
132 | console.log(` Got: ${JSON.stringify(translatedParams)}`);
133 | }
134 | }
135 |
136 | return passedTranslations === testCases.length;
137 | }
138 |
139 | // Test built-in command recognition in parser
140 | function testBuiltinCommandRecognition() {
141 | console.log('🔍 Test 3: Built-in Command Recognition');
142 |
143 | const builtinCommands = [
144 | 'listprompts', 'listprompt', 'list_prompts',
145 | 'help', 'commands',
146 | 'status', 'health',
147 | 'analytics', 'metrics'
148 | ];
149 |
150 | // Simulate the isBuiltinCommand logic
151 | function isBuiltinCommand(promptId) {
152 | return builtinCommands.includes(promptId.toLowerCase());
153 | }
154 |
155 | let passedRecognition = 0;
156 | const testCommands = [
157 | { command: 'listprompts', shouldRecognize: true },
158 | { command: 'help', shouldRecognize: true },
159 | { command: 'status', shouldRecognize: true },
160 | { command: 'analytics', shouldRecognize: true },
161 | { command: 'some_regular_prompt', shouldRecognize: false },
162 | { command: 'LISTPROMPTS', shouldRecognize: true }, // Case insensitive
163 | { command: 'unknown_command', shouldRecognize: false }
164 | ];
165 |
166 | for (const test of testCommands) {
167 | const recognized = isBuiltinCommand(test.command);
168 | const result = recognized === test.shouldRecognize ? '✅' : '❌';
169 | const status = recognized === test.shouldRecognize ? 'PASSED' : 'FAILED';
170 | console.log(`${result} Command '${test.command}' recognition: ${status}`);
171 |
172 | if (recognized === test.shouldRecognize) {
173 | passedRecognition++;
174 | }
175 | }
176 |
177 | return passedRecognition === testCommands.length;
178 | }
179 |
180 | // Test error message enhancements
181 | function testErrorMessageEnhancements() {
182 | console.log('🔍 Test 4: Enhanced Error Messages');
183 |
184 | function getBuiltinCommandHint(promptId) {
185 | const lower = promptId.toLowerCase();
186 |
187 | if (lower.includes('list') && lower.includes('prompt')) {
188 | return '\n\nDid you mean >>listprompts?';
189 | }
190 | if (lower === 'commands' || lower === 'help') {
191 | return '\n\nTry >>help for available commands.';
192 | }
193 | if (lower === 'stat' || lower === 'status') {
194 | return '\n\nTry >>status for system status.';
195 | }
196 |
197 | return '';
198 | }
199 |
200 | const testCases = [
201 | { command: 'listprompt', expectedHint: '\n\nDid you mean >>listprompts?' },
202 | { command: 'commands', expectedHint: '\n\nTry >>help for available commands.' },
203 | { command: 'stat', expectedHint: '\n\nTry >>status for system status.' },
204 | { command: 'unknown', expectedHint: '' }
205 | ];
206 |
207 | let passedHints = 0;
208 |
209 | for (const test of testCases) {
210 | const hint = getBuiltinCommandHint(test.command);
211 | const result = hint === test.expectedHint ? '✅' : '❌';
212 | const status = hint === test.expectedHint ? 'PASSED' : 'FAILED';
213 | console.log(`${result} Error hint for '${test.command}': ${status}`);
214 |
215 | if (hint === test.expectedHint) {
216 | passedHints++;
217 | }
218 | }
219 |
220 | return passedHints === testCases.length;
221 | }
222 |
223 | // Run all tests
224 | const results = [
225 | testRoutingPatterns(),
226 | testParameterTranslation(),
227 | testBuiltinCommandRecognition(),
228 | testErrorMessageEnhancements()
229 | ];
230 |
231 | const passedTests = results.filter(r => r).length;
232 | const totalTests = results.length;
233 |
234 | console.log('\n📊 Routing System Integration Tests Summary:');
235 | console.log(` ✅ Passed: ${passedTests}/${totalTests} test categories`);
236 | console.log(` 📊 Success Rate: ${((passedTests/totalTests)*100).toFixed(1)}%`);
237 |
238 | // Check for remaining resources before exit
239 | console.log('\n🔍 Checking for remaining global resources...');
240 | globalResourceTracker.logDiagnostics();
241 | const cleared = globalResourceTracker.emergencyCleanup();
242 | if (cleared > 0) {
243 | console.log(`💀 Emergency cleanup cleared ${cleared} additional resources`);
244 | }
245 |
246 | if (passedTests === totalTests) {
247 | console.log('🎉 All Routing System Integration tests passed!');
248 | // Emergency process exit to prevent hanging due to global Node.js resources
249 | console.log('💀 Forcing process exit to prevent hanging from global timers...');
250 | setTimeout(() => process.exit(0), 100); // Small delay to ensure log output
251 | return true;
252 | } else {
253 | console.error('❌ Some Routing System Integration tests failed');
254 | // Emergency process exit for failure case as well
255 | console.log('💀 Forcing process exit to prevent hanging from global timers...');
256 | setTimeout(() => process.exit(1), 100); // Small delay to ensure log output
257 | return false;
258 | }
259 |
260 | } catch (error) {
261 | console.error('❌ Routing System Integration tests failed with error:', error.message);
262 | if (error.stack) {
263 | console.error('Stack trace:', error.stack);
264 | }
265 | // Emergency process exit for error case as well
266 | console.log('💀 Forcing process exit due to test error to prevent hanging from global timers...');
267 | setTimeout(() => process.exit(1), 100); // Small delay to ensure log output
268 | return false;
269 | }
270 | }
271 |
272 | // Run the tests
273 | if (import.meta.url === `file://${process.argv[1]}`) {
274 | runRoutingSystemTests().catch(error => {
275 | console.error('❌ Test execution failed:', error);
276 | process.exit(1);
277 | });
278 | }
279 |
280 | export { runRoutingSystemTests };
```
--------------------------------------------------------------------------------
/server/src/semantic/integrations/llm-clients.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * LLM Integration Clients for Semantic Analysis
3 | *
4 | * Provides concrete implementations for different LLM providers
5 | * to enable intelligent semantic analysis when configured.
6 | */
7 |
8 | import { Logger } from "../../logging/index.js";
9 | import { LLMIntegrationConfig, LLMProvider } from "../../types/index.js";
10 | import { LLMClient } from "../configurable-semantic-analyzer.js";
11 |
12 | /**
13 | * Base LLM client with common functionality
14 | */
15 | abstract class BaseLLMClient implements LLMClient {
16 | protected logger: Logger;
17 | protected config: LLMIntegrationConfig;
18 |
19 | constructor(logger: Logger, config: LLMIntegrationConfig) {
20 | this.logger = logger;
21 | this.config = config;
22 | }
23 |
24 | abstract classify(request: {
25 | text: string;
26 | task: string;
27 | categories: string[];
28 | methodologies: string[];
29 | }): Promise<{
30 | executionType: string;
31 | confidence: number;
32 | reasoning: string[];
33 | recommendedFramework?: string;
34 | complexity: string;
35 | }>;
36 |
37 | /**
38 | * Common prompt construction for semantic analysis
39 | */
40 | protected buildAnalysisPrompt(request: {
41 | text: string;
42 | task: string;
43 | categories: string[];
44 | methodologies: string[];
45 | }): string {
46 | return `${request.task}
47 |
48 | Prompt Text:
49 | """
50 | ${request.text}
51 | """
52 |
53 | Available Execution Types: ${request.categories.join(', ')}
54 | Available Methodologies: ${request.methodologies.join(', ')}
55 |
56 | Please analyze this prompt and return:
57 | 1. executionType: One of [${request.categories.join(', ')}]
58 | 2. confidence: Number between 0 and 1
59 | 3. reasoning: Array of strings explaining your analysis
60 | 4. recommendedFramework: One of [${request.methodologies.join(', ')}] or "none"
61 | 5. complexity: One of ["low", "medium", "high"]
62 |
63 | Respond in JSON format only.`;
64 | }
65 |
66 | /**
67 | * Parse LLM response and validate format
68 | */
69 | protected parseResponse(response: string): {
70 | executionType: string;
71 | confidence: number;
72 | reasoning: string[];
73 | recommendedFramework?: string;
74 | complexity: string;
75 | } {
76 | try {
77 | const parsed = JSON.parse(response);
78 |
79 | return {
80 | executionType: parsed.executionType || "template",
81 | confidence: Math.max(0.1, Math.min(1.0, parsed.confidence || 0.5)),
82 | reasoning: Array.isArray(parsed.reasoning) ? parsed.reasoning : ["LLM analysis performed"],
83 | recommendedFramework: parsed.recommendedFramework === "none" ? undefined : parsed.recommendedFramework,
84 | complexity: ["low", "medium", "high"].includes(parsed.complexity) ? parsed.complexity : "medium"
85 | };
86 | } catch (error) {
87 | this.logger.warn("Failed to parse LLM response, using defaults:", error);
88 | return {
89 | executionType: "template",
90 | confidence: 0.3,
91 | reasoning: ["Failed to parse LLM response"],
92 | complexity: "medium"
93 | };
94 | }
95 | }
96 | }
97 |
98 | /**
99 | * OpenAI client implementation
100 | */
101 | export class OpenAIClient extends BaseLLMClient {
102 | async classify(request: {
103 | text: string;
104 | task: string;
105 | categories: string[];
106 | methodologies: string[];
107 | }): Promise<{
108 | executionType: string;
109 | confidence: number;
110 | reasoning: string[];
111 | recommendedFramework?: string;
112 | complexity: string;
113 | }> {
114 | if (!this.config.apiKey) {
115 | throw new Error("OpenAI API key not configured");
116 | }
117 |
118 | const prompt = this.buildAnalysisPrompt(request);
119 |
120 | try {
121 | const response = await fetch(this.config.endpoint || "https://api.openai.com/v1/chat/completions", {
122 | method: "POST",
123 | headers: {
124 | "Authorization": `Bearer ${this.config.apiKey}`,
125 | "Content-Type": "application/json"
126 | },
127 | body: JSON.stringify({
128 | model: this.config.model,
129 | messages: [
130 | {
131 | role: "system",
132 | content: "You are an expert at analyzing prompts for execution strategy and framework requirements. Always respond with valid JSON."
133 | },
134 | {
135 | role: "user",
136 | content: prompt
137 | }
138 | ],
139 | max_tokens: this.config.maxTokens,
140 | temperature: this.config.temperature
141 | })
142 | });
143 |
144 | if (!response.ok) {
145 | throw new Error(`OpenAI API error: ${response.status} ${response.statusText}`);
146 | }
147 |
148 | const data = await response.json() as any;
149 | const content = data.choices?.[0]?.message?.content;
150 |
151 | if (!content) {
152 | throw new Error("No content in OpenAI response");
153 | }
154 |
155 | this.logger.debug("OpenAI analysis completed successfully");
156 | return this.parseResponse(content);
157 |
158 | } catch (error) {
159 | this.logger.error("OpenAI API call failed:", error);
160 | throw error;
161 | }
162 | }
163 | }
164 |
165 | /**
166 | * Anthropic client implementation
167 | */
168 | export class AnthropicClient extends BaseLLMClient {
169 | async classify(request: {
170 | text: string;
171 | task: string;
172 | categories: string[];
173 | methodologies: string[];
174 | }): Promise<{
175 | executionType: string;
176 | confidence: number;
177 | reasoning: string[];
178 | recommendedFramework?: string;
179 | complexity: string;
180 | }> {
181 | if (!this.config.apiKey) {
182 | throw new Error("Anthropic API key not configured");
183 | }
184 |
185 | const prompt = this.buildAnalysisPrompt(request);
186 |
187 | try {
188 | const response = await fetch(this.config.endpoint || "https://api.anthropic.com/v1/messages", {
189 | method: "POST",
190 | headers: {
191 | "Authorization": `Bearer ${this.config.apiKey}`,
192 | "Content-Type": "application/json",
193 | "anthropic-version": "2023-06-01"
194 | },
195 | body: JSON.stringify({
196 | model: this.config.model || "claude-3-haiku-20240307",
197 | max_tokens: this.config.maxTokens,
198 | temperature: this.config.temperature,
199 | messages: [
200 | {
201 | role: "user",
202 | content: prompt
203 | }
204 | ]
205 | })
206 | });
207 |
208 | if (!response.ok) {
209 | throw new Error(`Anthropic API error: ${response.status} ${response.statusText}`);
210 | }
211 |
212 | const data = await response.json() as any;
213 | const content = data.content?.[0]?.text;
214 |
215 | if (!content) {
216 | throw new Error("No content in Anthropic response");
217 | }
218 |
219 | this.logger.debug("Anthropic analysis completed successfully");
220 | return this.parseResponse(content);
221 |
222 | } catch (error) {
223 | this.logger.error("Anthropic API call failed:", error);
224 | throw error;
225 | }
226 | }
227 | }
228 |
229 | /**
230 | * Custom endpoint client implementation
231 | */
232 | export class CustomClient extends BaseLLMClient {
233 | async classify(request: {
234 | text: string;
235 | task: string;
236 | categories: string[];
237 | methodologies: string[];
238 | }): Promise<{
239 | executionType: string;
240 | confidence: number;
241 | reasoning: string[];
242 | recommendedFramework?: string;
243 | complexity: string;
244 | }> {
245 | if (!this.config.endpoint) {
246 | throw new Error("Custom endpoint not configured");
247 | }
248 |
249 | const prompt = this.buildAnalysisPrompt(request);
250 |
251 | try {
252 | const headers: Record<string, string> = {
253 | "Content-Type": "application/json"
254 | };
255 |
256 | if (this.config.apiKey) {
257 | headers["Authorization"] = `Bearer ${this.config.apiKey}`;
258 | }
259 |
260 | const response = await fetch(this.config.endpoint, {
261 | method: "POST",
262 | headers,
263 | body: JSON.stringify({
264 | model: this.config.model,
265 | prompt: prompt,
266 | max_tokens: this.config.maxTokens,
267 | temperature: this.config.temperature
268 | })
269 | });
270 |
271 | if (!response.ok) {
272 | throw new Error(`Custom endpoint error: ${response.status} ${response.statusText}`);
273 | }
274 |
275 | const data = await response.json() as any;
276 | // Assume the custom endpoint returns the analysis directly
277 | const content = data.response || data.content || data.text;
278 |
279 | if (!content) {
280 | throw new Error("No content in custom endpoint response");
281 | }
282 |
283 | this.logger.debug("Custom endpoint analysis completed successfully");
284 | return this.parseResponse(content);
285 |
286 | } catch (error) {
287 | this.logger.error("Custom endpoint call failed:", error);
288 | throw error;
289 | }
290 | }
291 | }
292 |
293 | /**
294 | * Detect LLM provider from endpoint URL
295 | */
296 | function detectProviderFromEndpoint(endpoint: string | null): LLMProvider {
297 | if (!endpoint) {
298 | throw new Error("Endpoint URL is required for provider auto-detection");
299 | }
300 |
301 | const url = endpoint.toLowerCase();
302 |
303 | if (url.includes("api.openai.com")) {
304 | return "openai";
305 | } else if (url.includes("api.anthropic.com")) {
306 | return "anthropic";
307 | } else {
308 | return "custom";
309 | }
310 | }
311 |
312 | /**
313 | * LLM client factory
314 | */
315 | export class LLMClientFactory {
316 | static create(logger: Logger, config: LLMIntegrationConfig): LLMClient {
317 | try {
318 | const provider = detectProviderFromEndpoint(config.endpoint);
319 |
320 | switch (provider) {
321 | case "openai":
322 | return new OpenAIClient(logger, config);
323 | case "anthropic":
324 | return new AnthropicClient(logger, config);
325 | case "custom":
326 | return new CustomClient(logger, config);
327 | default:
328 | throw new Error(`Unsupported LLM provider: ${provider}`);
329 | }
330 | } catch (error) {
331 | throw new Error(
332 | `Failed to create LLM client: ${error instanceof Error ? error.message : 'Unknown error'}. ` +
333 | `Please ensure the endpoint URL is valid and follows the format: ` +
334 | `"https://api.openai.com/v1/chat/completions" for OpenAI, ` +
335 | `"https://api.anthropic.com/v1/messages" for Anthropic, ` +
336 | `or a custom endpoint URL for other providers.`
337 | );
338 | }
339 | }
340 |
341 | /**
342 | * Test LLM client configuration
343 | */
344 | static async testClient(logger: Logger, config: LLMIntegrationConfig): Promise<boolean> {
345 | try {
346 | // Auto-detect provider before testing
347 | const provider = detectProviderFromEndpoint(config.endpoint);
348 | logger.debug(`Auto-detected LLM provider: ${provider} from endpoint: ${config.endpoint}`);
349 |
350 | const client = LLMClientFactory.create(logger, config);
351 |
352 | const testResult = await client.classify({
353 | text: "Analyze this simple test prompt with two arguments: {{input}} and {{context}}",
354 | task: "Test classification",
355 | categories: ["prompt", "template"],
356 | methodologies: ["CAGEERF", "none"]
357 | });
358 |
359 | // Basic validation that we got a valid response
360 | return Boolean(testResult.executionType &&
361 | testResult.confidence > 0 &&
362 | testResult.reasoning.length > 0);
363 |
364 | } catch (error) {
365 | logger.error("LLM client test failed:", error);
366 | return false;
367 | }
368 | }
369 | }
370 |
371 | /**
372 | * Environment variable configuration helper
373 | * Provider is auto-detected from endpoint URL
374 | */
375 | export function loadLLMConfigFromEnv(): Partial<LLMIntegrationConfig> {
376 | return {
377 | enabled: process.env.MCP_LLM_ENABLED === "true",
378 | apiKey: process.env.MCP_LLM_API_KEY || null,
379 | endpoint: process.env.MCP_LLM_ENDPOINT || null,
380 | model: process.env.MCP_LLM_MODEL || "gpt-4",
381 | maxTokens: parseInt(process.env.MCP_LLM_MAX_TOKENS || "1000"),
382 | temperature: parseFloat(process.env.MCP_LLM_TEMPERATURE || "0.1")
383 | };
384 | }
```
--------------------------------------------------------------------------------
/docs/chain-modification-examples.md:
--------------------------------------------------------------------------------
```markdown
1 | # Chain Modification Workflow Examples
2 |
3 | This document provides practical examples of the **correct way** to modify chains using the MCP tools, based on real scenarios.
4 |
5 | ## Example 1: Adding Vault Search to Notes Chain
6 |
7 | ### The Request
8 | > "Currently our note does not actually pull from relevant related notes in our vault, it just makes some up. Find the relevant step in our prompt chain, and refine it so it does look for, and valuable relevant notes in our vault"
9 |
10 | ### ❌ Wrong Approach (from logFail.txt)
11 | The agent incorrectly tried to:
12 | 1. Use `Update()` to modify chain.json files directly
13 | 2. Use `Write()` to create new step files
14 | 3. Bypass the MCP tool system entirely
15 |
16 | ### ✅ Correct Approach
17 |
18 | #### Step 1: Analyze Current Chain
19 | ```bash
20 | # List all notes-related prompts
21 | prompt_manager(action: "list", filter: "notes")
22 |
23 | # Get details about the notes chain
24 | prompt_manager(action: "list", filter: "type:chain notes", verbose: true)
25 | ```
26 |
27 | #### Step 2: Check for Vault-Related Components
28 | ```bash
29 | # Search for existing vault functionality
30 | prompt_manager(action: "list", filter: "vault")
31 |
32 | # Search for related notes functionality
33 | prompt_manager(action: "list", filter: "related notes")
34 | ```
35 |
36 | #### Step 3: Create Missing Components (if needed)
37 | ```bash
38 | # If vault_related_notes_finder doesn't exist, create it
39 | prompt_manager(action: "create",
40 | id: "vault_related_notes_finder",
41 | name: "Vault Related Notes Finder",
42 | category: "content_processing",
43 | description: "Searches vault for actual related notes using content analysis",
44 | system_message: "You are an expert at finding related notes in a knowledge vault. Search for notes that are thematically and conceptually related to the given content.",
45 | user_message_template: "Search in vault path: {{vault_path}}\n\nFind notes related to this topic: {{note_topic}}\n\nContent areas to analyze:\n{{content_areas}}\n\nReturn actual related notes from the vault, not fictional ones.",
46 | arguments: [
47 | {"name": "vault_path", "description": "Path to the vault directory", "required": true},
48 | {"name": "note_topic", "description": "Main topic/content to find related notes for", "required": true},
49 | {"name": "content_areas", "description": "Specific content areas to analyze", "required": false}
50 | ])
51 | ```
52 |
53 | #### Step 4: Update the Chain Structure
54 | ```bash
55 | # Update the notes_modular chain to include vault search step
56 | prompt_manager(action: "update",
57 | id: "notes_modular",
58 | description: "Enhanced analysis chain: processes content through initial analysis, deep analysis, structured markdown creation, vault-based related notes discovery, and final refinement with actual cross-references.",
59 | chain_steps: [
60 | {
61 | "id": "step_1",
62 | "name": "Initial Content Analysis (Step 1 of 5)",
63 | "description": "Initial analysis of provided content",
64 | "promptId": "content_analysis",
65 | "order": 0,
66 | "dependencies": [],
67 | "inputMapping": {
68 | "content": "content"
69 | },
70 | "outputMapping": {
71 | "result": "content_analysis_output"
72 | }
73 | },
74 | {
75 | "id": "step_2",
76 | "name": "Deep Analysis (Step 2 of 5)",
77 | "description": "Deep analysis building on initial analysis",
78 | "promptId": "deep_analysis",
79 | "order": 1,
80 | "dependencies": ["step_1"],
81 | "inputMapping": {
82 | "content": "content",
83 | "initial_analysis": "content_analysis_output"
84 | },
85 | "outputMapping": {
86 | "result": "deep_analysis_output"
87 | }
88 | },
89 | {
90 | "id": "step_3",
91 | "name": "Markdown Notebook Creation (Step 3 of 5)",
92 | "description": "Convert analysis into structured markdown notebook",
93 | "promptId": "markdown_notebook",
94 | "order": 2,
95 | "dependencies": ["step_2"],
96 | "inputMapping": {
97 | "content": "content",
98 | "analysis": "deep_analysis_output"
99 | },
100 | "outputMapping": {
101 | "result": "notebook_output"
102 | }
103 | },
104 | {
105 | "id": "step_4",
106 | "name": "Vault Related Notes Search (Step 4 of 5)",
107 | "description": "Search vault for actual related notes using content analysis",
108 | "promptId": "vault_related_notes_finder",
109 | "order": 3,
110 | "dependencies": ["step_3"],
111 | "inputMapping": {
112 | "note_topic": "content",
113 | "content_areas": "deep_analysis_output",
114 | "vault_path": "/mnt/c/Users/legoj/Notes/Notion"
115 | },
116 | "outputMapping": {
117 | "result": "related_notes"
118 | },
119 | "timeout": 300000,
120 | "optional": false
121 | },
122 | {
123 | "id": "step_5",
124 | "name": "Note Refinement with Related Notes (Step 5 of 5)",
125 | "description": "Final refinement incorporating actual vault-searched related notes",
126 | "promptId": "note_refinement_with_vault",
127 | "order": 4,
128 | "dependencies": ["step_3", "step_4"],
129 | "inputMapping": {
130 | "notes": "notebook_output",
131 | "related_notes": "related_notes"
132 | },
133 | "outputMapping": {
134 | "result": "result"
135 | },
136 | "timeout": 300000,
137 | "optional": false
138 | }
139 | ])
140 | ```
141 |
142 | #### Step 5: Create Enhanced Note Refinement Prompt
143 | ```bash
144 | # Create the final refinement prompt that incorporates actual related notes
145 | prompt_manager(action: "create",
146 | id: "note_refinement_with_vault",
147 | name: "Note Refinement with Vault Integration",
148 | category: "analysis",
149 | description: "Final step in the notes chain that integrates actual vault-discovered related notes with refined markdown formatting",
150 | system_message: "You are an expert at organizing and refining knowledge notes with proper cross-referencing. Your task is to take markdown notes and enhance them with actual related notes found in the vault, creating a polished, interconnected knowledge artifact.",
151 | user_message_template: "Please refine and enhance these markdown notes by integrating the actual related notes that were found in the vault:\n\n## Original Notes:\n{{notes}}\n\n## Related Notes Found in Vault:\n{{related_notes}}\n\n## Task:\n1. Review the original notes and related notes\n2. Integrate relevant information from the related notes\n3. Add proper cross-references and links\n4. Improve the structure and formatting\n5. Ensure the final output is a cohesive, well-organized knowledge artifact\n\nReturn the refined notes with actual cross-references to the vault notes.",
152 | arguments: [
153 | {"name": "notes", "description": "Original markdown notes to refine", "required": true},
154 | {"name": "related_notes", "description": "Related notes found in the vault", "required": true}
155 | ])
156 | ```
157 |
158 | #### Step 6: Apply Changes and Test
159 | ```bash
160 | # Reload to apply all changes
161 | prompt_manager(action: "reload")
162 |
163 | # Test the updated chain
164 | prompt_engine(command: ">>notes_modular content:'Test content to see if vault search works'")
165 |
166 | # Verify the chain structure
167 | prompt_manager(action: "list", filter: "notes_modular", verbose: true)
168 | ```
169 |
170 | ## Example 2: Adding a Step to Existing Chain
171 |
172 | ### Scenario: Add validation step to a processing chain
173 |
174 | ```bash
175 | # 1. Check current chain structure
176 | prompt_manager(action: "list", filter: "processing_chain", verbose: true)
177 |
178 | # 2. Create validation prompt if needed
179 | prompt_manager(action: "create",
180 | id: "content_validator",
181 | name: "Content Validator",
182 | category: "validation",
183 | description: "Validates processed content for quality and completeness",
184 | user_message_template: "Validate this content: {{content}}\n\nCheck for:\n- Completeness\n- Accuracy\n- Format compliance\n\nReturn validation results.")
185 |
186 | # 3. Update chain to insert validation step
187 | prompt_manager(action: "update",
188 | id: "processing_chain",
189 | chain_steps: [
190 | // ... existing steps up to where validation should be inserted ...
191 | {
192 | "id": "validation_step",
193 | "name": "Content Validation",
194 | "promptId": "content_validator",
195 | "order": 2, // Insert at appropriate position
196 | "dependencies": ["previous_step"],
197 | "inputMapping": {
198 | "content": "processed_content"
199 | },
200 | "outputMapping": {
201 | "result": "validation_results"
202 | }
203 | },
204 | // ... remaining steps with updated dependencies and order numbers ...
205 | ])
206 |
207 | # 4. Apply and test
208 | prompt_manager(action: "reload")
209 | prompt_engine(command: ">>processing_chain input:'test data'")
210 | ```
211 |
212 | ## Example 3: Modifying Chain Step Parameters
213 |
214 | ### Scenario: Update timeout and input mappings for a step
215 |
216 | ```bash
217 | # 1. Get current chain definition
218 | prompt_manager(action: "list", filter: "my_chain", verbose: true)
219 |
220 | # 2. Update with modified parameters
221 | prompt_manager(action: "update",
222 | id: "my_chain",
223 | chain_steps: [
224 | {
225 | "id": "slow_step",
226 | "name": "Processing Step",
227 | "promptId": "heavy_processor",
228 | "order": 1,
229 | "dependencies": ["step_0"],
230 | "inputMapping": {
231 | "input_data": "raw_data",
232 | "processing_mode": "thorough", // New parameter
233 | "batch_size": 100 // New parameter
234 | },
235 | "outputMapping": {
236 | "result": "processed_data"
237 | },
238 | "timeout": 600000, // Increased from 300000
239 | "optional": false
240 | }
241 | // ... other steps ...
242 | ])
243 |
244 | # 3. Apply changes
245 | prompt_manager(action: "reload")
246 | ```
247 |
248 | ## Key Principles
249 |
250 | ### 1. Always Use MCP Tools
251 | - ✅ `prompt_manager(action: "update", ...)`
252 | - ❌ `Update(~/prompts/chain.json)`
253 |
254 | ### 2. Check Before Creating
255 | - Use `prompt_manager(action: "list")` to see what exists
256 | - Avoid duplicating existing functionality
257 |
258 | ### 3. Reload After Changes
259 | - Always call `prompt_manager(action: "reload")` after modifications
260 | - This ensures hot-reloading picks up changes
261 |
262 | ### 4. Test Changes
263 | - Use `prompt_engine(command: ">>chain_name ...")` to test
264 | - Verify with `prompt_manager(action: "list", verbose: true)`
265 |
266 | ### 5. Structured Data Approach
267 | - Define complete chain_steps arrays with all required fields
268 | - Use proper dependency management (order, dependencies arrays)
269 | - Include all metadata (timeouts, optional flags, etc.)
270 |
271 | ## Common Pitfalls to Avoid
272 |
273 | 1. **Direct File Editing**: Never use Update(), Edit(), Write() on prompt files
274 | 2. **Partial Updates**: Always provide complete chain_steps array, not partial modifications
275 | 3. **Missing Dependencies**: Ensure step dependencies are correctly specified
276 | 4. **Skipping Reload**: Changes won't take effect without reload
277 | 5. **Wrong Order Numbers**: Step order affects execution sequence
278 | 6. **Missing Error Handling**: Consider timeout and optional settings for reliability
279 |
280 | ## Advanced Patterns
281 |
282 | ### Conditional Chain Steps
283 | ```bash
284 | # Use optional: true for steps that may fail
285 | {
286 | "id": "optional_enhancement",
287 | "name": "Enhancement Step",
288 | "promptId": "enhancer",
289 | "optional": true, // Won't fail chain if this step fails
290 | "timeout": 30000 // Shorter timeout for optional steps
291 | }
292 | ```
293 |
294 | ### Parallel Processing
295 | ```bash
296 | # Steps with same order number execute in parallel
297 | {
298 | "id": "parallel_step_a",
299 | "order": 2,
300 | "dependencies": ["step_1"]
301 | },
302 | {
303 | "id": "parallel_step_b",
304 | "order": 2,
305 | "dependencies": ["step_1"]
306 | }
307 | ```
308 |
309 | ### Data Transformation
310 | ```bash
311 | # Use inputMapping to transform data between steps
312 | {
313 | "inputMapping": {
314 | "prompt_input_name": "previous_step_output_key",
315 | "static_value": "constant_data",
316 | "computed_value": "{{dynamic_expression}}"
317 | }
318 | }
319 | ```
```
--------------------------------------------------------------------------------
/server/src/frameworks/types/prompt-guidance-types.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Prompt Guidance Type Definitions
3 | *
4 | * Contains all types related to prompt enhancement, system prompt injection,
5 | * and methodology-driven template processing. These types support the prompt
6 | * guidance system that enhances MCP prompts with methodology-specific improvements.
7 | */
8 |
9 | import type { ConvertedPrompt } from '../../execution/types.js';
10 | import type { FrameworkDefinition, MethodologyEnhancement, ProcessingGuidance } from './methodology-types.js';
11 |
12 | /**
13 | * System prompt injection configuration
14 | */
15 | export interface SystemPromptInjectionConfig {
16 | /** Whether to inject methodology guidance into system prompts */
17 | enabled: boolean;
18 | /** Priority of injection (higher values override lower) */
19 | priority: number;
20 | /** Template for injecting methodology guidance */
21 | injectionTemplate: string;
22 | /** Variables available for injection template */
23 | availableVariables: string[];
24 | }
25 |
26 | /**
27 | * System prompt injection result
28 | */
29 | export interface SystemPromptInjectionResult {
30 | /** Original system prompt before injection */
31 | originalPrompt: string;
32 | /** Enhanced system prompt with methodology guidance */
33 | enhancedPrompt: string;
34 | /** Methodology guidance that was injected */
35 | injectedGuidance: string;
36 | /** Framework that provided the guidance */
37 | sourceFramework: FrameworkDefinition;
38 | /** Injection metadata */
39 | metadata: {
40 | injectionTime: Date;
41 | injectionMethod: string;
42 | variablesUsed: string[];
43 | confidence: number;
44 | processingTimeMs: number;
45 | validationPassed: boolean;
46 | error?: string;
47 | // Phase 4: Semantic analysis metadata
48 | semanticAware?: boolean;
49 | semanticComplexity?: 'low' | 'medium' | 'high';
50 | semanticConfidence?: number;
51 | };
52 | }
53 |
54 | /**
55 | * Template enhancement configuration
56 | */
57 | export interface TemplateEnhancementConfig {
58 | /** Whether to enhance templates with methodology guidance */
59 | enabled: boolean;
60 | /** Types of enhancements to apply */
61 | enabledEnhancements: TemplateEnhancementType[];
62 | /** Minimum confidence threshold for applying enhancements */
63 | confidenceThreshold: number;
64 | /** Maximum number of enhancements to apply */
65 | maxEnhancements: number;
66 | }
67 |
68 | /**
69 | * Types of template enhancements
70 | */
71 | export type TemplateEnhancementType =
72 | | 'structure'
73 | | 'clarity'
74 | | 'completeness'
75 | | 'methodology_alignment'
76 | | 'quality_gates';
77 |
78 | /**
79 | * Template enhancement result
80 | */
81 | export interface TemplateEnhancementResult {
82 | /** Original template before enhancement */
83 | originalTemplate: string;
84 | /** Enhanced template with methodology improvements */
85 | enhancedTemplate: string;
86 | /** Applied enhancements */
87 | suggestions: string[];
88 | /** Template processing guidance from methodology */
89 | processingGuidance: ProcessingGuidance;
90 | /** Framework that provided the guidance */
91 | sourceFramework: FrameworkDefinition;
92 | /** Enhancement metadata */
93 | metadata: {
94 | enhancementTime: Date;
95 | enhancementLevel: 'minimal' | 'moderate' | 'comprehensive';
96 | suggestionsCount: number;
97 | validationPassed: boolean;
98 | processingTimeMs: number;
99 | methodologyApplied: string;
100 | error?: string;
101 | // Phase 4: Semantic analysis metadata
102 | semanticAware?: boolean;
103 | semanticComplexity?: 'low' | 'medium' | 'high';
104 | semanticConfidence?: number;
105 | semanticEnhancementsApplied?: string[];
106 | };
107 | /** Validation result */
108 | validation: {
109 | passed: boolean;
110 | score: number;
111 | issues: string[];
112 | recommendations: string[];
113 | };
114 | }
115 |
116 | /**
117 | * Applied enhancement details
118 | */
119 | export interface AppliedEnhancement {
120 | /** Type of enhancement applied */
121 | type: TemplateEnhancementType;
122 | /** Description of what was enhanced */
123 | description: string;
124 | /** Location in template where enhancement was applied */
125 | location: 'system' | 'user' | 'arguments' | 'metadata';
126 | /** Enhancement content that was added/modified */
127 | content: string;
128 | /** Confidence in this enhancement */
129 | confidence: number;
130 | /** Methodology justification for the enhancement */
131 | justification: string;
132 | }
133 |
134 | /**
135 | * Methodology tracking state
136 | */
137 | export interface MethodologyTrackingState {
138 | /** Currently active methodology */
139 | activeMethodology: string;
140 | /** Previous methodology (for switch tracking) */
141 | previousMethodology: string | null;
142 | /** When the current methodology was activated */
143 | activatedAt: Date;
144 | /** Reason for the current methodology selection */
145 | activationReason: string;
146 | /** Whether methodology tracking is enabled */
147 | trackingEnabled: boolean;
148 | /** Methodology switch history */
149 | switchHistory: MethodologySwitchRecord[];
150 | }
151 |
152 | /**
153 | * Methodology switch record
154 | */
155 | export interface MethodologySwitchRecord {
156 | /** When the switch occurred */
157 | timestamp: Date;
158 | /** Methodology switched from */
159 | fromMethodology: string;
160 | /** Methodology switched to */
161 | toMethodology: string;
162 | /** Reason for the switch */
163 | reason: string;
164 | /** Whether the switch was successful */
165 | successful: boolean;
166 | /** Switch duration in milliseconds */
167 | duration: number;
168 | }
169 |
170 | /**
171 | * Methodology state change event
172 | */
173 | export interface MethodologyStateChangeEvent {
174 | /** Type of state change */
175 | type: 'switch' | 'enable' | 'disable' | 'error';
176 | /** Previous state */
177 | previousState: MethodologyTrackingState;
178 | /** New state */
179 | newState: MethodologyTrackingState;
180 | /** Event timestamp */
181 | timestamp: Date;
182 | /** Additional event context */
183 | context?: Record<string, any>;
184 | }
185 |
186 | /**
187 | * Prompt guidance configuration
188 | */
189 | export interface PromptGuidanceConfig {
190 | /** System prompt injection configuration */
191 | systemPromptInjection: SystemPromptInjectionConfig;
192 | /** Template enhancement configuration */
193 | templateEnhancement: TemplateEnhancementConfig;
194 | /** Methodology tracking configuration */
195 | methodologyTracking: {
196 | enabled: boolean;
197 | persistState: boolean;
198 | trackSwitches: boolean;
199 | maxHistoryEntries: number;
200 | };
201 | }
202 |
203 | /**
204 | * Comprehensive prompt guidance result
205 | */
206 | export interface PromptGuidanceResult {
207 | /** Original prompt before guidance was applied */
208 | originalPrompt: ConvertedPrompt;
209 | /** Enhanced prompt with all guidance applied */
210 | enhancedPrompt: ConvertedPrompt;
211 | /** System prompt injection result */
212 | systemPromptInjection: SystemPromptInjectionResult | null;
213 | /** Template enhancement result */
214 | templateEnhancement: TemplateEnhancementResult | null;
215 | /** Applied methodology enhancement */
216 | methodologyEnhancement: MethodologyEnhancement | null;
217 | /** Guidance metadata */
218 | metadata: {
219 | guidanceTime: Date;
220 | activeMethodology: string;
221 | totalEnhancements: number;
222 | confidenceScore: number;
223 | processingTime: number;
224 | };
225 | }
226 |
227 | /**
228 | * Prompt guidance analytics
229 | */
230 | export interface PromptGuidanceAnalytics {
231 | /** Total number of prompts enhanced */
232 | totalEnhanced: number;
233 | /** Enhancement success rate */
234 | successRate: number;
235 | /** Average enhancement confidence */
236 | averageConfidence: number;
237 | /** Most common enhancement types */
238 | commonEnhancements: Record<TemplateEnhancementType, number>;
239 | /** Methodology usage distribution */
240 | methodologyUsage: Record<string, {
241 | count: number;
242 | averageConfidence: number;
243 | successRate: number;
244 | }>;
245 | /** Performance metrics */
246 | performance: {
247 | averageProcessingTime: number;
248 | maxProcessingTime: number;
249 | totalProcessingTime: number;
250 | };
251 | }
252 |
253 | /**
254 | * Framework state information for prompt guidance
255 | */
256 | export interface FrameworkStateInfo {
257 | /** Whether framework system is enabled */
258 | frameworkSystemEnabled: boolean;
259 | /** Active framework definition */
260 | activeFramework: FrameworkDefinition | null;
261 | /** Available frameworks */
262 | availableFrameworks: FrameworkDefinition[];
263 | /** Framework health status */
264 | healthStatus: 'healthy' | 'degraded' | 'error';
265 | /** Framework switching metrics */
266 | switchingMetrics: {
267 | totalSwitches: number;
268 | successfulSwitches: number;
269 | averageResponseTime: number;
270 | };
271 | }
272 |
273 | /**
274 | * Prompt guidance service interface
275 | */
276 | export interface IPromptGuidanceService {
277 | /**
278 | * Apply comprehensive guidance to a prompt
279 | */
280 | applyGuidance(
281 | prompt: ConvertedPrompt,
282 | config?: Partial<PromptGuidanceConfig>
283 | ): Promise<PromptGuidanceResult>;
284 |
285 | /**
286 | * Get current methodology tracking state
287 | */
288 | getMethodologyState(): MethodologyTrackingState;
289 |
290 | /**
291 | * Get framework state information
292 | */
293 | getFrameworkState(): FrameworkStateInfo;
294 |
295 | /**
296 | * Get guidance analytics
297 | */
298 | getAnalytics(): PromptGuidanceAnalytics;
299 |
300 | /**
301 | * Reset analytics and tracking data
302 | */
303 | resetAnalytics(): void;
304 | }
305 |
306 | /**
307 | * Methodology state information (Phase 3)
308 | */
309 | export interface MethodologyState {
310 | /** Currently active methodology */
311 | activeMethodology: string;
312 | /** Previous methodology (for switch tracking) */
313 | previousMethodology: string | null;
314 | /** When the current methodology was activated */
315 | switchedAt: Date;
316 | /** Reason for the current methodology selection */
317 | switchReason: string;
318 | /** Whether methodology system is healthy */
319 | isHealthy: boolean;
320 | /** Whether methodology system is enabled */
321 | methodologySystemEnabled: boolean;
322 | /** Methodology switching metrics */
323 | switchingMetrics: {
324 | switchCount: number;
325 | averageResponseTime: number;
326 | errorCount: number;
327 | };
328 | }
329 |
330 | /**
331 | * Methodology switch request (Phase 3)
332 | */
333 | export interface MethodologySwitchRequest {
334 | /** Target methodology to switch to */
335 | targetMethodology: string;
336 | /** Reason for the switch */
337 | reason?: string;
338 | /** Additional criteria for the switch */
339 | criteria?: Record<string, any>;
340 | }
341 |
342 | /**
343 | * Methodology system health information (Phase 3)
344 | */
345 | export interface MethodologyHealth {
346 | /** System health status */
347 | status: "healthy" | "degraded" | "error";
348 | /** Currently active methodology */
349 | activeMethodology: string;
350 | /** Whether methodology system is enabled */
351 | methodologySystemEnabled: boolean;
352 | /** Last switch time */
353 | lastSwitchTime: Date | null;
354 | /** Switching performance metrics */
355 | switchingMetrics: {
356 | totalSwitches: number;
357 | successfulSwitches: number;
358 | failedSwitches: number;
359 | averageResponseTime: number;
360 | };
361 | /** Current health issues */
362 | issues: string[];
363 | }
364 |
365 | /**
366 | * Persisted methodology state for disk storage (Phase 3)
367 | */
368 | export interface PersistedMethodologyState {
369 | /** State format version */
370 | version: string;
371 | /** Whether methodology system is enabled */
372 | methodologySystemEnabled: boolean;
373 | /** Currently active methodology */
374 | activeMethodology: string;
375 | /** Last switch timestamp as ISO string */
376 | lastSwitchedAt: string;
377 | /** Reason for current state */
378 | switchReason: string;
379 | }
380 |
381 | /**
382 | * Template processing guidance from methodology guides (Phase 3)
383 | * Extends the base ProcessingGuidance interface
384 | */
385 | export interface TemplateProcessingGuidance {
386 | // Methodology-specific processing steps
387 | processingSteps: Array<{
388 | id: string;
389 | name: string;
390 | action: string;
391 | methodologyPhase: string;
392 | dependencies: string[];
393 | expected_output: string;
394 | }>;
395 |
396 | // Template enhancement suggestions
397 | templateEnhancements: {
398 | systemPromptAdditions: string[];
399 | userPromptModifications: string[];
400 | contextualHints: string[];
401 | };
402 |
403 | // Execution flow guidance
404 | executionFlow: {
405 | preProcessingSteps: string[];
406 | postProcessingSteps: string[];
407 | validationSteps: string[];
408 | };
409 | }
```
--------------------------------------------------------------------------------
/server/src/types/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Consolidated Type Index for MCP Prompts Server
3 | *
4 | * This module serves as the central type export hub, importing from domain-specific
5 | * type files and re-exporting them for easy consumption. Types are now organized
6 | * by domain for better maintainability and reduced duplication.
7 | *
8 | * Architecture: Domain-specific types -> This index -> Consumer modules
9 | */
10 |
11 | // ===== Import Domain-Specific Types =====
12 |
13 | // Core configuration and protocol types
14 | export type {
15 | Config,
16 | ServerConfig,
17 | TransportConfig,
18 | TransportsConfig,
19 | LoggingConfig,
20 | AnalysisMode,
21 | LLMProvider,
22 | LLMIntegrationConfig,
23 | SemanticAnalysisConfig,
24 | AnalysisConfig,
25 | ToolDescriptionsOptions,
26 | Message,
27 | MessageContent,
28 | MessageRole,
29 | TextMessageContent,
30 | BaseMessageContent
31 | } from '../types.js';
32 |
33 | // Prompt system types
34 | export type {
35 | PromptArgument,
36 | Category,
37 | PromptData,
38 | PromptFile,
39 | PromptsConfig,
40 | PromptsConfigFile,
41 | PromptsFile,
42 | PromptFileContent,
43 | CategoryPromptsResult,
44 | CategoryValidationResult,
45 | CategoryStatistics,
46 | CategoryPromptRelationship
47 | } from '../prompts/types.js';
48 |
49 | // Execution system types
50 | export type {
51 | ConvertedPrompt,
52 | ChainStep,
53 | ExecutionStrategyType,
54 | ExecutionType,
55 | BaseExecutionContext,
56 | UnifiedExecutionResult,
57 | ExecutionStrategy,
58 | ChainExecutionResult,
59 | ChainStepResult,
60 | ChainExecutionState,
61 | EnhancedChainExecutionOptions,
62 | TemplateContext,
63 | ValidationResult,
64 | ExecutionStats,
65 | PerformanceMetrics
66 | } from '../execution/types.js';
67 |
68 | // Import additional types needed for interfaces in this file
69 | import type {
70 | ChainStep,
71 | EnhancedChainExecutionOptions,
72 | ChainStepResult
73 | } from '../execution/types.js';
74 | import type {
75 | GateStatus,
76 | StepResult
77 | } from '../gates/types.js';
78 |
79 | // Gate system types
80 | export type {
81 | GateDefinition,
82 | GateRequirement,
83 | GateRequirementType,
84 | GateStatus,
85 | GateEvaluationResult,
86 | ValidationContext,
87 | GateActivationResult,
88 | LightweightGateDefinition,
89 | GatePassCriteria,
90 | ValidationCheck,
91 | GatesConfig,
92 | StepResult,
93 | GateType
94 | } from '../gates/types.js';
95 |
96 | // Framework system types (consolidated in Phase 2)
97 | export type {
98 | FrameworkDefinition,
99 | FrameworkExecutionContext,
100 | FrameworkSelectionCriteria,
101 | FrameworkMethodology,
102 | IMethodologyGuide,
103 | FrameworkStateInfo,
104 | IntegratedAnalysisResult,
105 | FrameworkSwitchingConfig
106 | } from '../frameworks/types/index.js';
107 |
108 | // ===== Additional System Types =====
109 |
110 | // Text Reference System Types
111 | export interface TextReference {
112 | id: string;
113 | title: string;
114 | content: string;
115 | createdAt: number;
116 | lastUsed: number;
117 | }
118 |
119 | export interface TextReferenceStore {
120 | references: TextReference[];
121 | maxAge: number; // Maximum age in milliseconds before cleanup
122 | maxSize: number; // Maximum number of references to store
123 | }
124 |
125 | // Conversation History Types
126 | export interface ConversationHistoryItem {
127 | role: "user" | "assistant";
128 | content: string;
129 | timestamp: number;
130 | isProcessedTemplate?: boolean; // Flag to indicate if this is a processed template rather than original user input
131 | }
132 |
133 | // Advanced Chain Execution Types
134 | export interface EnhancedChainExecutionContext {
135 | chainId: string;
136 | chainName: string;
137 | startTime: number;
138 | executionOptions: EnhancedChainExecutionOptions;
139 |
140 | // Enhanced step tracking
141 | allSteps: ChainStep[]; // All steps in the chain
142 | completedSteps: Set<string>; // Step IDs that have completed successfully
143 | failedSteps: Set<string>; // Step IDs that have failed
144 | skippedSteps: Set<string>; // Step IDs that were skipped due to dependencies/conditions
145 | stepResults: Record<string, StepResult>; // Detailed results from each step
146 |
147 | // Dependency management
148 | executionPlan?: {
149 | executionOrder: string[]; // Topologically sorted step execution order
150 | parallelGroups: Map<string, string[]>; // Parallel execution groups
151 | };
152 |
153 | // Advanced execution state
154 | currentPhase: 'planning' | 'executing' | 'completed' | 'failed';
155 | activeParallelGroups: Map<string, string[]>; // Currently executing parallel groups
156 | retryCount: Record<string, number>; // Retry attempts per step
157 |
158 | // Gate validation tracking
159 | gateValidationResults: Record<string, GateStatus[]>; // Gate results per step
160 | }
161 |
162 | // API Response Types
163 | export interface ApiResponse {
164 | success: boolean;
165 | message: string;
166 | data?: unknown;
167 | }
168 |
169 | export interface ToolResponse {
170 | content: Array<{
171 | type: "text";
172 | text: string;
173 | }>;
174 | isError?: boolean;
175 |
176 | // Structured output data for programmatic access
177 | structuredContent?: {
178 | // Gate validation results in structured format
179 | gateValidation?: {
180 | enabled: boolean;
181 | passed: boolean;
182 | totalGates: number;
183 | failedGates: Array<{
184 | gateId: string;
185 | gateName: string;
186 | reason: string;
187 | score?: number;
188 | requirements: string[];
189 | evaluationTime?: number;
190 | }>;
191 | passedGates?: Array<{
192 | gateId: string;
193 | gateName: string;
194 | score?: number;
195 | }>;
196 | executionTime: number;
197 | retryCount?: number;
198 | };
199 |
200 | // Core execution metadata
201 | executionMetadata?: {
202 | executionId: string;
203 | executionType: "prompt" | "template" | "chain";
204 | startTime: number;
205 | endTime: number;
206 | executionTime: number;
207 | frameworkUsed?: string;
208 | frameworkEnabled: boolean;
209 | stepsExecuted?: number;
210 | sessionId?: string;
211 | memoryUsage?: {
212 | heapUsed: number;
213 | heapTotal: number;
214 | external: number;
215 | };
216 | };
217 |
218 | // Analytics and performance data
219 | analytics?: {
220 | totalExecutions: number;
221 | successRate: number;
222 | averageExecutionTime: number;
223 | frameworkSwitches?: number;
224 | gateValidationCount?: number;
225 | errorCount?: number;
226 | uptime: number;
227 | };
228 |
229 | // Chain execution progress (for chain operations)
230 | chainProgress?: {
231 | chainId: string;
232 | chainName: string;
233 | currentStep: number;
234 | totalSteps: number;
235 | status: "pending" | "running" | "completed" | "failed" | "paused";
236 | steps: Array<{
237 | stepIndex: number;
238 | stepName: string;
239 | promptId: string;
240 | status: "pending" | "running" | "completed" | "failed" | "skipped";
241 | startTime?: number;
242 | endTime?: number;
243 | duration?: number;
244 | result?: string;
245 | error?: string;
246 | }>;
247 | autoExecute: boolean;
248 | sessionStrategy?: "auto" | "explicit" | "new";
249 | executionOptions?: {
250 | stepConfirmation: boolean;
251 | gateValidation: boolean;
252 | frameworkEnabled: boolean;
253 | };
254 | };
255 |
256 | // Error information (for failed operations)
257 | errorInfo?: {
258 | errorCode: string;
259 | errorType: "validation" | "execution" | "system" | "client" | "configuration";
260 | message: string;
261 | details?: any;
262 | timestamp: number;
263 | severity: "low" | "medium" | "high" | "critical";
264 | suggestedActions?: string[];
265 | relatedComponents?: string[];
266 | };
267 |
268 | // Tool-specific structured data
269 | [key: string]: any;
270 | };
271 | }
272 |
273 | // Tool Description Types
274 | export interface ToolParameter {
275 | description?: string;
276 | examples?: string[];
277 | }
278 |
279 | export interface ToolDescription {
280 | description: string;
281 | parameters?: Record<string, ToolParameter | string>;
282 | shortDescription?: string;
283 | category?: string;
284 | frameworkAware?: {
285 | enabled?: string;
286 | disabled?: string;
287 | parametersEnabled?: Record<string, ToolParameter | string>;
288 | parametersDisabled?: Record<string, ToolParameter | string>;
289 | methodologies?: Record<string, string>;
290 | methodologyParameters?: Record<string, Record<string, ToolParameter | string>>;
291 | };
292 | }
293 |
294 | export interface ToolDescriptionsConfig {
295 | version: string;
296 | lastUpdated?: string;
297 | tools: Record<string, ToolDescription>;
298 | }
299 |
300 | // Server Management Types
301 | export interface ServerRefreshOptions {
302 | restart?: boolean;
303 | reason?: string;
304 | }
305 |
306 | export interface ServerState {
307 | isStarted: boolean;
308 | transport: string;
309 | port?: number;
310 | startTime: number;
311 | }
312 |
313 | // File Operation Types
314 | export interface FileOperation {
315 | (): Promise<boolean>;
316 | }
317 |
318 | export interface ModificationResult {
319 | success: boolean;
320 | message: string;
321 | }
322 |
323 | // Express and Transport Types
324 | export interface ExpressRequest {
325 | body: any;
326 | params: Record<string, string>;
327 | headers: Record<string, string>;
328 | ip: string;
329 | method: string;
330 | url: string;
331 | }
332 |
333 | export interface ExpressResponse {
334 | json: (data: any) => void;
335 | status: (code: number) => ExpressResponse;
336 | send: (data: any) => void;
337 | setHeader: (name: string, value: string) => void;
338 | end: () => void;
339 | sendStatus: (code: number) => void;
340 | on: (event: string, callback: () => void) => void;
341 | }
342 |
343 | // Execution State Types
344 | export interface ExecutionState {
345 | type: 'single' | 'chain';
346 | promptId: string;
347 | status: 'pending' | 'running' | 'waiting_gate' | 'completed' | 'failed' | 'retrying';
348 | currentStep?: number;
349 | totalSteps?: number;
350 | gates: GateStatus[];
351 | results: Record<string, string | ChainStepResult>;
352 | metadata: {
353 | startTime: number;
354 | endTime?: number;
355 | executionMode?: 'prompt' | 'template' | 'chain';
356 | stepConfirmation?: boolean;
357 | gateValidation?: boolean;
358 | sessionId?: string; // For chain session management
359 | };
360 | }
361 |
362 | // Enhanced Chain Execution Types
363 | export interface EnhancedChainExecutionState {
364 | chainId: string;
365 | currentStepIndex: number;
366 | totalSteps: number;
367 | startTime: number;
368 | status: 'pending' | 'running' | 'waiting_gate' | 'completed' | 'failed';
369 | stepResults: Record<string, StepResult>;
370 | gates: Record<string, GateStatus>;
371 | executionMode: 'auto' | 'chain';
372 | gateValidation: boolean;
373 | stepConfirmation: boolean;
374 | }
375 |
376 | // Chain execution progress tracking
377 | export interface ChainExecutionProgress {
378 | chainId: string;
379 | chainName: string;
380 | currentStep: number;
381 | totalSteps: number;
382 | status: 'pending' | 'running' | 'completed' | 'failed' | 'paused';
383 | steps: ChainStepProgress[];
384 | startTime: number;
385 | endTime?: number;
386 | duration?: number;
387 | errorCount: number;
388 | autoExecute: boolean;
389 | }
390 |
391 | export interface ChainStepProgress {
392 | stepIndex: number;
393 | stepName: string;
394 | promptId: string;
395 | status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
396 | startTime?: number;
397 | endTime?: number;
398 | duration?: number;
399 | result?: string;
400 | error?: string;
401 | gateResults?: GateStatus[];
402 | }
403 |
404 | // Auto-execution configuration for chains
405 | export interface AutoExecutionConfig {
406 | enabled: boolean;
407 | stepConfirmation: boolean;
408 | gateValidation: boolean;
409 | pauseOnError: boolean;
410 | maxRetries: number;
411 | retryDelay: number; // milliseconds
412 | }
413 |
414 | // Constants and Enums
415 | export const MAX_HISTORY_SIZE = 100;
416 |
417 | export enum LogLevel {
418 | DEBUG = "DEBUG",
419 | INFO = "INFO",
420 | WARN = "WARN",
421 | ERROR = "ERROR",
422 | }
423 |
424 | export enum TransportType {
425 | STDIO = "stdio",
426 | SSE = "sse",
427 | }
428 |
429 | export enum ExecutionMode {
430 | AUTO = "auto",
431 | TEMPLATE = "template",
432 | CHAIN = "chain",
433 | }
434 |
435 | export enum StepStatus {
436 | PENDING = "pending",
437 | RUNNING = "running",
438 | COMPLETED = "completed",
439 | FAILED = "failed",
440 | SKIPPED = "skipped",
441 | }
442 |
443 | // ===== End of Consolidated Type Definitions =====
444 | // Types are now organized by domain for better maintainability:
445 | // - Core types: ../types.js
446 | // - Prompt types: ../prompts/types.js
447 | // - Execution types: ../execution/types.js
448 | // - Gate types: ../gates/types.js
449 | // - Framework types: ../frameworks/types/index.js
```