@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/workflow-templates.md

@@ -0,0 +1,423 @@
+# Workflow Templates
+
+The Template Registry provides pre-built templates for common workflow types, making it easy to get started quickly.
+
+## Quick Start
+
+### Using CLI
+
+```bash
+# List available templates
+node scripts/create-from-template.js --list
+
+# Create from template
+node scripts/create-from-template.js bug-investigation
+
+# This creates: bug-investigation-workflow.json
+```
+
+### Using Programmatically
+
+```javascript
+import { templateRegistry } from './template-registry.js';
+
+// Create from template
+const data = templateRegistry.createFromTemplate('bug-investigation', {
+  'dashboard.title': 'Auth Token Bug',
+  'bugSummary': 'Users unable to log in'
+});
+
+// Use in workflow
+workrail.createSession('my-workflow', 'BUG-001', data);
+```
+
+## Available Templates
+
+### Bug Investigation
+
+**ID:** `bug-investigation`  
+**Category:** Debugging  
+**Schema:** bug-investigation
+
+Systematic bug investigation with hypotheses, timeline, and recommendations.
+
+**Fields:**
+- `dashboard` - Title, status, progress, confidence
+- `bugSummary` - Detailed bug description
+- `hypotheses` - Array of hypotheses with status
+- `timeline` - Investigation timeline
+- `phases` - Investigation phases
+- `recommendations` - Suggested fixes
+
+**Example:**
+```javascript
+{
+  dashboard: {
+    title: 'Auth Token Expiration Bug',
+    status: 'in_progress',
+    progress: 45,
+    confidence: 7
+  },
+  bugSummary: 'Users are being logged out unexpectedly',
+  hypotheses: [
+    {
+      description: 'Token expiration time misconfigured',
+      status: 'confirmed',
+      confidence: 9
+    }
+  ]
+}
+```
+
+### Code Review
+
+**ID:** `code-review`  
+**Category:** Quality  
+**Schema:** code-review
+
+Code review workflow with findings, severities, and approval tracking.
+
+**Fields:**
+- `dashboard` - Title, status, progress
+- `summary` - Overall review summary
+- `changes` - List of changed files
+- `findings` - Issues found with severity
+- `approved` - Approval status
+
+**Example:**
+```javascript
+{
+  dashboard: {
+    title: 'PR #123: Add Authentication',
+    status: 'in_progress'
+  },
+  findings: [
+    {
+      severity: 'high',
+      description: 'SQL injection vulnerability',
+      file: 'auth.ts',
+      line: 45
+    }
+  ],
+  approved: false
+}
+```
+
+### Test Results
+
+**ID:** `test-results`  
+**Category:** Testing  
+**Schema:** test-results
+
+Test execution results with pass/fail tracking and trends.
+
+**Fields:**
+- `dashboard` - Title, status, progress
+- `summary` - Test counts (total, passed, failed, skipped)
+- `tests` - Individual test results
+- `testResultsTrend` - Historical trend data
+
+**Example:**
+```javascript
+{
+  dashboard: {
+    title: 'E2E Test Run',
+    status: 'passed'
+  },
+  summary: {
+    total: 50,
+    passed: 48,
+    failed: 2,
+    skipped: 0
+  },
+  testResultsTrend: [
+    { label: 'Previous', value: 45 },
+    { label: 'Current', value: 48 }
+  ]
+}
+```
+
+### Documentation
+
+**ID:** `documentation`  
+**Category:** Documentation  
+
+Documentation generation with section tracking and coverage metrics.
+
+**Fields:**
+- `dashboard` - Title, status, progress
+- `sections` - Documentation sections with status
+- `coverage` - Coverage metrics
+
+**Example:**
+```javascript
+{
+  dashboard: {
+    title: 'API Documentation',
+    progress: 75
+  },
+  sections: [
+    { title: 'Overview', status: 'complete' },
+    { title: 'Authentication', status: 'in_progress' }
+  ],
+  coverage: [
+    { label: 'API Coverage', value: 80 },
+    { label: 'Examples', value: 60 }
+  ]
+}
+```
+
+### Performance Analysis
+
+**ID:** `performance-analysis`  
+**Category:** Performance  
+
+Performance investigation and optimization tracking.
+
+**Fields:**
+- `dashboard` - Title, status, progress
+- `metrics` - Performance metrics
+- `findings` - Performance bottlenecks
+- `performanceTrend` - Before/after comparison
+
+**Example:**
+```javascript
+{
+  dashboard: {
+    title: 'Homepage Performance',
+    progress: 60
+  },
+  metrics: [
+    { label: 'Load Time', value: 2.5 },
+    { label: 'Bundle Size', value: 350 }
+  ],
+  performanceTrend: [
+    { label: 'Baseline', value: 3.8 },
+    { label: 'Optimized', value: 2.5 }
+  ]
+}
+```
+
+### Generic Workflow
+
+**ID:** `generic`  
+**Category:** General  
+
+Basic template for any workflow type.
+
+**Fields:**
+- `dashboard` - Title, status, progress
+- `phases` - Workflow phases
+- `timeline` - Event timeline
+
+## Using Templates
+
+### 1. Create Session from Template
+
+```javascript
+// In your workflow
+import { templateRegistry } from '@workrail/template-registry';
+
+const data = templateRegistry.createFromTemplate('bug-investigation', {
+  'dashboard.title': 'My Bug Investigation',
+  'bugSummary': 'Description of the bug'
+});
+
+workrail.createSession('workflow-id', 'session-id', data);
+```
+
+### 2. Update During Workflow
+
+```javascript
+// Update hypothesis
+workrail.updateSession('workflow-id', 'session-id', {
+  hypotheses: [
+    ...existingHypotheses,
+    {
+      description: 'New hypothesis',
+      status: 'active',
+      confidence: 6
+    }
+  ]
+});
+```
+
+### 3. Add to Timeline
+
+```javascript
+// Log investigation step
+workrail.updateSession('workflow-id', 'session-id', {
+  timeline: [
+    ...existingTimeline,
+    {
+      timestamp: new Date().toISOString(),
+      event: 'Found root cause in auth service',
+      reasoning: 'Token validation logic is incorrect'
+    }
+  ]
+});
+```
+
+## Custom Templates
+
+You can create custom templates for your organization:
+
+```javascript
+import { templateRegistry } from '@workrail/template-registry';
+
+templateRegistry.register('deployment', {
+  name: 'Deployment',
+  description: 'Deployment workflow',
+  category: 'operations',
+  workflowType: 'generic',
+  template: {
+    dashboard: {
+      title: 'Deployment: [Environment]',
+      status: 'pending'
+    },
+    environment: 'staging',
+    version: '1.0.0',
+    steps: []
+  },
+  guide: {
+    steps: [
+      '1. Set environment and version',
+      '2. Execute deployment steps',
+      '3. Verify deployment'
+    ],
+    tips: [
+      'Track each deployment step',
+      'Include rollback procedures',
+      'Document any issues encountered'
+    ]
+  }
+});
+```
+
+## Template API
+
+### `templateRegistry.list(category)`
+
+List all templates, optionally filtered by category.
+
+```javascript
+const all = templateRegistry.list();
+const debugging = templateRegistry.list('debugging');
+```
+
+### `templateRegistry.get(id)`
+
+Get a template by ID.
+
+```javascript
+const template = templateRegistry.get('bug-investigation');
+console.log(template.name, template.description);
+```
+
+### `templateRegistry.createFromTemplate(id, customizations)`
+
+Create data from template with customizations.
+
+```javascript
+const data = templateRegistry.createFromTemplate('code-review', {
+  'dashboard.title': 'PR #456',
+  'summary': 'Looks good overall'
+});
+```
+
+### `templateRegistry.getGuide(id)`
+
+Get template usage guide.
+
+```javascript
+const guide = templateRegistry.getGuide('bug-investigation');
+console.log(guide.steps);
+console.log(guide.tips);
+```
+
+### `templateRegistry.exportTemplate(id)`
+
+Export template as JSON string.
+
+```javascript
+const json = templateRegistry.exportTemplate('bug-investigation');
+fs.writeFileSync('template.json', json);
+```
+
+## Best Practices
+
+### 1. Start with a Template
+
+Always start with the closest template to your workflow:
+
+```javascript
+// Instead of starting from scratch
+const data = { dashboard: { title: '...' } };
+
+// Use a template
+const data = templateRegistry.createFromTemplate('bug-investigation');
+```
+
+### 2. Customize Incrementally
+
+Add fields as needed - templates are starting points:
+
+```javascript
+const data = templateRegistry.createFromTemplate('bug-investigation');
+
+// Add custom field
+data.reproductionSteps = [
+  'Step 1',
+  'Step 2'
+];
+```
+
+### 3. Follow Template Patterns
+
+Templates use proven patterns that work well with the dashboard:
+
+- Arrays with `label` + `value` → Charts
+- Fields with `status` → Grouped lists
+- Fields with `timestamp` → Timelines
+- Fields with `severity` → Severity lists
+
+### 4. Use Schemas
+
+Templates specify recommended schemas - use them for validation:
+
+```javascript
+const template = templateRegistry.get('bug-investigation');
+console.log(template.workflowType); // 'bug-investigation'
+
+// Validate against schema
+normalizer.normalize(data, { 
+  workflowType: template.workflowType 
+});
+```
+
+## FAQ
+
+**Q: Can I modify templates?**  
+A: Templates are cloned when used, so modifications don't affect the original.
+
+**Q: Can I create my own templates?**  
+A: Yes! Use `templateRegistry.register()` to add custom templates.
+
+**Q: Do I have to use all fields in a template?**  
+A: No, templates are starting points. Remove unused fields.
+
+**Q: Can I add fields not in the template?**  
+A: Absolutely! Add any fields you need.
+
+**Q: Are templates validated?**  
+A: Templates specify a recommended schema, but validation is optional.
+
+## Examples
+
+See `workflows/` directory for example workflows using templates.
+
+
+
+
+
+

