guild-agents 0.3.1 → 1.1.0

package/src/templates/skills/session-start/SKILL.md

@@ -2,6 +2,38 @@
 name: session-start
 description: "Loads context and resumes work from SESSION.md"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: load-context
+      role: system
+      intent: "Read CLAUDE.md, SESSION.md, and PROJECT.md to load project context."
+      commands: [cat CLAUDE.md, cat SESSION.md, cat PROJECT.md]
+      produces: [claude-md, session-md, project-md]
+    - id: detect-resumable
+      role: system
+      intent: "Check for wip: checkpoint commits on feature and fix branches."
+      commands: [git branch --list "feature/*" --list "fix/*", git log --oneline -1]
+      requires: [session-md]
+      produces: [resumable-branches, last-phase]
+    - id: present-state
+      role: system
+      intent: "Display previous session summary: date, task, state, decisions, next steps, resumable pipelines."
+      requires: [session-md, resumable-branches]
+      produces: [state-display]
+      gate: true
+    - id: suggest-continuation
+      role: system
+      intent: "Suggest appropriate skill to continue based on current state."
+      requires: [state-display]
+      produces: [suggested-action]
+      gate: true
+    - id: update-session
+      role: system
+      intent: "Update SESSION.md with current date to record session start."
+      requires: [session-md]
+      produces: [session-updated]
+      gate: true
 ---
 
 # Session Start

package/src/templates/skills/status/SKILL.md

@@ -2,6 +2,25 @@
 name: status
 description: "Shows current project and session state"
 user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - id: read-state
+      role: system
+      intent: "Read CLAUDE.md, PROJECT.md, and SESSION.md for project state."
+      commands: [cat CLAUDE.md, cat PROJECT.md, cat SESSION.md]
+      produces: [claude-md, project-md, session-md]
+    - id: scan-resources
+      role: system
+      intent: "List available agents and skills from .claude/ directories."
+      commands: [ls .claude/agents/, ls .claude/skills/]
+      produces: [agent-list, skill-list]
+    - id: present-status
+      role: system
+      intent: "Display project summary: name, stack, session state, agents, skills, and suggested next steps."
+      requires: [project-md, session-md, agent-list, skill-list]
+      produces: [status-display]
+      gate: true
 ---
 
 # Status

package/src/utils/dispatch-protocol.js

@@ -0,0 +1,74 @@
+/**
+ * dispatch-protocol.js — Constants and type definitions for the Guild dispatch protocol.
+ *
+ * Defines the vocabulary shared by dispatch utilities, workflow parser,
+ * model routing, and trace modules. Zero dependencies.
+ */
+
+/**
+ * Valid model tier values. Each tier maps to a class of model capability.
+ * @type {readonly ['reasoning', 'execution', 'routine']}
+ */
+export const MODEL_TIERS = ['reasoning', 'execution', 'routine'];
+
+/**
+ * Valid failure strategy base values for workflow steps.
+ * - abort: halt the workflow on failure (default)
+ * - continue: skip this step and proceed
+ * Additionally, `goto:<step-id>` is valid for redirecting to another step.
+ * @type {readonly ['abort', 'continue']}
+ */
+export const FAILURE_STRATEGIES = ['abort', 'continue'];
+
+/**
+ * Default failure strategy when none is specified.
+ * @type {string}
+ */
+export const DEFAULT_FAILURE_STRATEGY = 'abort';
+
+/**
+ * Default tier assignment for each Guild agent role.
+ * Used as fallback when neither the workflow step nor the agent frontmatter
+ * specifies a tier.
+ * @type {Record<string, string>}
+ */
+export const DEFAULT_AGENT_TIERS = {
+  'advisor': 'reasoning',
+  'product-owner': 'reasoning',
+  'tech-lead': 'reasoning',
+  'code-reviewer': 'reasoning',
+  'developer': 'execution',
+  'bugfix': 'execution',
+  'db-migration': 'execution',
+  'qa': 'execution',
+  'platform-expert': 'execution',
+  'learnings-extractor': 'routine',
+};
+
+/**
+ * Built-in model profiles mapping tiers to concrete model IDs.
+ * @type {Record<string, Record<string, string>>}
+ */
+export const DEFAULT_MODEL_PROFILES = {
+  max: {
+    reasoning: 'claude-opus-4-6',
+    execution: 'claude-sonnet-4-6',
+    routine: 'claude-haiku-4-5',
+  },
+  pro: {
+    reasoning: 'claude-sonnet-4-6',
+    execution: 'claude-sonnet-4-6',
+    routine: 'claude-haiku-4-5',
+  },
+};
+
+/**
+ * Fallback chain for tier resolution. When a tier's model is unavailable,
+ * fall back to the next tier. `null` means no further fallback.
+ * @type {Record<string, string|null>}
+ */
+export const FALLBACK_CHAIN = {
+  reasoning: 'execution',
+  execution: 'routine',
+  routine: null,
+};

