agentic-qe 3.10.9 → 3.11.1

package/.claude/commands/workflows/development.md

@@ -0,0 +1,78 @@
+# Development Workflow Coordination
+
+## Purpose
+Structure Claude Code's approach to complex development tasks for maximum efficiency.
+
+## Step-by-Step Coordination
+
+### 1. Initialize Development Framework
+```
+Tool: mcp__claude-flow__swarm_init
+Parameters: {"topology": "hierarchical", "maxAgents": 8, "strategy": "specialized"}
+```
+Creates hierarchical structure for organized, top-down development.
+
+### 2. Define Development Perspectives
+```
+Tool: mcp__claude-flow__agent_spawn
+Parameters: {
+  "type": "architect",
+  "name": "System Design",
+  "capabilities": ["api-design", "database-schema"]
+}
+```
+```
+Tool: mcp__claude-flow__agent_spawn
+Parameters: {
+  "type": "coder",
+  "name": "Implementation Focus",
+  "capabilities": ["nodejs", "typescript", "express"]
+}
+```
+```
+Tool: mcp__claude-flow__agent_spawn
+Parameters: {
+  "type": "tester",
+  "name": "Quality Assurance",
+  "capabilities": ["unit-testing", "integration-testing"]
+}
+```
+Sets up architectural and implementation thinking patterns.
+
+### 3. Coordinate Implementation
+```
+Tool: mcp__claude-flow__task_orchestrate
+Parameters: {
+  "task": "Build REST API with authentication",
+  "strategy": "parallel",
+  "priority": "high",
+  "dependencies": ["database setup", "auth system"]
+}
+```
+
+### 4. Monitor Progress
+```
+Tool: mcp__claude-flow__task_status
+Parameters: {"taskId": "api-build-task-123"}
+```
+
+## What Claude Code Actually Does
+1. Uses **Write** tool to create new files
+2. Uses **Edit/MultiEdit** tools for code modifications
+3. Uses **Bash** tool for testing and building
+4. Uses **TodoWrite** tool for task tracking
+5. Follows coordination patterns for systematic implementation
+
+Remember: All code is written by Claude Code using its native tools!
+
+## CLI Usage
+```bash
+# Start development workflow via CLI
+npx claude-flow workflow dev "REST API with auth"
+
+# Create custom workflow
+npx claude-flow workflow create --name "api-dev" --steps "design,implement,test,deploy"
+
+# Execute saved workflow
+npx claude-flow workflow execute api-dev
+```

package/.claude/commands/workflows/research.md

@@ -0,0 +1,63 @@
+# Research Workflow Coordination
+
+## Purpose
+Coordinate Claude Code's research activities for comprehensive, systematic exploration.
+
+## Step-by-Step Coordination
+
+### 1. Initialize Research Framework
+```
+Tool: mcp__claude-flow__swarm_init
+Parameters: {"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}
+```
+Creates a mesh topology for comprehensive exploration from multiple angles.
+
+### 2. Define Research Perspectives
+```
+Tool: mcp__claude-flow__agent_spawn
+Parameters: {"type": "researcher", "name": "Literature Review"}
+```
+```
+Tool: mcp__claude-flow__agent_spawn  
+Parameters: {"type": "analyst", "name": "Data Analysis"}
+```
+Sets up different analytical approaches for Claude Code to use.
+
+### 3. Execute Coordinated Research
+```
+Tool: mcp__claude-flow__task_orchestrate
+Parameters: {
+  "task": "Research modern web frameworks performance",
+  "strategy": "adaptive",
+  "priority": "medium"
+}
+```
+
+### 4. Store Research Findings
+```
+Tool: mcp__claude-flow__memory_usage
+Parameters: {
+  "action": "store",
+  "key": "research_findings",
+  "value": "framework performance analysis results",
+  "namespace": "research"
+}
+```
+
+## What Claude Code Actually Does
+1. Uses **WebSearch** tool for finding resources
+2. Uses **Read** tool for analyzing documentation
+3. Uses **Task** tool for parallel exploration
+4. Synthesizes findings using coordination patterns
+5. Stores insights in memory for future reference
+
+Remember: The swarm coordinates HOW Claude Code researches, not WHAT it finds.
+
+## CLI Usage
+```bash
+# Start research workflow via CLI
+npx claude-flow workflow research "modern web frameworks"
+
+# Export research workflow
+npx claude-flow workflow export research --format json
+```

