guild-agents 0.3.1 → 1.1.0

package/README.md

@@ -86,11 +86,14 @@ guild new-agent <name>  # Create a custom agent
 guild status            # Show project status
 guild doctor            # Diagnose setup
 guild list              # List agents and skills
+guild run <skill>       # Preview a skill's execution plan (dry-run)
+guild logs              # View execution traces
+guild logs clean        # Remove old traces (--days N, --all)
 ```
 
 ## Under the Hood
 
-Guild coordinates 9 specialized agents through the pipeline. Each agent handles one phase.
+Guild coordinates 10 specialized agents through the pipeline. Each agent handles one phase.
 
 | Agent | Role |
 | --- | --- |
@@ -103,6 +106,7 @@ Guild coordinates 9 specialized agents through the pipeline. Each agent handles
 | bugfix | Bug diagnosis and resolution |
 | db-migration | Schema changes and safe migrations |
 | platform-expert | Diagnoses Claude Code integration issues |
+| learnings-extractor | Extracts compound learnings from pipeline executions |
 
 Agents are flat `.md` files with identity and expertise. Skills orchestrate agents through structured pipelines. Everything lives in `.claude/`, readable by humans, tracked by git.
 

package/bin/guild.js

@@ -14,14 +14,25 @@ import { program } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import chalk from 'chalk';
+import { parseVersion, getPreReleaseWarning } from '../src/utils/version.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
 
+const { channel } = parseVersion(pkg.version);
+const prereleaseWarning = getPreReleaseWarning(pkg.version);
+if (prereleaseWarning) {
+  const color = channel === 'snapshot' ? chalk.red : chalk.yellow;
+  console.error(color(`Guild v${pkg.version} -- ${prereleaseWarning}`));
+}
+
 program
   .name('guild')
   .description('Specification-driven development CLI for Claude Code')
-  .version(pkg.version);
+  .version(pkg.version)
+  .option('--verbose', 'Enable verbose logging (records decision trail)')
+  .option('--debug', 'Enable debug logging (records full prompts and responses)');
 
 // guild init
 program
@@ -94,4 +105,67 @@ program
     }
   });
 
+// guild reset-learnings
+program
+  .command('reset-learnings')
+  .description('Reset the compound learnings file')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .action(async (options) => {
+    try {
+      const { runResetLearnings } = await import('../src/commands/reset-learnings.js');
+      await runResetLearnings(options);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild run
+program
+  .command('run')
+  .description('Execute a skill workflow')
+  .argument('<skill>', 'Skill name to run')
+  .argument('[input]', 'Input text for the skill', '')
+  .option('--profile <profile>', 'Model profile (max, pro)', 'max')
+  .option('--dry-run', 'Display the execution plan without running it')
+  .action(async (skill, input, options) => {
+    try {
+      const { runRun } = await import('../src/commands/run.js');
+      await runRun(skill, input, options);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild logs (list traces)
+const logsCmd = program
+  .command('logs')
+  .description('View and manage execution traces')
+  .action(async (options) => {
+    try {
+      const { runLogs } = await import('../src/commands/logs.js');
+      await runLogs('list', options);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild logs clean
+logsCmd
+  .command('clean')
+  .description('Remove old execution traces')
+  .option('--days <days>', 'Remove traces older than N days', '30')
+  .option('--all', 'Remove all traces')
+  .action(async (options) => {
+    try {
+      const { runLogs } = await import('../src/commands/logs.js');
+      await runLogs('clean', options);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guild-agents",
-  "version": "0.3.1",
+  "version": "1.1.0",
   "description": "Specification-driven development CLI for Claude Code — think before you build",
   "type": "module",
   "files": [
@@ -17,11 +17,18 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/ && markdownlint-cli2 'src/templates/**/*.md'",
-    "lint:js": "eslint src/",
+    "lint": "eslint src/ scripts/ && markdownlint-cli2 'src/templates/**/*.md'",
+    "lint:js": "eslint src/ scripts/",
     "lint:md": "markdownlint-cli2 'src/templates/**/*.md'",
     "dev": "node bin/guild.js",
-    "prepublishOnly": "npm test && npm run lint"
+    "prepublishOnly": "npm test && npm run lint",
+    "version:snapshot": "node scripts/version-snapshot.js",
+    "version:beta": "node scripts/version-beta.js",
+    "version:stable": "node scripts/version-stable.js",
+    "publish:snapshot": "npm run version:snapshot && npm publish --tag snapshot",
+    "publish:beta": "npm run version:beta && npm publish --tag beta",
+    "publish:stable": "npm run version:stable && npm publish --tag latest",
+    "publish:promote-beta": "npm dist-tag add guild-agents@$(node --input-type=commonjs -p \"require('./package.json').version\") beta"
   },
   "keywords": [
     "claude",
@@ -54,7 +61,7 @@
     "@clack/prompts": "^1.0.1",
     "chalk": "^5.3.0",
     "commander": "^14.0.3",
-    "guild-agents": "^0.3.0"
+    "yaml": "^2.8.2"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/commands/doctor.js

@@ -7,6 +7,7 @@ import chalk from 'chalk';
 import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { resolveProjectRoot } from '../utils/files.js';
+import { loadAllSkills } from '../utils/skill-loader.js';
 
 export async function runDoctor() {
   const root = resolveProjectRoot();
@@ -83,9 +84,77 @@ export async function runDoctor() {
     healthy = false;
   }
 
+  // Check workflow validation in skills
+  if (existsSync(skillsDir)) {
+    const skills = loadAllSkills(skillsDir);
+    let workflowCount = 0;
+    let workflowErrors = 0;
+    const errorDetails = [];
+
+    for (const [name, skill] of skills) {
+      if (skill.workflow) {
+        workflowCount++;
+        if (skill.errors.length > 0) {
+          workflowErrors++;
+          errorDetails.push(`${name}: ${skill.errors.join('; ')}`);
+        }
+      }
+
+      // Check that agent references exist
+      if (skill.workflow) {
+        for (const step of skill.workflow.steps) {
+          if (step.role !== 'system' && step.role !== 'dynamic') {
+            const agentPath = join(agentsDir, `${step.role}.md`);
+            if (!existsSync(agentPath)) {
+              errorDetails.push(`${name}: step "${step.id}" references agent "${step.role}" — agent not found`);
+              workflowErrors++;
+            }
+          }
+        }
+      }
+    }
+
+    if (workflowCount > 0 && workflowErrors === 0) {
+      checks.push({ name: `Workflows (${workflowCount} valid)`, pass: true });
+    } else if (workflowCount > 0 && workflowErrors > 0) {
+      checks.push({
+        name: `Workflows (${workflowErrors} issue(s))`,
+        pass: false,
+        fix: errorDetails.join('\n    '),
+      });
+      healthy = false;
+    }
+    // If workflowCount === 0, don't add a check (no workflows to validate)
+
+    // Check for dual-format skills (workflow frontmatter + body step/phase headings)
+    // Matches "### Step 1", "## Phase 2", etc. — requires digit after Step/Phase
+    const STEP_PHASE_RE = /^#{1,3}\s+(Step|Phase)\s+\d/im;
+    const dualFormatWarnings = [];
+
+    for (const [name, skill] of skills) {
+      if (skill.workflow && skill.body && STEP_PHASE_RE.test(skill.body)) {
+        dualFormatWarnings.push(name);
+      }
+    }
+
+    if (dualFormatWarnings.length > 0) {
+      checks.push({
+        name: `Dual-format skills (${dualFormatWarnings.length} warning(s))`,
+        pass: true,
+        warn: true,
+        detail: `Skills with both workflow frontmatter and body step/phase headings: ${dualFormatWarnings.join(', ')}. Workflow steps take precedence — consider removing prose steps from body.`,
+      });
+    }
+  }
+
   // Display results
   for (const check of checks) {
-    if (check.pass) {
+    if (check.warn) {
+      p.log.warn(`${chalk.yellow('⚠')} ${check.name}`);
+      if (check.detail) {
+        p.log.info(chalk.gray(`  ${check.detail}`));
+      }
+    } else if (check.pass) {
       p.log.success(`${chalk.green('✓')} ${check.name}`);
     } else {
       p.log.error(`${chalk.red('✗')} ${check.name}`);

package/src/commands/logs.js

@@ -0,0 +1,63 @@
+/**
+ * logs.js — View and manage Guild execution traces
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { join } from 'node:path';
+import { ensureProjectRoot } from '../utils/files.js';
+import { listTraces, cleanTraces } from '../utils/trace.js';
+
+/**
+ * Runs the `guild logs` command.
+ *
+ * @param {'list'|'clean'} action - Subcommand to run
+ * @param {object} [options={}] - Options
+ * @param {string} [options.days='30'] - Days threshold for clean
+ * @param {boolean} [options.all] - Remove all traces
+ */
+export async function runLogs(action, options = {}) {
+  const root = ensureProjectRoot();
+  const tracesDir = join(root, '.claude', 'guild', 'traces');
+
+  if (action === 'clean') {
+    p.intro(chalk.bold.cyan('Guild — Clean Traces'));
+
+    let removed;
+    if (options.all) {
+      removed = cleanTraces(0, tracesDir);
+    } else {
+      const days = parseInt(options.days || '30', 10);
+      removed = cleanTraces(days, tracesDir);
+    }
+
+    p.log.info(chalk.gray(`Removed ${removed} trace(s).`));
+    p.outro('');
+    return;
+  }
+
+  // Default: list traces
+  p.intro(chalk.bold.cyan('Guild — Traces'));
+
+  const traces = listTraces(tracesDir);
+
+  if (traces.length === 0) {
+    p.log.info(chalk.gray('No traces found.'));
+    p.outro('');
+    return;
+  }
+
+  for (const trace of traces) {
+    const date = trace.date !== 'unknown' ? new Date(trace.date).toLocaleString() : 'unknown';
+    const result = trace.result === 'pass' ? chalk.green('pass') :
+                   trace.result === 'fail' ? chalk.red('fail') :
+                   chalk.gray(trace.result || 'unknown');
+
+    p.log.info(`  ${chalk.white.bold(trace.workflow)} ${result}`);
+    p.log.info(chalk.gray(`    ${date} | level: ${trace.level}`));
+  }
+
+  p.log.info('');
+  p.log.info(chalk.gray(`Total: ${traces.length} trace(s)`));
+  p.outro('');
+}

package/src/commands/reset-learnings.js

@@ -0,0 +1,44 @@
+/**
+ * reset-learnings.js — Resets the compound learnings file
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { join } from 'path';
+import { ensureProjectRoot } from '../utils/files.js';
+import { learningsExist, deleteLearnings } from '../utils/learnings-io.js';
+import { GUILD_LEARNINGS_PATH } from '../utils/learnings.js';
+
+/**
+ * Runs the `guild reset-learnings` command.
+ * @param {object} [options]
+ * @param {boolean} [options.force] - Skip confirmation prompt
+ */
+export async function runResetLearnings(options = {}) {
+  const root = ensureProjectRoot();
+  const filePath = join(root, GUILD_LEARNINGS_PATH);
+
+  p.intro(chalk.bold.cyan('Guild — Reset Learnings'));
+
+  if (!learningsExist(filePath)) {
+    p.log.info('No learnings file found. Nothing to reset.');
+    p.outro('Done.');
+    return;
+  }
+
+  if (!options.force) {
+    const confirmed = await p.confirm({
+      message: 'This will delete all accumulated learnings. Continue?',
+      initialValue: false,
+    });
+
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.cancel('Reset cancelled.');
+      return;
+    }
+  }
+
+  deleteLearnings(filePath);
+  p.log.success(`${chalk.green('✓')} Learnings file deleted.`);
+  p.outro('Learnings have been reset. They will be regenerated on the next workflow execution.');
+}

package/src/commands/run.js

@@ -0,0 +1,105 @@
+/**
+ * run.js — Executes a skill workflow (or displays the plan in dry-run mode)
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { ensureProjectRoot } from '../utils/files.js';
+import { orchestrate, finalizeWorkflowTrace } from '../utils/orchestrator-io.js';
+import { execute } from '../utils/executor.js';
+import { createClaudeCodeProvider } from '../utils/providers/claude-code.js';
+
+/**
+ * Displays the execution plan without running it.
+ * @param {object} plan
+ * @param {object} dispatchInfoMap
+ */
+function displayPlan(plan, dispatchInfoMap) {
+  for (let i = 0; i < plan.groups.length; i++) {
+    const group = plan.groups[i];
+    const label = group.parallel ? `Group ${i + 1} (parallel)` : `Group ${i + 1}`;
+    p.log.step(chalk.bold(label));
+
+    for (const step of group.steps) {
+      const dispatch = dispatchInfoMap[step.id] || {};
+      const roleLabel = step.role === 'system' ? chalk.yellow('system') : chalk.blue(step.role);
+      const modelLabel = dispatch.model ? chalk.gray(` → ${dispatch.model}`) : '';
+      const gateLabel = step.gate ? chalk.red(' GATE') : '';
+
+      p.log.info(`  ${chalk.white.bold(step.id)} ${roleLabel}${modelLabel}${gateLabel}`);
+      p.log.info(chalk.gray(`    ${step.intent}`));
+
+      if (step.requires && step.requires.length > 0) {
+        p.log.info(chalk.gray(`    requires: ${step.requires.join(', ')}`));
+      }
+      if (step.produces && step.produces.length > 0) {
+        p.log.info(chalk.gray(`    produces: ${step.produces.join(', ')}`));
+      }
+      if (step.condition) {
+        p.log.info(chalk.gray(`    condition: ${step.condition}`));
+      }
+      if (step.commands && step.commands.length > 0) {
+        p.log.info(chalk.gray(`    commands: ${step.commands.join(', ')}`));
+      }
+    }
+  }
+}
+
+/**
+ * Runs the `guild run <skill>` command.
+ *
+ * @param {string} skillName - Name of the skill to run
+ * @param {string} [input=''] - Optional input text for the skill
+ * @param {object} [options={}] - Options
+ * @param {string} [options.profile='max'] - Model profile
+ * @param {boolean} [options.dryRun=false] - Show plan without executing
+ */
+export async function runRun(skillName, input = '', options = {}) {
+  const root = ensureProjectRoot();
+  const { profile = 'max', dryRun = false } = options;
+
+  p.intro(chalk.bold.cyan(' Guild — Run: ' + skillName + ' '));
+
+  const { plan, trace, dispatchInfoMap } = await orchestrate(skillName, input, {
+    profile,
+    projectRoot: root,
+  });
+
+  p.log.info(chalk.gray(`Profile: ${profile} | Steps: ${plan.totalSteps}`));
+
+  if (dryRun) {
+    displayPlan(plan, dispatchInfoMap);
+    p.outro(chalk.gray('Plan generated (dry-run). No steps were executed.'));
+    return;
+  }
+
+  // Real execution
+  const provider = createClaudeCodeProvider({ projectRoot: root });
+
+  const finalPlan = await execute(plan, dispatchInfoMap, {
+    provider,
+    skillBody: input,
+    trace,
+    projectRoot: root,
+
+    onStepStart(step, dispatch) {
+      const roleLabel = step.role === 'system' ? chalk.yellow('system') : chalk.blue(step.role);
+      const modelLabel = dispatch.model ? chalk.gray(` (${dispatch.model})`) : '';
+      p.log.step(`${chalk.bold(step.id)} ${roleLabel}${modelLabel}`);
+    },
+
+    onStepEnd(step, result) {
+      const icon = result.status === 'passed' ? chalk.green('✓') : chalk.red('✗');
+      p.log.info(`  ${icon} ${result.status}`);
+    },
+  });
+
+  // Finalize trace
+  const { executionSummary } = finalizeWorkflowTrace(trace, finalPlan);
+
+  const statusLabel = finalPlan.status === 'completed'
+    ? chalk.green('completed')
+    : chalk.red(finalPlan.status);
+
+  p.outro(`${statusLabel} | ${executionSummary}`);
+}

package/src/templates/agents/advisor.md

@@ -3,6 +3,7 @@ name: advisor
 description: "Evaluates ideas and provides strategic direction before committing work"
 tools: Read, Glob, Grep
 permissionMode: plan
+default-tier: reasoning
 ---
 
 # Advisor

package/src/templates/agents/bugfix.md

@@ -3,6 +3,7 @@ name: bugfix
 description: "Bug diagnosis and resolution"
 tools: Read, Write, Edit, Bash, Glob, Grep
 permissionMode: bypassPermissions
+default-tier: execution
 ---
 
 # Bugfix

package/src/templates/agents/code-reviewer.md

@@ -3,6 +3,7 @@ name: code-reviewer
 description: "Reviews quality, patterns, and technical debt"
 tools: Read, Glob, Grep
 permissionMode: plan
+default-tier: reasoning
 ---
 
 # Code Reviewer

package/src/templates/agents/db-migration.md

@@ -3,6 +3,7 @@ name: db-migration
 description: "Schema changes and safe migrations"
 tools: Read, Write, Edit, Bash, Glob, Grep
 permissionMode: bypassPermissions
+default-tier: execution
 ---
 
 # DB Migration

package/src/templates/agents/developer.md

@@ -3,6 +3,7 @@ name: developer
 description: "Implements features following the project conventions"
 tools: Read, Write, Edit, Bash, Glob, Grep
 permissionMode: bypassPermissions
+default-tier: execution
 ---
 
 # Developer

package/src/templates/agents/learnings-extractor.md

@@ -0,0 +1,49 @@
+---
+name: learnings-extractor
+description: "Extracts compound learnings from pipeline executions"
+tools: Read, Glob, Grep
+permissionMode: plan
+default-tier: routine
+---
+
+# Learnings Extractor
+
+You are the Learnings Extractor for [PROJECT]. Your job is to analyze completed pipeline traces and extract reusable patterns, recurring issues, and optimization opportunities that improve future executions.
+
+## Responsibilities
+
+- Read pipeline trace files from `.claude/guild/traces/`
+- Identify patterns across multiple executions (recurring review loops, common failures)
+- Extract actionable learnings that reduce future iteration count
+- Update `.claude/guild/learnings.md` with new findings
+- Prioritize learnings by impact (reduces tokens, reduces loops, improves quality)
+
+## What you do NOT do
+
+- You do not implement features — that is the Developer's role
+- You do not evaluate strategy — that is the Advisor's role
+- You do not modify source code — you only read traces and write learnings
+
+## Process
+
+1. Read the pipeline trace provided as input
+2. Analyze step results, loop counts, and failure patterns
+3. Compare with existing learnings in `.claude/guild/learnings.md`
+4. Extract new learnings or reinforce existing ones
+5. Write updated learnings in a structured format
+
+## Output format
+
+Each learning should include:
+
+- **Pattern**: What was observed
+- **Frequency**: How often it occurs (first-seen or recurring)
+- **Recommendation**: What to do differently next time
+- **Impact**: Expected reduction in loops, tokens, or failures
+
+## Behavior rules
+
+- Never duplicate an existing learning — update its frequency instead
+- Focus on actionable recommendations, not observations
+- Keep learnings concise — one paragraph maximum per entry
+- Tag learnings with the workflow they came from

package/src/templates/agents/platform-expert.md

@@ -3,6 +3,7 @@ name: platform-expert
 description: "Diagnoses and resolves Claude Code integration issues -- permissions, subagents, hooks, settings"
 tools: Read, Write, Edit, Bash, Glob, Grep
 permissionMode: bypassPermissions
+default-tier: execution
 ---
 
 # Platform Expert

package/src/templates/agents/product-owner.md

@@ -3,6 +3,7 @@ name: product-owner
 description: "Converts approved ideas into concrete, implementable tasks"
 tools: Read, Glob, Grep
 permissionMode: plan
+default-tier: reasoning
 ---
 
 # Product Owner

package/src/templates/agents/qa.md

@@ -3,6 +3,7 @@ name: qa
 description: "Testing, edge cases, regression"
 tools: Read, Write, Edit, Bash, Glob, Grep
 permissionMode: bypassPermissions
+default-tier: execution
 ---
 
 # QA

package/src/templates/agents/tech-lead.md

@@ -3,6 +3,7 @@ name: tech-lead
 description: "Defines technical approach and architecture"
 tools: Read, Glob, Grep
 permissionMode: plan
+default-tier: reasoning
 ---
 
 # Tech Lead