package/src/utils/dispatch.js

@@ -0,0 +1,172 @@
+/**
+ * dispatch.js — Validation and resolution utilities for the Guild dispatch protocol.
+ *
+ * Provides functions to validate workflow step configurations, resolve agent
+ * metadata from frontmatter, determine effective model tiers, and resolve
+ * tiers to concrete model IDs.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { parseFrontmatter } from './files.js';
+import { parseSkill } from './workflow-parser.js';
+import {
+  MODEL_TIERS,
+  FAILURE_STRATEGIES,
+  DEFAULT_AGENT_TIERS,
+  DEFAULT_MODEL_PROFILES,
+  FALLBACK_CHAIN,
+} from './dispatch-protocol.js';
+
+/**
+ * Validates a workflow step configuration object.
+ * @param {object} config - Step config with role, intent, model-tier, etc.
+ * @returns {string[]} Array of error messages (empty means valid)
+ */
+export function validateStepConfig(config) {
+  const errors = [];
+
+  if (!config.role) {
+    errors.push('Missing required field: role');
+  }
+
+  if (!config.intent) {
+    errors.push('Missing required field: intent');
+  }
+
+  if (config['model-tier'] && !MODEL_TIERS.includes(config['model-tier'])) {
+    errors.push(`Invalid model-tier: "${config['model-tier']}". Must be one of: ${MODEL_TIERS.join(', ')}`);
+  }
+
+  if (config['on-failure']) {
+    const isGoto = config['on-failure'].startsWith('goto:');
+    if (!FAILURE_STRATEGIES.includes(config['on-failure']) && !isGoto) {
+      errors.push(`Invalid on-failure: "${config['on-failure']}". Must be one of: ${FAILURE_STRATEGIES.join(', ')}, or goto:<step-id>`);
+    }
+  }
+
+  if (config['max-retries'] !== undefined) {
+    const val = config['max-retries'];
+    if (!Number.isInteger(val) || val < 1) {
+      errors.push(`Invalid max-retries: ${val}. Must be a positive integer`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Reads agent metadata from the agent's markdown frontmatter.
+ * @param {string} role - Agent role name (e.g., 'tech-lead')
+ * @param {string} [projectRoot=process.cwd()] - Project root directory
+ * @returns {{ name: string, role: string, defaultTier: string|undefined, [key: string]: unknown } | null}
+ */
+export function resolveAgentMetadata(role, projectRoot = process.cwd()) {
+  const agentPath = join(projectRoot, '.claude', 'agents', `${role}.md`);
+
+  if (!existsSync(agentPath)) {
+    return null;
+  }
+
+  const content = readFileSync(agentPath, 'utf8');
+  const frontmatter = parseFrontmatter(content);
+
+  return {
+    ...frontmatter,
+    role,
+    defaultTier: frontmatter['default-tier'] || undefined,
+  };
+}
+
+/**
+ * Resolves the effective model tier for a workflow step using the precedence chain:
+ * 1. stepConfig['model-tier'] (explicit in workflow step)
+ * 2. agentMetadata.defaultTier (from agent frontmatter)
+ * 3. DEFAULT_AGENT_TIERS[role] (hardcoded defaults)
+ * 4. 'execution' (ultimate fallback)
+ *
+ * @param {object} stepConfig - Workflow step with role and optional model-tier
+ * @param {object|null} [agentMetadata=null] - Agent metadata from resolveAgentMetadata
+ * @returns {string} One of MODEL_TIERS values
+ */
+export function resolveEffectiveTier(stepConfig, agentMetadata = null) {
+  if (stepConfig['model-tier'] && MODEL_TIERS.includes(stepConfig['model-tier'])) {
+    return stepConfig['model-tier'];
+  }
+
+  if (agentMetadata?.defaultTier && MODEL_TIERS.includes(agentMetadata.defaultTier)) {
+    return agentMetadata.defaultTier;
+  }
+
+  const defaultTier = DEFAULT_AGENT_TIERS[stepConfig.role];
+  if (defaultTier) {
+    return defaultTier;
+  }
+
+  return 'execution';
+}
+
+/**
+ * Resolves a model tier to a concrete model ID using a profile.
+ * Applies the fallback chain if the tier is not found in the profile.
+ *
+ * @param {string} tier - One of MODEL_TIERS
+ * @param {string|Record<string, string>} profile - Profile name ('max', 'pro') or custom mapping
+ * @returns {string} Concrete model ID (e.g., 'claude-opus-4-6')
+ * @throws {Error} If no model can be resolved after exhausting the fallback chain
+ */
+export function resolveModel(tier, profile) {
+  const profileMap = typeof profile === 'string'
+    ? DEFAULT_MODEL_PROFILES[profile]
+    : profile;
+
+  if (!profileMap) {
+    throw new Error(`Unknown profile: "${profile}". Available: ${Object.keys(DEFAULT_MODEL_PROFILES).join(', ')}`);
+  }
+
+  let currentTier = tier;
+  const visited = new Set();
+
+  while (currentTier) {
+    if (visited.has(currentTier)) {
+      break;
+    }
+    visited.add(currentTier);
+
+    if (profileMap[currentTier]) {
+      return profileMap[currentTier];
+    }
+
+    currentTier = FALLBACK_CHAIN[currentTier];
+  }
+
+  throw new Error(`Cannot resolve model for tier "${tier}": no model available in profile after fallback chain`);
+}
+
+/**
+ * Extracts dispatch configuration from skill markdown content.
+ * Precedence: workflow steps (frontmatter) > null (legacy prose).
+ *
+ * Dependency direction: dispatch.js imports from workflow-parser.js.
+ * Do not reverse this — workflow-parser.js must not import from dispatch.js.
+ *
+ * @param {string} skillMarkdown - Raw SKILL.md content
+ * @returns {{ source: 'workflow', steps: Array<object> } | { source: null }}
+ * @throws {Error} If YAML frontmatter is malformed (propagated from parseSkill)
+ */
+export function extractDispatchConfigs(skillMarkdown) {
+  if (!skillMarkdown) {
+    return { source: null };
+  }
+
+  const skill = parseSkill(skillMarkdown);
+
+  if (skill.workflow && Array.isArray(skill.workflow.steps) && skill.workflow.steps.length > 0) {
+    return {
+      source: 'workflow',
+      steps: skill.workflow.steps,
+    };
+  }
+
+  return { source: null };
+}

package/src/utils/executor.js

@@ -0,0 +1,183 @@
+/**
+ * executor.js — Execution loop for Guild workflow plans.
+ *
+ * Drives a plan to completion by iterating through steps, dispatching
+ * agent steps to a provider function and system steps to local commands.
+ * Sequential execution only (v1.1); parallel groups deferred to v1.2.
+ */
+
+import { execFile } from 'child_process';
+import {
+  advanceStep,
+  getNextSteps,
+  isPlanComplete,
+} from './orchestrator.js';
+import { buildStepContext, recordStepTrace } from './orchestrator-io.js';
+
+const SYSTEM_STEP_TIMEOUT = 120_000; // 2 minutes
+
+/**
+ * Promisified execFile wrapper that always resolves (never rejects).
+ *
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Arguments
+ * @param {object} opts - execFile options
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number }>}
+ */
+function execFileAsync(cmd, args, opts) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, opts, (error, stdout, stderr) => {
+      resolve({
+        stdout: stdout || '',
+        stderr: stderr || (error && error.message) || '',
+        exitCode: error ? (typeof error.code === 'number' ? error.code : 1) : 0,
+      });
+    });
+  });
+}
+
+/**
+ * Executes a system step by running its commands or handling delegation.
+ *
+ * @param {object} step - System step definition
+ * @param {object} [options={}] - Options
+ * @param {string} [options.projectRoot=process.cwd()] - Working directory for commands
+ * @returns {Promise<{ status: string, output: string }>}
+ */
+async function executeSystemStep(step, options = {}) {
+  const { projectRoot = process.cwd() } = options;
+
+  if (step.commands && step.commands.length > 0) {
+    const outputs = [];
+    for (const cmd of step.commands) {
+      // v1.1: simple split — commands with quoted args or shell features
+      // are not supported. Use simple commands like "npm test".
+      const [bin, ...args] = cmd.split(' ');
+      const result = await execFileAsync(bin, args, {
+        cwd: projectRoot,
+        timeout: SYSTEM_STEP_TIMEOUT,
+      });
+
+      if (result.exitCode !== 0) {
+        return {
+          status: 'failed',
+          output: result.stderr || result.stdout || `Command failed: ${cmd}`,
+        };
+      }
+      outputs.push(result.stdout);
+    }
+    return { status: 'passed', output: outputs.join('\n') };
+  }
+
+  if (step.delegatesTo) {
+    return { status: 'passed', output: `Delegation to "${step.delegatesTo}" skipped (v1.1)` };
+  }
+
+  return { status: 'passed', output: 'System step completed' };
+}
+
+/**
+ * Finds a step definition by ID across all groups in a plan.
+ *
+ * @param {object} plan - Execution plan
+ * @param {string} stepId - Step ID to find
+ * @returns {object|null}
+ */
+function findStepInPlan(plan, stepId) {
+  for (const group of plan.groups) {
+    for (const step of group.steps) {
+      if (step.id === stepId) return step;
+    }
+  }
+  return null;
+}
+
+/**
+ * Executes a workflow plan to completion.
+ *
+ * Drives the orchestrator state machine by repeatedly calling getNextSteps,
+ * dispatching each step (agent via provider, system via local commands),
+ * and advancing the plan with the result.
+ *
+ * @param {import('./orchestrator.js').ExecutionPlan} plan - Initial execution plan
+ * @param {Object.<string, import('./orchestrator-io.js').StepDispatchInfo>} dispatchInfoMap - Dispatch info per step
+ * @param {object} [options={}] - Options
+ * @param {Function} options.provider - Agent step provider: (step, dispatch, context) => { status, output, outcome?, error?, tokens? }
+ * @param {object} [options.trace] - Trace context for recording step executions
+ * @param {string} [options.projectRoot] - Working directory for system commands
+ * @param {string} [options.skillBody=''] - Skill body text for context building
+ * @param {Function} [options.onStepStart] - Callback before each step: (step, dispatch) => void
+ * @param {Function} [options.onStepEnd] - Callback after each step: (step, result) => void
+ * @returns {Promise<import('./orchestrator.js').ExecutionPlan>} Final plan state
+ */
+export async function execute(plan, dispatchInfoMap, options = {}) {
+  const {
+    provider,
+    trace,
+    projectRoot,
+    skillBody = '',
+    onStepStart,
+    onStepEnd,
+  } = options;
+
+  let currentPlan = plan;
+  let emptyIterations = 0;
+  const MAX_EMPTY_ITERATIONS = 100;
+
+  while (!isPlanComplete(currentPlan)) {
+    const { steps, skipped } = getNextSteps(currentPlan);
+
+    // Advance skipped steps first
+    for (const stepId of skipped) {
+      currentPlan = advanceStep(currentPlan, stepId, { status: 'skipped' });
+
+      if (trace) {
+        const step = findStepInPlan(currentPlan, stepId);
+        const dispatch = dispatchInfoMap[stepId] || {};
+        if (step) {
+          recordStepTrace(trace, step, currentPlan.stepStates[stepId], dispatch);
+        }
+      }
+    }
+
+    // If no executable steps remain, check completion again
+    if (steps.length === 0) {
+      if (isPlanComplete(currentPlan)) break;
+      if (++emptyIterations > MAX_EMPTY_ITERATIONS) {
+        currentPlan = { ...currentPlan, status: 'aborted' };
+        break;
+      }
+      continue;
+    }
+    emptyIterations = 0;
+
+    // v1.1: sequential execution — one step at a time
+    const step = steps[0];
+    const dispatch = dispatchInfoMap[step.id] || {};
+
+    onStepStart?.(step, dispatch);
+
+    let result;
+    if (step.role === 'system') {
+      result = await executeSystemStep(step, { projectRoot });
+    } else {
+      const context = buildStepContext(step, currentPlan, { skillBody });
+      result = await provider(step, dispatch, context);
+    }
+
+    currentPlan = advanceStep(currentPlan, step.id, result);
+
+    if (trace) {
+      recordStepTrace(trace, step, currentPlan.stepStates[step.id], dispatch);
+    }
+
+    onStepEnd?.(step, result);
+  }
+
+  // Mark plan as completed if all steps reached terminal state and plan is still running
+  if (currentPlan.status === 'running' && isPlanComplete(currentPlan)) {
+    currentPlan = { ...currentPlan, status: 'completed' };
+  }
+
+  return currentPlan;
+}