package/.claude/commands/workflows/workflow-create.md

@@ -0,0 +1,25 @@
+# workflow-create
+
+Create reusable workflow templates.
+
+## Usage
+```bash
+npx claude-flow workflow create [options]
+```
+
+## Options
+- `--name <name>` - Workflow name
+- `--from-history` - Create from history
+- `--interactive` - Interactive creation
+
+## Examples
+```bash
+# Create workflow
+npx claude-flow workflow create --name "deploy-api"
+
+# From history
+npx claude-flow workflow create --name "test-suite" --from-history
+
+# Interactive mode
+npx claude-flow workflow create --interactive
+```

package/.claude/commands/workflows/workflow-execute.md

@@ -0,0 +1,25 @@
+# workflow-execute
+
+Execute saved workflows.
+
+## Usage
+```bash
+npx claude-flow workflow execute [options]
+```
+
+## Options
+- `--name <name>` - Workflow name
+- `--params <json>` - Workflow parameters
+- `--dry-run` - Preview execution
+
+## Examples
+```bash
+# Execute workflow
+npx claude-flow workflow execute --name "deploy-api"
+
+# With parameters
+npx claude-flow workflow execute --name "test-suite" --params '{"env": "staging"}'
+
+# Dry run
+npx claude-flow workflow execute --name "deploy-api" --dry-run
+```

package/.claude/commands/workflows/workflow-export.md

@@ -0,0 +1,25 @@
+# workflow-export
+
+Export workflows for sharing.
+
+## Usage
+```bash
+npx claude-flow workflow export [options]
+```
+
+## Options
+- `--name <name>` - Workflow to export
+- `--format <type>` - Export format
+- `--include-history` - Include execution history
+
+## Examples
+```bash
+# Export workflow
+npx claude-flow workflow export --name "deploy-api"
+
+# As YAML
+npx claude-flow workflow export --name "test-suite" --format yaml
+
+# With history
+npx claude-flow workflow export --name "deploy-api" --include-history
+```

package/.claude/helpers/auto-commit.sh

@@ -90,7 +90,7 @@ Automatic checkpoint created by Claude Code
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>" --quiet 2>/dev/null; then
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>" --quiet 2>/dev/null; then
         log "Created commit: $message"
 
         # Push if enabled

package/.claude/helpers/auto-memory-hook.mjs

@@ -31,6 +31,27 @@ const log = (msg) => console.log(`${CYAN}[AutoMemory] ${msg}${RESET}`);
 const success = (msg) => console.log(`${GREEN}[AutoMemory] ✓ ${msg}${RESET}`);
 const dim = (msg) => console.log(`  ${DIM}${msg}${RESET}`);
 
+const DEBUG = !!(process.env.RUFLO_DEBUG || process.env.DEBUG);
+
+// ── Graceful shutdown (FIX 3) ───────────────────────────────────────────────
+// Track the backend in use so a SIGTERM/SIGINT mid-run can still flush it
+// (the JSON backend persists; a SQLite-backed one closes/flushes WAL) instead
+// of leaving a half-written store or a stale lock behind.
+let activeBackend = null;
+let shuttingDown = false;
+function trackBackend(b) { activeBackend = b; return b; }
+async function gracefulExit(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  if (DEBUG) process.stderr.write(`[AutoMemory] received ${signal}, flushing backend before exit\n`);
+  try {
+    if (activeBackend && typeof activeBackend.shutdown === 'function') await activeBackend.shutdown();
+  } catch { /* best effort — never block exit on cleanup */ }
+  process.exit(0);
+}
+process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });
+process.on('SIGINT', () => { gracefulExit('SIGINT'); });
+
 // Ensure data dir
 if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
 
