agent-state-machine 2.4.0 → 2.6.0

package/templates/project-builder/agents/post-code-security.md

@@ -0,0 +1,55 @@
+---
+model: med
+format: json
+description: "Post-code phase: Audits implementation for security vulnerabilities"
+---
+
+# Post-Code Security Auditor Agent
+
+You are a security auditor. Review implemented code to identify security vulnerabilities and verify secure coding practices.
+
+## How to Audit
+
+**Use your file tools to read the files that need auditing.** You will receive a list of file paths. Read each file's contents directly from disk to perform your security audit.
+
+## Instructions
+
+Perform a post-implementation security audit:
+
+- Review the implementation for security issues
+- Check for common vulnerabilities (OWASP Top 10)
+- Verify secure coding practices
+- Identify any remaining security debt
+- Verify pre-code security recommendations were followed
+
+## Output Format
+
+Return a valid JSON object:
+
+{
+  "riskLevel": "low",
+  "findings": [
+    {
+      "type": "vulnerability",
+      "severity": "high",
+      "location": "src/auth.js:42",
+      "description": "User input not sanitized before database query",
+      "recommendation": "Use parameterized query instead"
+    }
+  ],
+  "checklistResults": [
+    {"item": "Input validation implemented", "status": "passed"},
+    {"item": "SQL injection prevented", "status": "passed"},
+    {"item": "Authentication tokens secured", "status": "failed"}
+  ],
+  "securityDebt": [
+    "Consider adding rate limiting in future iteration"
+  ],
+  "approved": true,
+  "blockers": []
+}
+
+**Severity levels:** critical, high, medium, low, info
+**Status values:** passed, failed, na
+
+Critical and high severity findings should set approved: false and be listed in blockers.

package/templates/project-builder/agents/{security-reviewer.md → pre-code-security.md}

@@ -1,34 +1,27 @@
 ---
 model: med
 format: json
+description: "Pre-code phase: Analyzes security risks before implementation starts"
 ---
 
-# Security Reviewer Agent
+# Pre-Code Security Reviewer Agent
 
-You are a security review specialist. Review tasks and implementations for security concerns.
+You are a security threat analyst. Analyze tasks BEFORE implementation to identify security risks and recommend secure patterns.
 
 ## Instructions
 
-Perform a security review appropriate to the stage:
+Perform a pre-implementation security analysis:
 
-**Pre-Implementation Review (stage: pre-implementation):**
 - Identify potential security concerns for the task
 - Recommend secure implementation patterns
 - Flag any high-risk areas requiring extra attention
 - Suggest security tests to include
 