package/src/utils/learnings-io.js

@@ -0,0 +1,76 @@
+/**
+ * learnings-io.js — File I/O operations for compound learnings.
+ *
+ * Read, write, init, exists, and delete operations for .claude/guild/learnings.md.
+ * Separated from the pure functions in learnings.js following the trace.js pattern.
+ *
+ * NOTE: File locking for concurrent access is intentionally omitted.
+ * Concurrent workflow execution is a v2 concern — current Guild workflows
+ * are single-session and sequential.
+ */
+
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { GUILD_LEARNINGS_PATH, renderEmptyLearnings } from './learnings.js';
+
+/**
+ * Reads the learnings file from disk.
+ * Returns the raw content as a string, or null if the file does not exist.
+ * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
+ * @returns {string | null}
+ */
+export function readLearnings(filePath) {
+  const target = filePath || GUILD_LEARNINGS_PATH;
+  if (!existsSync(target)) return null;
+  return readFileSync(target, 'utf8');
+}
+
+/**
+ * Writes content to the learnings file.
+ * Creates parent directories if needed.
+ * @param {string} content - Markdown content to write
+ * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
+ */
+export function writeLearnings(content, filePath) {
+  const target = filePath || GUILD_LEARNINGS_PATH;
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content, 'utf8');
+}
+
+/**
+ * Checks whether the learnings file exists on disk.
+ * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
+ * @returns {boolean}
+ */
+export function learningsExist(filePath) {
+  const target = filePath || GUILD_LEARNINGS_PATH;
+  return existsSync(target);
+}
+
+/**
+ * Initializes the learnings file with empty scaffold content.
+ * No-ops if the file already exists.
+ * @param {string} [projectName='Project'] - Project name for the header
+ * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
+ * @returns {{ created: boolean }}
+ */
+export function initLearnings(projectName = 'Project', filePath) {
+  const target = filePath || GUILD_LEARNINGS_PATH;
+  if (existsSync(target)) return { created: false };
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, renderEmptyLearnings(projectName), 'utf8');
+  return { created: true };
+}
+
+/**
+ * Deletes the learnings file from disk.
+ * Returns { deleted: false } if the file does not exist (no throw).
+ * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
+ * @returns {{ deleted: boolean }}
+ */
+export function deleteLearnings(filePath) {
+  const target = filePath || GUILD_LEARNINGS_PATH;
+  if (!existsSync(target)) return { deleted: false };
+  unlinkSync(target);
+  return { deleted: true };
+}