@@ -219,7 +240,7 @@ async function doImport() {
   }
 
   const config = readConfig();
-  const backend = new JsonFileBackend(STORE_PATH);
+  const backend = trackBackend(new JsonFileBackend(STORE_PATH));
   await backend.initialize();
 
   const bridgeConfig = {
@@ -272,7 +293,7 @@ async function doSync() {
   }
 
   const config = readConfig();
-  const backend = new JsonFileBackend(STORE_PATH);
+  const backend = trackBackend(new JsonFileBackend(STORE_PATH));
   await backend.initialize();
 
   const entryCount = await backend.count();
@@ -348,6 +369,18 @@ async function doStatus() {
 
 const command = process.argv[2] || 'status';
 
+// Dynamic import() failures can surface as unhandled rejections on a later
+// microtask even when the awaiting call site already caught them, which would
+// otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
+// reason under RUFLO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
+// (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
+process.on('unhandledRejection', (reason) => {
+  if (DEBUG) {
+    const detail = reason && reason.message ? reason.message : String(reason);
+    process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
+  }
+});
+
 try {
   switch (command) {
     case 'import': await doImport(); break;
@@ -361,5 +394,5 @@ try {
   // Hooks must never crash Claude Code - fail silently
   try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
 }
-// Hooks must ALWAYS exit 0
-process.exitCode = 0;
+// Force clean exit — process.exitCode alone isn't enough if async errors override it
+process.exit(0);

package/.claude/helpers/github-safe.js

@@ -1,25 +1,43 @@
 #!/usr/bin/env node
-
 /**
- * Safe GitHub CLI Helper
- * Prevents timeout issues when using gh commands with special characters
- * 
+ * Safe GitHub CLI Helper — v1.0.0
+ *
+ * Prevents injection issues when using `gh` commands with untrusted content
+ * (PR bodies, issue bodies, comment bodies) by routing the body through a
+ * temp file and using `--body-file` rather than interpolating into shell args.
+ *
+ * ADR-127 Phase 2 hardening:
+ *   - GITHUB_SAFE_VERSION exported for smoke assertions.
+ *   - Explicit 256KB body cap: rejects oversized bodies before any temp-file
+ *     write, matching the GitHub API `body` field limit.
+ *   - Strict error handling: all execSync calls inside try/catch; cleanup in
+ *     finally; non-zero exit on any error.
+ *   - GITHUB_SAFE_DRY_RUN=1 env-var skips the actual `gh` exec for testing.
+ *
  * Usage:
- *   ./github-safe.js issue comment 123 "Message with `backticks`"
+ *   ./github-safe.js issue comment 123 "Message with \`backticks\`"
  *   ./github-safe.js pr create --title "Title" --body "Complex body"
  */
 
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import { writeFileSync, unlinkSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { randomBytes } from 'crypto';
 
+// Version constant — asserted by smoke-github-safe-injection.mjs.
+export const GITHUB_SAFE_VERSION = '1.0.0';
+
+// Maximum body size allowed (bytes).  The GitHub API enforces 65536 chars for
+// issue/PR bodies; the CLI is more lenient but the 256KB limit is a
+// conservative safety cap that prevents accidental oversized writes.
+const MAX_BODY_BYTES = 256 * 1024;
+
 const args = process.argv.slice(2);
 
 if (args.length < 2) {
   console.log(`
-Safe GitHub CLI Helper
+Safe GitHub CLI Helper v${GITHUB_SAFE_VERSION}
 
 Usage:
   ./github-safe.js issue comment <number> <body>
@@ -27,11 +45,11 @@ Usage:
   ./github-safe.js issue create --title <title> --body <body>
   ./github-safe.js pr create --title <title> --body <body>
 
-This helper prevents timeout issues with special characters like:
+This helper prevents injection issues with special characters:
 - Backticks in code examples
-- Command substitution \$(...)
-- Directory paths
-- Special shell characters
+- Command substitution $(...)
+- Semicolons and other shell metacharacters
+- Oversized bodies (> 256 KB rejected)
 `);
   process.exit(1);
 }
@@ -39,68 +57,100 @@ This helper prevents timeout issues with special characters like:
 const [command, subcommand, ...restArgs] = args;
 
 // Handle commands that need body content
-if ((command === 'issue' || command === 'pr') && 
+if ((command === 'issue' || command === 'pr') &&
     (subcommand === 'comment' || subcommand === 'create')) {
-  
+
   let bodyIndex = -1;
   let body = '';
-  
+
   if (subcommand === 'comment' && restArgs.length >= 2) {
     // Simple format: github-safe.js issue comment 123 "body"
     body = restArgs[1];
     bodyIndex = 1;
   } else {
-    // Flag format: --body "content" 
+    // Flag format: --body "content"
     bodyIndex = restArgs.indexOf('--body');
     if (bodyIndex !== -1 && bodyIndex < restArgs.length - 1) {
       body = restArgs[bodyIndex + 1];
     }
   }
-  
+
   if (body) {
-    // Use temporary file for body content
+    // Enforce 256KB cap before any file I/O.
+    const bodyBytes = Buffer.byteLength(body, 'utf8');
+    if (bodyBytes > MAX_BODY_BYTES) {
+      console.error(
+        `[ERROR] Body exceeds maximum allowed size (${bodyBytes} bytes > ${MAX_BODY_BYTES} bytes). ` +
+        'GitHub API body fields are capped at 256KB. Truncate the body before passing it to github-safe.js.'
+      );
+      process.exit(1);
+    }
+
+    // Use temporary file for body content — never interpolate into argv.
     const tmpFile = join(tmpdir(), `gh-body-${randomBytes(8).toString('hex')}.tmp`);
-    
+
     try {
       writeFileSync(tmpFile, body, 'utf8');
-      
+
       // Build new command with --body-file
       const newArgs = [...restArgs];
       if (subcommand === 'comment' && bodyIndex === 1) {
-        // Replace body with --body-file
+        // Replace positional body arg with --body-file
         newArgs[1] = '--body-file';
         newArgs.push(tmpFile);
       } else if (bodyIndex !== -1) {
-        // Replace --body with --body-file
+        // Replace --body flag pair with --body-file
         newArgs[bodyIndex] = '--body-file';
         newArgs[bodyIndex + 1] = tmpFile;
       }
-      
-      // Execute safely
-      const ghCommand = `gh ${command} ${subcommand} ${newArgs.join(' ')}`;
-      console.log(`Executing: ${ghCommand}`);
-      
-      const result = execSync(ghCommand, { 
+
+      // Skip actual gh exec in dry-run mode (used by smoke tests).
+      if (process.env.GITHUB_SAFE_DRY_RUN === '1') {
+        const ghArgs = [command, subcommand, ...newArgs];
+        console.log(`[DRY-RUN] gh ${ghArgs.join(' ')}`);
+        process.exit(0);
+      }
+
+      const ghArgv = [command, subcommand, ...newArgs];
+      console.log(`Executing: gh ${ghArgv.join(' ')}`);
+
+      // Use execFileSync to avoid shell interpolation — args are passed as an
+      // array so shell metacharacters in tmpFile path cannot be exploited.
+      execFileSync('gh', ghArgv, {
         stdio: 'inherit',
-        timeout: 30000 // 30 second timeout
+        timeout: 30000,
       });
-      
+
     } catch (error) {
-      console.error('Error:', error.message);
+      console.error('[ERROR]', error.message);
       process.exit(1);
     } finally {
-      // Clean up
-      try {
-        unlinkSync(tmpFile);
-      } catch (e) {
-        // Ignore cleanup errors
-      }
+      // Always clean up the temp file.
+      try { unlinkSync(tmpFile); } catch (_) { /* ignore cleanup errors */ }
     }
   } else {
-    // No body content, execute normally
-    execSync(`gh ${args.join(' ')}`, { stdio: 'inherit' });
+    // No body content — execute normally (no injection risk for args).
+    if (process.env.GITHUB_SAFE_DRY_RUN === '1') {
+      console.log(`[DRY-RUN] gh ${args.join(' ')}`);
+      process.exit(0);
+    }
+    try {
+      execFileSync('gh', args, { stdio: 'inherit' });
+    } catch (error) {
+      console.error('[ERROR]', error.message);
+      process.exit(1);
+    }
   }
 } else {
-  // Other commands, execute normally
-  execSync(`gh ${args.join(' ')}`, { stdio: 'inherit' });
+  // Non-body commands — execute normally.
+  if (process.env.GITHUB_SAFE_DRY_RUN === '1') {
+    console.log(`[DRY-RUN] gh ${args.join(' ')}`);
+    process.exit(0);
+  }
+  try {
+    execFileSync('gh', args, { stdio: 'inherit' });
+  } catch (error) {
+    console.error('[ERROR]', error.message);
+    process.exit(1);
+  }
 }

package/.claude/helpers/github-setup.sh

@@ -1,28 +1,45 @@
 #!/bin/bash
+# Security rationale: set -euo pipefail ensures that:
+#   -e  — exit immediately if any command fails (no silent failures)
+#   -u  — treat unset variables as errors (prevents empty-string expansion bugs)
+#   -o pipefail — pipeline fails if any command in it fails (not just last)
+# This matches the ADR-127 Phase 2 requirement for github-setup.sh hardening.
+set -euo pipefail
+
 # Setup GitHub integration for Claude Flow
 
-echo "🔗 Setting up GitHub integration..."
+echo "Setting up GitHub integration..."
 
 # Check for gh CLI
 if ! command -v gh &> /dev/null; then
-    echo "⚠️  GitHub CLI (gh) not found"
+    echo "WARNING: GitHub CLI (gh) not found"
     echo "Install from: https://cli.github.com/"
     echo "Continuing without GitHub features..."
 else
-    echo "✅ GitHub CLI found"
-    
-    # Check auth status
-    if gh auth status &> /dev/null; then
-        echo "✅ GitHub authentication active"
+    echo "OK: GitHub CLI found"
+
+    # Check auth status and scope sufficiency.
+    # `gh auth status` exits non-zero when not authenticated.
+    # We additionally parse for "Token scopes" to verify we have at least
+    # 'repo' scope, which is required for PR/issue operations.
+    if gh auth status 2>&1 | grep -q "Logged in"; then
+        echo "OK: GitHub authentication active"
+        # Verify repo scope is present for PR/issue operations.
+        if gh auth status 2>&1 | grep -q "repo"; then
+            echo "OK: 'repo' scope available"
+        else
+            echo "WARNING: 'repo' scope not confirmed — PR/issue operations may fail"
+            echo "Run: gh auth login --scopes repo,read:org"
+        fi
     else
-        echo "⚠️  Not authenticated with GitHub"
+        echo "WARNING: Not authenticated with GitHub"
         echo "Run: gh auth login"
     fi
 fi
 
 echo ""
-echo "📦 GitHub swarm commands available:"
-echo "  - npx ruflo github swarm"
-echo "  - npx ruflo repo analyze"
-echo "  - npx ruflo pr enhance"
-echo "  - npx ruflo issue triage"
+echo "GitHub swarm commands available:"
+echo "  - npx claude-flow github swarm"
+echo "  - npx claude-flow repo analyze"
+echo "  - npx claude-flow pr enhance"
+echo "  - npx claude-flow issue triage"