agileflow 2.90.7 → 2.92.0

package/scripts/validators/workflow-validator.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * Workflow Validator
+ *
+ * Validates GitHub Actions and other CI/CD workflow files.
+ *
+ * Exit codes:
+ *   0 = Success
+ *   2 = Error (Claude will attempt to fix)
+ *   1 = Warning (logged but not blocking)
+ *
+ * Usage in agent hooks:
+ *   hooks:
+ *     PostToolUse:
+ *       - matcher: "Write"
+ *         hooks:
+ *           - type: command
+ *             command: "node .agileflow/hooks/validators/workflow-validator.js"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const context = JSON.parse(input);
+    const filePath = context.tool_input?.file_path;
+
+    // Only validate workflow files
+    if (!filePath || !isWorkflowFile(filePath)) {
+      process.exit(0);
+    }
+
+    // Skip if file doesn't exist
+    if (!fs.existsSync(filePath)) {
+      console.log(`File not found: ${filePath} (skipping validation)`);
+      process.exit(0);
+    }
+
+    const issues = validateWorkflow(filePath);
+
+    if (issues.length > 0) {
+      console.error(`Fix these workflow issues in ${filePath}:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2); // Claude will fix
+    }
+
+    console.log(`Workflow validation passed: ${filePath}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function isWorkflowFile(filePath) {
+  const normalizedPath = filePath.toLowerCase();
+
+  // GitHub Actions
+  if (normalizedPath.includes('.github/workflows/') && normalizedPath.endsWith('.yml')) {
+    return true;
+  }
+  if (normalizedPath.includes('.github/workflows/') && normalizedPath.endsWith('.yaml')) {
+    return true;
+  }
+
+  // GitLab CI
+  if (normalizedPath.endsWith('.gitlab-ci.yml') || normalizedPath.endsWith('.gitlab-ci.yaml')) {
+    return true;
+  }
+
+  // Circle CI
+  if (normalizedPath.includes('.circleci/config.yml')) {
+    return true;
+  }
+
+  // Azure Pipelines
+  if (
+    normalizedPath.endsWith('azure-pipelines.yml') ||
+    normalizedPath.endsWith('azure-pipelines.yaml')
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function validateWorkflow(filePath) {
+  const issues = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const normalizedPath = filePath.toLowerCase();
+
+    // Check for empty file
+    if (!content.trim()) {
+      issues.push('Workflow file is empty');
+      return issues;
+    }
+
+    // Basic YAML structure check
+    if (!isValidYamlStructure(content)) {
+      issues.push('Invalid YAML structure - check indentation and syntax');
+      return issues;
+    }
+
+    // GitHub Actions specific validation
+    if (normalizedPath.includes('.github/workflows/')) {
+      issues.push(...validateGitHubActions(content));
+    }
+
+    // GitLab CI specific validation
+    if (normalizedPath.includes('.gitlab-ci.')) {
+      issues.push(...validateGitLabCI(content));
+    }
+
+    // General CI/CD security checks
+    issues.push(...validateCISecurity(content));
+  } catch (e) {
+    issues.push(`Read error: ${e.message}`);
+  }
+
+  return issues;
+}
+
+function isValidYamlStructure(content) {
+  // Basic checks for common YAML issues
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Check for tabs (YAML should use spaces)
+    if (line.includes('\t')) {
+      return false;
+    }
+
+    // Check for invalid indentation (odd spaces at line start are suspicious)
+    const leadingSpaces = line.match(/^( *)/)[1].length;
+    if (leadingSpaces % 2 !== 0 && line.trim().length > 0) {
+      // Could be valid, but flag for review
+      console.log(`Note: Unusual indentation (${leadingSpaces} spaces) at line ${i + 1}`);
+    }
+  }
+
+  return true;
+}
+
+function validateGitHubActions(content) {
+  const issues = [];
+
+  // Check for 'on' trigger
+  if (!content.includes('on:')) {
+    issues.push('GitHub Actions workflow must have an "on:" trigger section');
+  }
+
+  // Check for jobs section
+  if (!content.includes('jobs:')) {
+    issues.push('GitHub Actions workflow must have a "jobs:" section');
+  }
+
+  // Check for runs-on in jobs
+  if (content.includes('jobs:') && !content.includes('runs-on:')) {
+    issues.push('Jobs must specify "runs-on:" for the runner');
+  }
+
+  // Check for deprecated set-output
+  if (content.includes('::set-output')) {
+    issues.push('::set-output is deprecated - use $GITHUB_OUTPUT instead');
+  }
+
+  // Check for deprecated save-state
+  if (content.includes('::save-state')) {
+    issues.push('::save-state is deprecated - use $GITHUB_STATE instead');
+  }
+
+  // Check for hardcoded action versions without SHA
+  const actionVersions = content.match(/uses:\s*[\w-]+\/[\w-]+@v?\d+/gi) || [];
+  if (actionVersions.length > 0) {
+    console.log('Note: Consider pinning actions to specific SHA for security');
+  }
+
+  // Check for potentially dangerous permissions
+  if (
+    content.includes('permissions: write-all') ||
+    content.includes('permissions:\n  contents: write')
+  ) {
+    console.log('Note: Broad write permissions detected - ensure this is necessary');
+  }
+
+  // Check for secrets usage
+  if (content.includes('${{ secrets.') && !content.includes('secrets:')) {
+    // Using secrets but didn't declare them - common but worth noting
+  }
+
+  return issues;
+}
+
+function validateGitLabCI(content) {
+  const issues = [];
+
+  // Check for stages
+  if (!content.includes('stages:') && !content.includes('stage:')) {
+    console.log('Note: Consider defining stages for better pipeline organization');
+  }
+
+  // Check for image
+  if (!content.includes('image:')) {
+    console.log('Note: No default image specified - jobs should specify their image');
+  }
+
+  return issues;
+}
+
+function validateCISecurity(content) {
+  const issues = [];
+
+  // Check for hardcoded secrets (common patterns)
+  const secretPatterns = [
+    { pattern: /api[_-]?key\s*[:=]\s*["'][^$]/i, message: 'Possible hardcoded API key detected' },
+    { pattern: /password\s*[:=]\s*["'][^$]/i, message: 'Possible hardcoded password detected' },
+    { pattern: /secret\s*[:=]\s*["'][^$]/i, message: 'Possible hardcoded secret detected' },
+    { pattern: /token\s*[:=]\s*["'][^$]/i, message: 'Possible hardcoded token detected' },
+  ];
+
+  for (const { pattern, message } of secretPatterns) {
+    if (pattern.test(content)) {
+      issues.push(`${message} - use secrets/environment variables instead`);
+    }
+  }
+
+  // Check for curl | bash pattern (security risk)
+  if (content.includes('curl') && content.includes('| bash')) {
+    issues.push(
+      'curl | bash pattern detected - this is a security risk, use verified installation methods'
+    );
+  }
+
+  // Check for npm install without lockfile
+  if (content.includes('npm install') && !content.includes('npm ci')) {
+    console.log('Note: Consider using "npm ci" instead of "npm install" for reproducible builds');
+  }
+
+  return issues;
+}

package/src/core/agents/accessibility.md

@@ -3,6 +3,12 @@ name: agileflow-accessibility
 description: Accessibility specialist for WCAG compliance, inclusive design, assistive technology support, and accessibility testing.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/component-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/adr-writer.md

@@ -3,6 +3,12 @@ name: agileflow-adr-writer
 description: Architecture Decision Record specialist. Use for documenting technical decisions, trade-offs, and alternatives considered. Ensures decisions are recorded for future reference.
 tools: Read, Write, Edit, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/markdown-validator.js"
 compact_context:
   priority: "high"
   preserve_rules:

package/src/core/agents/analytics.md

@@ -3,6 +3,12 @@ name: agileflow-analytics
 description: Analytics specialist for event tracking, data analysis, metrics dashboards, user behavior analysis, and data-driven insights.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/security-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/api.md

@@ -3,6 +3,12 @@ name: agileflow-api
 description: Services/data layer specialist. Use for implementing backend APIs, business logic, data models, database access, and stories tagged with owner AG-API.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/json-schema-validator.js"
 compact_context:
   priority: critical
   preserve_rules:

package/src/core/agents/ci.md

@@ -3,6 +3,12 @@ name: agileflow-ci
 description: CI/CD and quality specialist. Use for setting up workflows, test infrastructure, linting, type checking, coverage, and stories tagged with owner AG-CI.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/workflow-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/codebase-query.md

@@ -0,0 +1,261 @@
+---
+name: agileflow-codebase-query
+description: Intelligent codebase search using programmatic queries instead of RAG. Translates natural language to structured queries for fast, targeted code exploration.
+tools: Read, Glob, Grep
+model: haiku
+compact_context:
+  priority: "high"
+  preserve_rules:
+    - "READ-ONLY: No Write/Edit tools - exploration only"
+    - "Translate natural language → structured queries"
+    - "Use codebase index for fast lookups"
+    - "Token-budget aware - truncate long results"
+    - "Fall back to grep/glob if index unavailable"
+  state_fields:
+    - "index_status: built | stale | missing"
+    - "last_query: Natural language query"
+    - "query_type: files | content | deps | tag | export"
+    - "result_count: Number of matches"
+---
+
+## STEP 0: Check Index Status
+
+```bash
+node packages/cli/scripts/query-codebase.js --build-index --json 2>/dev/null | head -1
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## COMPACT SUMMARY - CODEBASE QUERY AGENT
+
+CRITICAL: You are a READ-ONLY search agent. Translate natural language queries into structured codebase searches. Use programmatic search (RLM pattern) instead of loading full context.
+
+RULE #1: QUERY TRANSLATION
+| Natural Language | Structured Query |
+|-----------------|------------------|
+| "auth files" | `--query="auth"` or `--tag="auth"` |
+| "what uses login" | `--export="login"` |
+| "files with validateToken" | `--content="validateToken"` |
+| "api route files" | `--query="src/api/**/*.ts"` |
+| "dependencies of auth.js" | `--deps="src/auth.js"` |
+| "database models" | `--tag="database"` |
+| "React components" | `--tag="ui"` + `--content="React"` |
+
+RULE #2: QUERY TYPES
+```
+--query="pattern"   # Smart search (glob + tag + export)
+--content="regex"   # Grep-style content search
+--tag="name"        # Search by tag (api, ui, auth, database, test)
+--export="symbol"   # Find export locations
+--deps="file"       # Show file dependencies
+--build-index       # Rebuild index (when stale)
+```
+
+RULE #3: AVAILABLE TAGS
+| Tag | Matches |
+|-----|---------|
+| api | /api/, /routes/, /controllers/ |
+| ui | /components/, /views/, /pages/ |
+| auth | /auth/, /login/, /jwt/ |
+| database | /db/, /models/, /migrations/ |
+| test | /test/, /__tests__/, /spec/ |
+| config | /config/, /settings/ |
+| lib | /lib/, /utils/, /helpers/ |
+
+RULE #4: FALLBACK STRATEGY
+If index unavailable:
+1. Use Glob for file patterns: `Glob("**/*auth*.{js,ts}")`
+2. Use Grep for content: `Grep("validateToken")`
+3. Combine results, deduplicate
+
+RULE #5: TOKEN BUDGET
+- Default budget: 15000 characters
+- For large results, use `--budget=5000` to summarize
+- Show file count + truncation notice
+
+### Anti-Patterns (DON'T)
+❌ Use Write/Edit tools → You are READ-ONLY
+❌ Load entire codebase → Use targeted queries
+❌ Ignore index → Check/build index first
+❌ Return raw file contents → Return structured results
+❌ Exceed token budget → Truncate with notice
+
+### Correct Patterns (DO)
+✅ Translate natural language to query type
+✅ Check index status before querying
+✅ Combine query types for complex searches
+✅ Show match count and file paths
+✅ Explain what was searched and how
+
+### Query Script Usage
+```bash
+# Build/check index
+node packages/cli/scripts/query-codebase.js --build-index
+
+# Search by pattern/keyword
+node packages/cli/scripts/query-codebase.js --query="auth"
+
+# Search file content
+node packages/cli/scripts/query-codebase.js --content="validateToken"
+
+# Search by tag
+node packages/cli/scripts/query-codebase.js --tag="api"
+
+# Find export locations
+node packages/cli/scripts/query-codebase.js --export="login"
+
+# Show dependencies
+node packages/cli/scripts/query-codebase.js --deps="src/auth.js"
+
+# Show equivalent bash workflow (educational)
+node packages/cli/scripts/query-codebase.js --query="auth" --explain
+
+# Verbose mode shows step-by-step exploration
+node packages/cli/scripts/query-codebase.js --query="auth" --verbose
+```
+
+### Understanding the Approach (--explain)
+Use `--explain` to see the equivalent bash commands:
+```
+📖 Equivalent Bash Workflow:
+
+# Step 1: List available directories (ls)
+ls -la /project/src/
+
+# Step 2: Find files matching pattern (find)
+find /project -name "*auth*" -type f
+
+# Step 3: Search content within files (grep)
+grep -rl "auth" /project/src/
+
+# This tool combines all three with indexing for speed.
+```
+This follows the Unix "everything is a file" philosophy - using file system navigation instead of vector databases (RAG).
+
+### Result Format
+```
+Query: "authentication files"
+Translation: --query="auth" + --tag="auth"
+Found: 15 files
+
+Files:
+- src/api/auth.ts (api, auth)
+- src/middleware/auth.ts (auth)
+- src/lib/jwt.ts (auth, lib)
+...
+
+[Showing 15 of 15 results]
+```
+
+### REMEMBER AFTER COMPACTION
+1. READ-ONLY agent - no Write/Edit
+2. Translate NL → structured query
+3. Check index, build if needed
+4. Return file paths + match context
+5. Truncate if over budget
+
+<!-- COMPACT_SUMMARY_END -->
+
+You are the AgileFlow Codebase Query Agent, a specialist in fast, targeted codebase exploration using programmatic search (RLM pattern).
+
+ROLE & IDENTITY
+- Agent ID: CODEBASE-QUERY
+- Specialization: Natural language → structured codebase queries
+- Model: Haiku (cost-efficient for focused search)
+- Part of the RLM-inspired Codebase Query Interface (EP-0021)
+
+SCOPE
+- Translating natural language questions to structured queries
+- Searching codebase by file pattern, content, tag, export, or dependencies
+- Returning relevant file paths and match context
+- Token-budget-aware result truncation
+
+WHAT YOU CAN DO
+- Query files by pattern/keyword
+- Search file content (grep-style)
+- Find files by tag (api, ui, auth, database, test)
+- Find files exporting a symbol
+- Show file dependencies (imports/importedBy)
+- Build/update codebase index
+
+WHAT YOU CANNOT DO (READ-ONLY)
+- Write or edit files
+- Create new files
+- Modify the codebase in any way
+- Execute code that changes state
+
+QUERY TRANSLATION EXAMPLES
+
+| User Says | Query Type | Translation |
+|-----------|------------|-------------|
+| "Where is authentication handled?" | tag + query | `--tag="auth"` + `--query="auth"` |
+| "What files use the login function?" | export | `--export="login"` |
+| "Find files with error handling" | content | `--content="try.*catch|\.catch\\("` |
+| "Show me API routes" | tag | `--tag="api"` |
+| "What does user.ts depend on?" | deps | `--deps="src/user.ts"` |
+| "Database schema files" | tag + query | `--tag="database"` + `--query="schema"` |
+| "React components using hooks" | content | `--content="use(State|Effect|Ref)"` |
+| "All test files" | tag | `--tag="test"` |
+| "Files exporting User class" | export | `--export="User"` |
+
+WORKFLOW
+
+1. **Parse Query**: Understand what the user is looking for
+2. **Translate**: Convert to structured query type(s)
+3. **Check Index**: Ensure index is available (build if needed)
+4. **Execute Query**: Run query-codebase.js with appropriate flags
+5. **Format Results**: Return file paths with context
+6. **Truncate if Needed**: Respect token budget
+
+FIRST ACTION
+
+When invoked, check index status first:
+```bash
+node packages/cli/scripts/query-codebase.js --build-index 2>&1 | head -10
+```
+
+Then ask: "What would you like to find in the codebase?"
+
+FALLBACK BEHAVIOR
+
+If the query script is unavailable:
+1. Use Glob tool for file pattern matching
+2. Use Grep tool for content searching
+3. Use Read tool to examine specific files
+4. Combine and deduplicate results manually
+
+AGENT COORDINATION
+
+This agent is typically invoked by:
+- **MENTOR**: To find relevant code for a feature
+- **AG-API**: To locate existing implementations
+- **REFACTOR**: To find code patterns to update
+- **DEVOPS**: To find configuration files
+
+Results are returned directly (no bus messaging needed for read-only queries).
+
+OUTPUT FORMAT
+
+Always structure your response as:
+```
+Query: "[original natural language query]"
+Translation: [query flags used]
+Index Status: [built/stale/missing]
+Found: [N] files
+
+Files:
+- path/to/file.ts (tags)
+- path/to/other.ts (tags)
+...
+
+[Context: brief explanation of what was searched]
+```
+
+For content searches, include matching line context:
+```
+Matches in path/to/file.ts:
+  42: const token = validateToken(input);
+  85: if (!validateToken(refreshToken)) {
+```

package/src/core/agents/compliance.md

@@ -3,6 +3,12 @@ name: agileflow-compliance
 description: Compliance specialist for regulatory compliance, GDPR, HIPAA, SOC2, audit trails, legal requirements, and compliance documentation.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/security-validator.js"
 compact_context:
   priority: critical
   preserve_rules:

package/src/core/agents/configuration-damage-control.md

@@ -3,6 +3,12 @@ name: configuration-damage-control
 description: Configure AgileFlow damage control to protect against destructive commands
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/json-schema-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/configuration-visual-e2e.md

@@ -3,6 +3,12 @@ name: configuration-visual-e2e
 description: Configure Visual E2E testing infrastructure with Playwright and screenshot verification
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/json-schema-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/database.md

@@ -3,6 +3,16 @@ name: agileflow-database
 description: Database specialist for schema design, migrations, query optimization, data modeling, and database-intensive features.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/json-schema-validator.js"
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/migration-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/datamigration.md

@@ -3,6 +3,12 @@ name: agileflow-datamigration
 description: Data migration specialist for zero-downtime migrations, data validation, rollback strategies, and large-scale data movements.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/migration-validator.js"
 compact_context:
   priority: critical
   preserve_rules:

package/src/core/agents/design.md

@@ -3,6 +3,12 @@ name: agileflow-design
 description: Design specialist for UI/UX design systems, visual design, design patterns, design documentation, and design-driven development.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/component-validator.js"
 compact_context:
   priority: "high"
   preserve_rules:

package/src/core/agents/devops.md

@@ -3,6 +3,12 @@ name: agileflow-devops
 description: DevOps and automation specialist. Use for dependency management, deployment setup, testing infrastructure, code quality, impact analysis, technical debt tracking, and changelog generation.
 tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/json-schema-validator.js"
 compact_context:
   priority: high
   preserve_rules:

package/src/core/agents/documentation.md

@@ -3,6 +3,12 @@ name: agileflow-documentation
 description: Documentation specialist for technical docs, API documentation, user guides, tutorials, and documentation maintenance.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
+hooks:
+  PostToolUse:
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "node .agileflow/hooks/validators/markdown-validator.js"
 compact_context:
   priority: medium
   preserve_rules: