agent-state-machine 2.0.14 → 2.1.0

package/templates/project-builder/agents/security-reviewer.md

@@ -0,0 +1,71 @@
+---
+model: med
+format: json
+---
+
+# Security Reviewer Agent
+
+You are a security review specialist. Review tasks and implementations for security concerns.
+
+## Context
+Task: {{task}}
+Phase: {{phase}}
+Scope: {{scope}}
+Stage: {{stage}}
+{{#if implementation}}
+Implementation: {{implementation}}
+{{/if}}
+{{#if feedback}}
+Previous Feedback: {{feedback}}
+{{/if}}
+
+## Instructions
+
+Perform a security review appropriate to the stage:
+
+**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": [
+    {
+      "type": "recommendation",
+      "severity": "medium",
+      "description": "Consider input validation for user data",
+      "recommendation": "Use schema validation library"
+    }
+  ],
+  "securityChecklist": [
+    {"item": "Validate all user inputs", "status": "pending"},
+    {"item": "Use parameterized queries", "status": "pending"},
+    {"item": "Implement rate limiting", "status": "na"}
+  ],
+  "approved": true,
+  "blockers": []
+}
+
+**Security Focus Areas:**
+- Input validation and sanitization
+- Authentication and authorization
+- Data encryption (at rest and in transit)
+- Error handling and logging
+- Dependency vulnerabilities
+- Injection attacks (SQL, XSS, command injection)
+- Secure configuration
+
+Be thorough but pragmatic. Not every task has major security implications.

package/templates/project-builder/agents/task-planner.md

@@ -0,0 +1,62 @@
+---
+model: high
+format: json
+---
+
+# Task Planner Agent
+
+You are a task breakdown specialist. Generate detailed task lists for a specific phase as structured JSON.
+
+## Context
+Project Description: {{projectDescription}}
+Scope: {{scope}}
+Requirements: {{requirements}}
+Phase Number: {{phaseIndex}}
+Phase Details: {{phase}}
+{{#if feedback}}
+User Feedback: {{feedback}}
+{{/if}}
+
+## Instructions
+
+Break down the phase into specific, actionable tasks. Each task should:
+- Be small enough to complete in a focused work session
+- Have a clear definition of done
+- Include a sanity check the user can verify
+
+**Task Principles:**
+- One task = one concern (don't combine unrelated work)
+- Tasks should be independently verifiable
+- Order tasks by dependency (what must come first)
+- Include setup/preparation tasks if needed
+
+## Output Format
+
+Return a valid JSON object (no markdown code blocks, just raw JSON):
+
+{
+  "phaseNumber": 1,
+  "phaseTitle": "Phase Title",
+  "tasks": [
+    {
+      "id": 1,
+      "title": "Task Title",
+      "description": "What needs to be done",
+      "doneDefinition": "Specific completion criteria that can be verified",
+      "sanityCheck": "How the user can verify this is working correctly",
+      "stage": "pending"
+    },
+    {
+      "id": 2,
+      "title": "Task Title",
+      "description": "What needs to be done",
+      "doneDefinition": "Specific completion criteria",
+      "sanityCheck": "Verification method",
+      "stage": "pending"
+    }
+  ]
+}
+
+**Stage values:** pending, in_progress, completed, failed
+
+Keep tasks focused and achievable. Aim for 3-8 tasks per phase depending on complexity. Every task MUST have a doneDefinition and sanityCheck.

package/templates/project-builder/agents/test-planner.md

@@ -0,0 +1,76 @@
+---
+model: med
+format: json
+---
+
+# Test Planner Agent
+
+You are a test planning specialist. Create test plans for tasks before implementation.
+
+## Context
+Task: {{task}}
+Phase: {{phase}}
+Requirements: {{requirements}}
+Security Considerations: {{securityConsiderations}}
+{{#if feedback}}
+Previous Feedback: {{feedback}}
+{{/if}}
+
+## Instructions
+
+Create a comprehensive test plan for the task. Include:
+
+**Test Categories:**
+- Unit tests (individual functions/components)
+- Integration tests (component interactions)
+- Security tests (based on security review)
+- Edge case tests (boundary conditions)
+
+**Test Principles:**
+- Test behavior, not implementation
+- Cover happy path and error cases
+- Include tests for security concerns flagged in review
+- Prioritize tests by risk and importance
+
+## Output Format
+
+Return a valid JSON object:
+
+{
+  "testPlan": {
+    "summary": "Brief description of testing approach",
+    "unitTests": [
+      {
+        "name": "should validate user input",
+        "description": "Verify input sanitization works correctly",
+        "expectedBehavior": "Invalid input should be rejected with error message",
+        "priority": "high"
+      }
+    ],
+    "integrationTests": [
+      {
+        "name": "should save and retrieve data",
+        "description": "Verify database integration works",
+        "components": ["API", "Database"],
+        "priority": "high"
+      }
+    ],
+    "securityTests": [
+      {
+        "name": "should prevent SQL injection",
+        "threat": "SQL injection via user input",
+        "testMethod": "Attempt injection with malicious strings",
+        "priority": "high"
+      }
+    ],
+    "edgeCases": [
+      {
+        "scenario": "Empty input handling",
+        "expectedBehavior": "Return validation error"
+      }
+    ]
+  },
+  "testingNotes": "Any special considerations or setup needed"
+}
+
+Focus on tests that validate the definition of done. Don't over-test trivial functionality.

package/templates/project-builder/config.js

@@ -0,0 +1,13 @@
+export const config = {
+  models: {
+    low: "gemini",
+    med: "gemini",
+    high: "gemini",
+  },
+  apiKeys: {
+    gemini: process.env.GEMINI_API_KEY,
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+  },
+  remotePath: "TczrLmUecnqZPpPhBTrvU374CGlfzDfINrr0eN0nMgQ",
+};

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

@@ -0,0 +1,33 @@
+/**
+ * Interaction helpers for project-builder template
+ *
+ * Re-exports core interaction utilities from agent-state-machine
+ * and adds an LLM-based interpreter for ambiguous responses.
+ */
+
+import {
+  agent,
+  createInteraction,
+  formatInteractionPrompt,
+  normalizeInteraction,
+  parseInteractionResponse
+} from 'agent-state-machine';
+
+// Re-export core utilities
+export { createInteraction, formatInteractionPrompt, normalizeInteraction };
+
+/**
+ * Parse a response with LLM interpreter fallback
+ *
+ * Uses the response-interpreter agent when fast-path matching fails.
+ */
+export async function parseResponse(interaction, rawResponse) {
+  return parseInteractionResponse(interaction, rawResponse, async (int, raw) => {
+    // Use the response-interpreter agent to interpret ambiguous responses
+    const result = await agent('response-interpreter', {
+      userResponse: raw,
+      interaction: int
+    });
+    return result;
+  });
+}

package/templates/project-builder/scripts/mac-notification.js

@@ -0,0 +1,24 @@
+"use strict";
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+function escAppleScript(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function notify(title = "Notification", message = "Everything finished!") {
+  const script = `display notification "${escAppleScript(message)}" with title "${escAppleScript(title)}"`;
+  spawnSync("osascript", ["-e", script], { stdio: "ignore" });
+
+  const soundPath = "/System/Library/Sounds/Glass.aiff";
+  const fallbackPath = "/System/Library/Sounds/Ping.aiff";
+
+  if (existsSync(soundPath)) {
+    spawnSync("afplay", [soundPath], { stdio: "ignore" });
+  } else if (existsSync(fallbackPath)) {
+    spawnSync("afplay", [fallbackPath], { stdio: "ignore" });
+  }
+}
+
+export { notify };

package/templates/project-builder/scripts/text-human.js

@@ -0,0 +1,92 @@
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import nodemailer from "nodemailer";
+
+function loadEnvFile() {
+  if (typeof process.loadEnvFile === "function") {
+    process.loadEnvFile();
+    return;
+  }
+
+  const envPath = ".env";
+  if (!existsSync(envPath)) {
+    return;
+  }
+
+  const lines = readFileSync(envPath, "utf8").split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!match) {
+      continue;
+    }
+
+    const key = match[1];
+    if (process.env[key] !== undefined) {
+      continue;
+    }
+
+    let value = match[2] ?? "";
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    process.env[key] = value;
+  }
+}
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+function createTransport() {
+  const host = requireEnv("SMTP_HOST");
+  const port = Number(requireEnv("SMTP_PORT"));
+  const user = requireEnv("SMTP_USER");
+  const pass = requireEnv("SMTP_PASS");
+  const secure = String(process.env.SMTP_SECURE || "").toLowerCase() === "true";
+
+  return nodemailer.createTransport({
+    host,
+    port,
+    secure,
+    auth: {
+      user,
+      pass,
+    },
+  });
+}
+
+async function textHuman(message) {
+  loadEnvFile();
+
+  if (!message || typeof message !== "string") {
+    throw new Error("textHuman(message) requires a non-empty string.");
+  }
+
+  const from = process.env.SMS_FROM || requireEnv("SMTP_FROM");
+  const to = requireEnv("SMS_TO");
+  const transporter = createTransport();
+
+  const info = await transporter.sendMail({
+    from,
+    to,
+    subject: "",
+    text: message,
+  });
+  void info;
+}
+
+export { textHuman };

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

@@ -0,0 +1,122 @@
+import fs from 'fs';
+import path from 'path';
+import { memory } from 'agent-state-machine';
+
+// Write markdown file to workflow state directory
+function writeMarkdownFile(stateDir, filename, content) {
+  if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
+  const filePath = path.join(stateDir, filename);
+  fs.writeFileSync(filePath, content);
+  console.log(`  [File] Updated: ${filename}`);
+  return filePath;
+}
+
+// Strict approval parsing - only accepts explicit approval
+function isApproval(response) {
+  if (!response || typeof response !== 'string') return false;
+  const trimmed = response.trim().toLowerCase();
+  // Must start with 'a' or be exactly 'approve/approved/yes/y'
+  return /^a\b/.test(trimmed) ||
+         /^approve/.test(trimmed) ||
+         /^yes\b/.test(trimmed) ||
+         /^y\b/.test(trimmed);
+}
+
+// Generate markdown from roadmap JSON
+function renderRoadmapMarkdown(roadmap) {
+  if (!roadmap || !roadmap.phases) return '# Project Roadmap\n\nNo phases defined.';
+
+  let md = `# Project Roadmap: ${roadmap.title || 'Untitled Project'}\n\n`;
+
+  for (const phase of roadmap.phases) {
+    const status = phase.completed ? ' [COMPLETED]' : '';
+    md += `## Phase ${phase.number}: ${phase.title}${status}\n`;
+    md += `**Objective:** ${phase.objective || 'No objective specified'}\n\n`;
+
+    for (const item of phase.checklist || []) {
+      const check = item.completed ? 'x' : ' ';
+      md += `- [${check}] ${item.text}\n`;
+    }
+    md += '\n';
+  }
+
+  if (roadmap.notes && roadmap.notes.length > 0) {
+    md += '---\n\n**Notes:**\n';
+    for (const note of roadmap.notes) {
+      md += `- ${note}\n`;
+    }
+  }
+
+  return md;
+}
+
+// Generate markdown from tasks JSON
+function renderTasksMarkdown(phaseNumber, phaseTitle, tasks) {
+  if (!tasks || !Array.isArray(tasks)) return `# Phase ${phaseNumber} Tasks\n\nNo tasks defined.`;
+
+  let md = `# Phase ${phaseNumber} Tasks: ${phaseTitle}\n\n`;
+
+  for (const task of tasks) {
+    const status = task.stage === 'completed' ? ' [COMPLETED]' :
+                   task.stage === 'in_progress' ? ' [IN PROGRESS]' : '';
+    md += `## Task ${task.id}: ${task.title}${status}\n`;
+    md += `**Description:** ${task.description || 'No description'}\n\n`;
+    md += `**Definition of Done:**\n- ${task.doneDefinition || 'Task completed successfully'}\n\n`;
+    md += `**Sanity Check:**\n- ${task.sanityCheck || 'Review the implementation and confirm it meets requirements.'}\n\n`;
+    md += '---\n\n';
+  }
+
+  md += '## Checklist Summary\n';
+  for (const task of tasks) {
+    const check = task.stage === 'completed' ? 'x' : ' ';
+    md += `- [${check}] Task ${task.id}: ${task.title}\n`;
+  }
+
+  return md;
+}
+
+// Task stage management
+const TASK_STAGES = {
+  PENDING: 'pending',
+  SECURITY_PRE: 'security_pre',
+  TEST_PLANNING: 'test_planning',
+  IMPLEMENTING: 'implementing',
+  CODE_REVIEW: 'code_review',
+  SECURITY_POST: 'security_post',
+  SANITY_CHECK: 'sanity_check',
+  AWAITING_APPROVAL: 'awaiting_approval',
+  COMPLETED: 'completed',
+  FAILED: 'failed'
+};
+
+function getTaskStage(phaseIndex, taskId) {
+  const key = `phase_${phaseIndex}_task_${taskId}_stage`;
+  return memory[key] || TASK_STAGES.PENDING;
+}
+
+function setTaskStage(phaseIndex, taskId, stage) {
+  const key = `phase_${phaseIndex}_task_${taskId}_stage`;
+  memory[key] = stage;
+}
+
+function getTaskData(phaseIndex, taskId, dataKey) {
+  const key = `phase_${phaseIndex}_task_${taskId}_${dataKey}`;
+  return memory[key];
+}
+
+function setTaskData(phaseIndex, taskId, dataKey, value) {
+  const key = `phase_${phaseIndex}_task_${taskId}_${dataKey}`;
+  memory[key] = value;
+}
+
+export {
+  writeMarkdownFile,
+  isApproval,
+  renderRoadmapMarkdown,
+  renderTasksMarkdown,
+  TASK_STAGES,
+  getTaskStage,
+  setTaskStage,
+  getTaskData,
+  setTaskData
+};

package/templates/project-builder/state/current.json

@@ -0,0 +1,9 @@
+{
+  "format": "native",
+  "status": "IDLE",
+  "memory": {},
+  "_pendingInteraction": null,
+  "_error": null,
+  "startedAt": null,
+  "lastUpdatedAt": "__NOW_ISO__"
+}

package/templates/project-builder/steering/config.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "Steering configuration",
+  "enabled": true,
+  "globalPrompt": "global.md"
+}

package/templates/project-builder/steering/global.md

@@ -0,0 +1,19 @@
+# Global Steering Prompt
+
+This content is included with every agent execution in the project-builder workflow.
+
+## Guidelines
+
+- Process data carefully and validate inputs
+- Return well-structured JSON when applicable
+- Log meaningful progress messages
+- Handle errors gracefully
+
+## Helpful Tips
+- Scripts live in /workflows/project-builder/scripts/
+- .gitignore includes /workflows so include ignored files when searching for a script and use `search_file_content` with the `no_ignore` flag to read the contents of script files.
+- Shell execution via `run_shell_command` is unavailable, so reproduce the script's intended side effect to fulfill the task.
+
+## Notes
+
+This file is automatically loaded and passed to every agent in the workflow via `context._steering.global`.