package/docs/workflow-validation.md

@@ -0,0 +1,184 @@
+# Workflow Validation
+
+This document describes the workflow validation system and how to use it.
+
+## Overview
+
+All workflow JSON files must pass JSON Schema validation before they can be loaded by the system. Invalid workflows are rejected with clear error messages.
+
+## Validation Layers
+
+### 1. **Runtime Validation (Non-Silent)**
+When the MCP server loads workflows, the `SchemaValidatingWorkflowStorage` validates each workflow against the schema. Invalid workflows are now **logged to console** with detailed error messages instead of being silently skipped.
+
+Example error:
+```
+[SchemaValidation] Workflow 'my-workflow' failed validation: 
+  /metaGuidance/19: must NOT have more than 256 characters
+```
+
+### 2. **CLI Validation**
+Validate individual workflow files using the CLI:
+
+```bash
+# Validate a single workflow
+node dist/cli.js validate workflows/my-workflow.json
+
+# Or with npm
+workrail validate workflows/my-workflow.json
+```
+
+### 3. **Batch Validation**
+Validate all workflows at once:
+
+```bash
+# Via npm script
+npm run validate:workflows
+
+# Or directly
+bash scripts/validate-workflows.sh
+```
+
+This will check all `.json` files in the `workflows/` directory and report:
+- Which workflows passed
+- Which workflows failed (with detailed errors)
+- Overall success/failure status
+
+### 4. **Pre-Commit Hook**
+A git pre-commit hook automatically validates any workflow files you're about to commit.
+
+**Installation:**
+```bash
+# Automatic (runs on npm install)
+npm install
+
+# Manual
+bash scripts/setup-hooks.sh
+```
+
+**Behavior:**
+- Only runs when workflow files (`.json` in `workflows/`) are being committed
+- Validates each changed workflow file
+- **Blocks the commit** if any workflow is invalid
+- Provides detailed error messages
+
+**Skip the hook (not recommended):**
+```bash
+git commit --no-verify
+```
+
+### 5. **CI/CD Pipeline (GitHub Actions)**
+The `.github/workflows/validate-workflows.yml` workflow automatically runs on:
+- Pushes to `main` or `develop` branches
+- Pull requests targeting `main` or `develop`
+- Only when workflow files or the schema changes
+
+**What it does:**
+- Installs dependencies
+- Builds the project
+- Validates all workflow files
+- Fails the CI build if any workflow is invalid
+
+## Common Validation Errors
+
+### 1. **String Too Long**
+```
+/metaGuidance/19: must NOT have more than 256 characters
+```
+**Fix:** Shorten the string or split it into multiple items.
+
+### 2. **Missing Required Field**
+```
+Missing required field 'steps' at root level
+```
+**Fix:** Add the required field to your workflow.
+
+### 3. **Invalid ID Format**
+```
+/id: must match pattern "^[a-z0-9-]+$"
+```
+**Fix:** Use only lowercase letters, numbers, and hyphens in workflow IDs.
+
+### 4. **Invalid Step Structure**
+```
+/steps/0: must have required property 'prompt'
+```
+**Fix:** Ensure all steps have required fields (id, title, prompt).
+
+## Best Practices
+
+1. **Validate Early**: Run `npm run validate:workflows` before committing
+2. **Check CI**: Monitor GitHub Actions to catch validation issues
+3. **Never Skip Hooks**: Use `--no-verify` only in emergencies
+4. **Keep Strings Short**: metaGuidance and other string fields have 256-char limits
+5. **Test Locally**: Use the CLI to validate before pushing
+
+## Troubleshooting
+
+### Hook Not Running
+```bash
+# Reinstall hooks
+bash scripts/setup-hooks.sh
+
+# Verify hook exists
+ls -la .git/hooks/pre-commit
+```
+
+### Validation Script Fails
+```bash
+# Rebuild the project first
+npm run build
+
+# Then try again
+npm run validate:workflows
+```
+
+### Silent Failures (Old Behavior)
+If workflows are being silently rejected:
+1. Check the MCP server console logs for `[SchemaValidation]` errors
+2. Run `npm run validate:workflows` to see all validation errors
+3. Update to the latest version with non-silent validation
+
+## Schema Location
+
+The workflow schema is located at:
+```
+spec/workflow.schema.json
+```
+
+To view the complete schema:
+```bash
+cat spec/workflow.schema.json
+```
+
+Or get it programmatically:
+```bash
+workrail get-schema
+```
+
+## Workflow Development Workflow
+
+Recommended workflow for creating/modifying workflows:
+
+1. **Edit** your workflow JSON file
+2. **Validate** locally: `npm run validate:workflows`
+3. **Test** by loading it in the MCP server
+4. **Commit** (hook will validate again)
+5. **Push** and check CI
+
+This multi-layer validation ensures invalid workflows never reach production.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+