guild-agents 0.3.1 → 1.0.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/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 };
+}

package/src/utils/learnings.js

@@ -0,0 +1,204 @@
+/**
+ * learnings.js — Pure functions for compound learning.
+ *
+ * Constants, parsing, rendering, token estimation, and context injection.
+ * Zero I/O, zero external dependencies — leaf module.
+ */
+
+/** Fixed section names for the learnings file (spec section 3.3). */
+export const LEARNINGS_SECTIONS = [
+  'Project Patterns',
+  'Architecture Decisions',
+  'Past Issues & Resolutions',
+  'User Preferences',
+  'Agent Notes',
+];
+
+/** Maximum token budget for the learnings file. */
+export const TOKEN_BUDGET = 2000;
+
+/** Default path to the learnings file, relative to project root. */
+export const GUILD_LEARNINGS_PATH = '.claude/guild/learnings.md';
+
+/**
+ * Estimates token count from text using a word-count heuristic.
+ * Approximation: tokens ≈ ceil(words × 1.35).
+ * @param {string | null | undefined} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  if (!text || !text.trim()) return 0;
+  const words = text.trim().split(/\s+/).length;
+  return Math.ceil(words * 1.35);
+}
+
+/**
+ * Returns true if the estimated token count is within the budget.
+ * @param {string | null | undefined} text
+ * @param {number} [budget=TOKEN_BUDGET]
+ * @returns {boolean}
+ */
+export function isWithinBudget(text, budget = TOKEN_BUDGET) {
+  return estimateTokens(text) <= budget;
+}
+
+/**
+ * Renders the initial/empty learnings file content.
+ * @param {string} [projectName='Project']
+ * @returns {string}
+ */
+export function renderEmptyLearnings(projectName = 'Project') {
+  const lines = [];
+  lines.push(`# Guild Learnings — ${projectName}`);
+  lines.push('');
+  lines.push(`> Auto-generated by Guild. Last updated: ${new Date().toISOString()}`);
+  lines.push('> Total executions: 0');
+  lines.push('> Token budget: this file should stay under 2000 tokens');
+  lines.push('');
+
+  for (const section of LEARNINGS_SECTIONS) {
+    lines.push(`## ${section}`);
+    lines.push('');
+    lines.push('_No learnings yet._');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+const PLACEHOLDER_RE = /^_No learnings yet\._$/;
+const ENTRY_RE = /^- (.+)$/;
+const DISCOVERED_RE = /\(discovered: ([^)]+)\)/;
+
+/**
+ * Parses a learnings.md file into a structured object.
+ * @param {string | null | undefined} content
+ * @returns {{ header: { project: string, lastUpdated: string, totalExecutions: number }, sections: Record<string, Array<{ text: string, discovered: string }>> }}
+ */
+export function parseLearnings(content) {
+  const empty = {
+    header: { project: '', lastUpdated: '', totalExecutions: 0 },
+    sections: {},
+  };
+  for (const s of LEARNINGS_SECTIONS) empty.sections[s] = [];
+
+  if (!content || !content.trim()) return empty;
+
+  const lines = content.split('\n');
+  const result = { header: { project: '', lastUpdated: '', totalExecutions: 0 }, sections: {} };
+  for (const s of LEARNINGS_SECTIONS) result.sections[s] = [];
+
+  let currentSection = null;
+
+  for (const line of lines) {
+    // Parse H1 header
+    const h1Match = line.match(/^# Guild Learnings — (.+)$/);
+    if (h1Match) {
+      result.header.project = h1Match[1].trim();
+      continue;
+    }
+
+    // Parse header metadata
+    const updatedMatch = line.match(/^> Auto-generated by Guild\. Last updated: (.+)$/);
+    if (updatedMatch) {
+      result.header.lastUpdated = updatedMatch[1].trim();
+      continue;
+    }
+    const execMatch = line.match(/^> Total executions: (\d+)$/);
+    if (execMatch) {
+      result.header.totalExecutions = parseInt(execMatch[1], 10);
+      continue;
+    }
+
+    // Parse section headers
+    const h2Match = line.match(/^## (.+)$/);
+    if (h2Match) {
+      const sectionName = h2Match[1].trim();
+      if (LEARNINGS_SECTIONS.includes(sectionName)) {
+        currentSection = sectionName;
+      } else {
+        currentSection = null;
+      }
+      continue;
+    }
+
+    // Skip placeholders and blank lines
+    if (!currentSection) continue;
+    if (PLACEHOLDER_RE.test(line.trim())) continue;
+    if (!line.trim()) continue;
+
+    // Parse entries (lines starting with "- ")
+    const entryMatch = line.match(ENTRY_RE);
+    if (entryMatch) {
+      const text = entryMatch[1].trim();
+      const discoveredMatch = text.match(DISCOVERED_RE);
+      result.sections[currentSection].push({
+        text,
+        discovered: discoveredMatch ? discoveredMatch[1] : '',
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Renders a parsed learnings structure back to markdown.
+ * @param {{ header: { project: string, lastUpdated: string, totalExecutions: number }, sections: Record<string, Array<{ text: string, discovered: string }>> }} parsed
+ * @returns {string}
+ */
+export function renderLearnings(parsed) {
+  const lines = [];
+  const project = parsed.header.project || 'Project';
+  const lastUpdated = parsed.header.lastUpdated || new Date().toISOString();
+  const totalExecutions = parsed.header.totalExecutions || 0;
+
+  lines.push(`# Guild Learnings — ${project}`);
+  lines.push('');
+  lines.push(`> Auto-generated by Guild. Last updated: ${lastUpdated}`);
+  lines.push(`> Total executions: ${totalExecutions}`);
+  lines.push('> Token budget: this file should stay under 2000 tokens');
+  lines.push('');
+
+  for (const section of LEARNINGS_SECTIONS) {
+    lines.push(`## ${section}`);
+    lines.push('');
+    const entries = parsed.sections[section] || [];
+    if (entries.length === 0) {
+      lines.push('_No learnings yet._');
+    } else {
+      for (const entry of entries) {
+        lines.push(`- ${entry.text}`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Builds a context injection string from raw learnings content.
+ * Wraps in <guild-learnings> tags per spec section 4.2.
+ * Returns empty string for null/empty input.
+ * @param {string | null | undefined} content
+ * @returns {string}
+ */
+export function buildContextInjection(content) {
+  if (!content || !content.trim()) return '';
+
+  const parsed = parseLearnings(content);
+  const hasEntries = LEARNINGS_SECTIONS.some(s => (parsed.sections[s] || []).length > 0);
+  if (!hasEntries) return '';
+
+  const lines = [];
+  lines.push('<guild-learnings>');
+  lines.push(content.trim());
+  lines.push('</guild-learnings>');
+  lines.push('');
+  lines.push('These are accumulated learnings from previous Guild executions on this project.');
+  lines.push('Use them to inform your work. Do not contradict established patterns unless');
+  lines.push('explicitly asked to change them.');
+
+  return lines.join('\n');
+}