-**Post-Implementation Review (stage: post-implementation):**
-- Review the implementation for security issues
-- Check for common vulnerabilities (OWASP Top 10)
-- Verify secure coding practices
-- Identify any remaining security debt
-
 ## Output Format
 
 Return a valid JSON object:
 
 {
-  "stage": "pre-implementation",
   "riskLevel": "low",
   "findings": [
     {
@@ -43,6 +36,10 @@ Return a valid JSON object:
     {"item": "Use parameterized queries", "status": "pending"},
     {"item": "Implement rate limiting", "status": "na"}
   ],
+  "suggestedTests": [
+    "Test for SQL injection with malicious input",
+    "Verify authentication token validation"
+  ],
   "approved": true,
   "blockers": []
 }

package/templates/project-builder/agents/{test-planner.md → pre-code-tests.md}

@@ -1,6 +1,7 @@
 ---
 model: med
 format: json
+description: "Pre-code phase: Creates test plan before implementation begins"
 ---
 
 # Test Planner Agent

package/templates/project-builder/agents/response-interpreter.md

@@ -1,6 +1,7 @@
 ---
 model: fast
 format: json
+description: "Utility: Parses natural language user responses into structured data"
 ---
 
 You are interpreting a user's natural language response against a structured interaction schema.

package/templates/project-builder/agents/verify-commit-msg.md

@@ -0,0 +1,64 @@
+---
+model: fast
+format: json
+description: "Verify phase: Generates conventional commit message after task completion"
+---
+
+# Commit Message Generator Agent
+
+You generate conventional commit messages for completed tasks.
+
+## Input
+- task: { title, description }
+- filesWritten: Array of { path, purpose } for files created/modified
+
+## Output Format
+
+Return a valid JSON object:
+
+{
+  "type": "feat",
+  "scope": "auth",
+  "message": "add user login functionality",
+  "body": "Implements login form with email/password validation.\nAdds JWT token storage and refresh logic."
+}
+
+## Commit Type Guidelines
+
+- **feat**: New feature for the user
+- **fix**: Bug fix for the user
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **test**: Adding or updating tests
+- **docs**: Documentation only changes
+- **style**: Formatting, missing semicolons, etc (no code change)
+- **chore**: Updating build tasks, configs, etc
+
+## Message Guidelines
+
+- Use imperative mood ("add" not "added" or "adds")
+- Keep first line under 72 characters
+- Scope is optional but recommended (component/module name)
+- Body should explain what and why, not how
+- Reference file changes in body when helpful
+
+## Examples
+
+Task: "Implement user authentication"
+Files: [{ path: "src/auth.js", purpose: "Auth module" }]
+Output:
+{
+  "type": "feat",
+  "scope": "auth",
+  "message": "implement user authentication",
+  "body": "Adds login/logout functionality with JWT tokens.\n\nFiles:\n- src/auth.js: Core auth module"
+}
+
+Task: "Fix login validation bug"
+Files: [{ path: "src/auth.js", purpose: "Fix validation" }]
+Output:
+{
+  "type": "fix",
+  "scope": "auth",
+  "message": "correct email validation regex",
+  "body": "Email validation was rejecting valid addresses with + symbols."
+}

package/templates/project-builder/agents/{sanity-checker.md → verify-sanity.md}

@@ -1,6 +1,7 @@
 ---
 model: fast
 format: json
+description: "Verify phase: Generates executable sanity checks to validate implementation"
 ---
 
 You generate executable sanity checks for the implemented task.
@@ -37,15 +38,3 @@ Guidelines:
 - Include at least one file_exists or file_contains check when files are created/modified.
 - If tests exist (from testPlan or implementation), include a type "test_suite" check.
 - Use testFramework.command for running tests (optionally target specific files when possible).
-
-Task:
-{{task}}
-
-Implementation:
-{{implementation}}
-
-Test Plan:
-{{testPlan}}
-
-Test Framework:
-{{testFramework}}

package/templates/project-builder/config.js

@@ -1,9 +1,9 @@
 export const config = {
   models: {
-    fast: "gemini -m gemini-2.5-pro",
-    low: "gemini -m gemini-2.5-pro",
-    med: "gemini -m gemini-2.5-pro",
-    high: "gemini -m gemini-2.5-pro",
+    fast: "gemini-2.5-flash",
+    low: "gemini-2.5-flash",
+    med: "gemini-2.5-flash",
+    high: "gemini-2.5-flash",
   },
   apiKeys: {
     gemini: process.env.GEMINI_API_KEY,
@@ -11,6 +11,17 @@ export const config = {
     openai: process.env.OPENAI_API_KEY,
   },
 
+  // CLI permission modes - enables native file access for agents
+  cliPermissions: {
+    claude: 'bypassPermissions',  // --permission-mode bypassPermissions
+    gemini: 'full',               // --approval-mode full
+    codex: 'bypass'               // --dangerously-bypass-approvals-and-sandbox
+  },
+
+  // Protected paths - prevents DELETION only (modifications allowed)
+  // Files matching these patterns cannot be deleted by agents
+  protectedPaths: ['.env', '.env.*', 'package.json'],
+
   // File tracking (all optional - shown with defaults)
   // projectRoot: process.env.PROJECT_ROOT,  // Defaults to ../.. from workflow
   // fileTracking: true,                     // Enable/disable file tracking

package/templates/project-builder/scripts/safeguard-recovery.js

@@ -0,0 +1,40 @@
+import { execSync } from 'child_process';
+
+/**
+ * Try to auto-fix common validation issues
+ * @param {string} projectRoot - Project root directory
+ * @param {string[]} violations - Array of violation messages
+ * @returns {string[]} Array of fixes applied
+ */
+export function autoFixValidationIssues(projectRoot, violations) {
+  const fixed = [];
+
+  for (const violation of violations) {
+    if (violation.includes('agent-state-machine')) {
+      // Re-install the dependency
+      try {
+        execSync('npm install agent-state-machine', { cwd: projectRoot, stdio: 'pipe' });
+        fixed.push('Reinstalled agent-state-machine');
+      } catch (e) {
+        // Will fall through to rollback
+      }
+    }
+  }
+
+  return fixed;
+}
+
+/**
+ * Rollback a file using git checkout
+ * @param {string} projectRoot - Project root directory
+ * @param {string} filePath - File path to rollback (relative to projectRoot)
+ * @returns {{ success: boolean, error?: string }}
+ */
+export function rollbackFile(projectRoot, filePath) {
+  try {
+    execSync(`git checkout -- "${filePath}"`, { cwd: projectRoot, stdio: 'pipe' });
+    return { success: true };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}

package/templates/project-builder/scripts/validate-changes.js

@@ -0,0 +1,61 @@
+/**
+ * File: /templates/project-builder/scripts/validate-changes.js
+ *
+ * Project-builder specific validation for file changes.
+ * Checks constraints that are specific to this workflow template.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Validate project-builder specific constraints after file changes.
+ * - package.json: agent-state-machine dependency must not be removed
+ * - Additions and other modifications are allowed
+ *
+ * @param {string} projectRoot - The project root directory
+ * @param {Object} changes - Detected changes { created, modified, deleted, renamed }
+ * @returns {{ valid: boolean, violations: string[] }}
+ */
+export function validateProjectChanges(projectRoot, changes) {
+  const violations = [];
+
+  // Check package.json modifications (not deletions - that's handled by core protectedPaths)
+  if ((changes.modified || []).includes('package.json')) {
+    const pkgPath = path.resolve(projectRoot, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const content = fs.readFileSync(pkgPath, 'utf-8');
+        // Only flag if agent-state-machine was removed entirely
+        // This allows adding/updating other dependencies
+        if (!content.includes('agent-state-machine')) {
+          violations.push('package.json: agent-state-machine dependency was removed (not allowed)');
+        }
+      } catch (err) {
+        console.warn(`[validate-changes] Failed to read package.json: ${err.message}`);
+      }
+    }
+  }
+
+  return { valid: violations.length === 0, violations };
+}
+
+/**
+ * Check if package.json still has agent-state-machine dependency.
+ * Utility for checking after any file write operation.
+ *
+ * @param {string} projectRoot - The project root directory
+ * @returns {boolean} - True if dependency is present
+ */
+export function hasAgentStateMachine(projectRoot) {
+  const pkgPath = path.resolve(projectRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return false;
+  }
+  try {
+    const content = fs.readFileSync(pkgPath, 'utf-8');
+    return content.includes('agent-state-machine');
+  } catch {
+    return false;
+  }
+}

package/templates/project-builder/scripts/workflow-helpers.js

@@ -1,40 +1,8 @@
 import fs from 'fs';
 import path from 'path';
+import { execSync } from 'child_process';
 import { memory, getCurrentRuntime } from 'agent-state-machine';
 
-// Write implementation files from code-writer agent output
-function writeImplementationFiles(implementation) {
-  const runtime = getCurrentRuntime();
-  if (!runtime) {
-    throw new Error('writeImplementationFiles must be called within a workflow context');
-  }
-
-  const projectRoot = runtime.workflowConfig.projectRoot;
-  const files = implementation?.implementation?.files || implementation?.files || [];
-  const written = [];
-
-  for (const file of files) {
-    if (!file.path || !file.code) {
-      console.warn(`  [File] Skipping invalid file entry: ${JSON.stringify(file)}`);
-      continue;
-    }
-
-    const fullPath = path.resolve(projectRoot, file.path);
-
-    // Ensure directory exists
-    const dir = path.dirname(fullPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-
-    fs.writeFileSync(fullPath, file.code);
-    written.push(file.path);
-    console.log(`  [File] Created: ${file.path}`);
-  }
-
-  return written;
-}
-
 // Write markdown file to workflow state directory
 function writeMarkdownFile(stateDir, filename, content) {
   if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
@@ -205,9 +173,90 @@ function detectTestFramework() {
   return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
 }
 
+// Git-based file awareness helpers
+
+/**
+ * Get list of all tracked files in the project
+ * @param {string} projectRoot - Project root directory
+ * @returns {string[]} Array of file paths
+ */
+function getProjectFiles(projectRoot) {
+  try {
+    const stdout = execSync('git ls-files', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    });
+    return stdout.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Create a git commit with the specified message
+ * @param {string} projectRoot - Project root directory
+ * @param {string} message - Commit message (can be multi-line)
+ * @param {string[]} files - Optional specific files to stage (stages all if empty)
+ * @returns {{ success: boolean, hash?: string, error?: string }}
+ */
+function createGitCommit(projectRoot, message, files = []) {
+  try {
+    // Stage files
+    if (files.length > 0) {
+      // Quote file paths to handle spaces
+      const quotedFiles = files.map(f => `"${f}"`).join(' ');
+      execSync(`git add ${quotedFiles}`, { cwd: projectRoot, stdio: 'pipe' });
+    } else {
+      execSync('git add -A', { cwd: projectRoot, stdio: 'pipe' });
+    }
+
+    // Check if there are staged changes
+    const status = execSync('git diff --cached --name-only', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    }).trim();
+
+    if (!status) {
+      return { success: false, error: 'No changes to commit' };
+    }
+
+    // Commit using stdin to avoid shell escaping issues
+    execSync('git commit -F -', {
+      cwd: projectRoot,
+      input: message,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    // Get commit hash
+    const hash = execSync('git rev-parse --short HEAD', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    }).trim();
+
+    return { success: true, hash };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Ensure a git repository exists at the project root
+ * @param {string} projectRoot - Project root directory
+ * @returns {{ initialized: boolean, message: string }}
+ */
+function ensureGitRepo(projectRoot) {
+  try {
+    execSync('git rev-parse --git-dir', { cwd: projectRoot, stdio: 'pipe' });
+    return { initialized: false, message: 'Git repo already exists' };
+  } catch {
+    // Not a git repo, initialize it
+    execSync('git init', { cwd: projectRoot, stdio: 'pipe' });
+    return { initialized: true, message: 'Git repo initialized' };
+  }
+}
+
 export {
   writeMarkdownFile,
-  writeImplementationFiles,
   isApproval,
   renderRoadmapMarkdown,
   renderTasksMarkdown,
@@ -220,5 +269,8 @@ export {
   getQuickFixAttempts,
   incrementQuickFixAttempts,
   resetQuickFixAttempts,
-  detectTestFramework
+  detectTestFramework,
+  getProjectFiles,
+  createGitCommit,
+  ensureGitRepo
 };