guild-agents 1.4.0 → 2.0.0

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

@@ -8,32 +8,34 @@ workflow:
     - id: gather-state
       role: system
       intent: "Analyze current work state: task in progress, pipeline phase, modified files, session commits."
-      commands: [git status, git log --oneline -10]
       produces: [work-state, modified-files, session-commits]
     - id: update-session
       role: system
-      intent: "Write current state, decisions, and next steps to SESSION.md."
+      intent: "Write ephemeral state (task, branch, phase, next steps) to SESSION.md."
       requires: [work-state, modified-files, session-commits]
       produces: [session-update]
       gate: true
+    - id: save-memory
+      role: system
+      intent: "Save durable learnings (decisions, lessons, references) to Claude Code memory files if any emerged this session."
+      requires: [session-update]
+      produces: [memory-update]
     - id: commit-wip
       role: system
       intent: "Create WIP checkpoint commit if uncommitted changes exist."
-      commands: [git add -A, git commit -m "wip: session paused"]
       requires: [modified-files]
       produces: [wip-commit]
-      condition: has-uncommitted-changes
     - id: confirm
       role: system
-      intent: "Confirm SESSION.md updated, WIP committed, safe to close."
-      requires: [session-update]
+      intent: "Confirm SESSION.md updated, memory saved, WIP committed, safe to close."
+      requires: [session-update, memory-update]
       produces: [confirmation]
       gate: true
 ---
 
 # Session End
 
-Saves the current work state to SESSION.md so it can be resumed in the next session. Run this skill before closing your work session.
+Saves the current work state to SESSION.md (ephemeral) and durable learnings to Claude Code memory (long-term). Run this skill before closing your work session.
 
 ## When to use
 
@@ -44,6 +46,17 @@ Saves the current work state to SESSION.md so it can be resumed in the next sess
 
 `/session-end`
 
+## Two persistence layers
+
+This skill writes to two complementary systems:
+
+| Layer | File | What goes here | Lifespan |
+| --- | --- | --- | --- |
+| **SESSION.md** | `SESSION.md` (project root) | Where you stopped: task, branch, phase, next steps | Overwritten each session |
+| **Claude Code Memory** | `.claude/projects/*/memory/*.md` | What you learned: decisions, lessons, references | Persists across sessions |
+
+**Rule of thumb:** if removing the information would make it hard to resume tomorrow, it goes in SESSION.md. If removing it would make you repeat a mistake in two weeks, it goes in memory.
+
 ## Process
 
 ### Step 1 — Gather current state
@@ -55,28 +68,61 @@ Analyze the current work state:
 - What files were modified (via `git status`)
 - What commits were made in this session
 
-### Step 2 — Update SESSION.md
+### Step 2 — Update SESSION.md (ephemeral state)
 
 Update SESSION.md with the following information:
 
 - **Date:** current date
 - **Task in progress:** task name or "none"
 - **GitHub Issue:** associated issue URL (if it exists)
-- **Active agent:** last agent used or "none"
+- **Branch:** current branch name
 - **State:** concrete description of where the work left off
 
-**Relevant context:**
-
-- Decisions made in this session
-- Problems encountered and how they were resolved
-- Important information for resuming
-
 **Next steps:**
 
 - The 2-3 most important concrete actions when resuming
 - Suggested skill to continue (e.g., "run /build-feature to continue from Phase 4")
 
-### Step 3 — Commit WIP if uncommitted work exists
+**Technical context:**
+
+- Version, test count, agent/skill counts — a snapshot that helps orient the next session
+
+Do NOT put decisions, lessons, or references in SESSION.md — those belong in memory.
+
+### Step 3 — Save durable learnings to Claude Code memory
+
+Review the session for knowledge worth preserving long-term. For each item, write a memory file using the Write tool to the project's memory directory.
+
+**What to save (only if something emerged this session):**
+
+- **Decisions with lasting impact** → memory type `project`. Example: "Chose recursive execution for delegation because plan-expansion would break retry semantics on parent steps."
+- **Lessons learned / corrections** → memory type `feedback`. Example: "npm audit fix resolves transitive vulnerabilities — don't chase individual Dependabot PRs when a single fix covers all."
+- **New external references** → memory type `reference`. Example: "Release workflow logs at gh run view --job=ID --log."
+
+**What NOT to save to memory:**
+
+- Current task state (goes in SESSION.md)
+- Code patterns or architecture (derivable from code)
+- Git history (derivable from git log)
+
+Use the standard memory frontmatter format:
+
+```markdown
+---
+name: short-kebab-slug
+description: "one-line summary"
+metadata:
+  type: project|feedback|reference
+---
+
+Content with **Why:** and **How to apply:** lines for feedback/project types.
+```
+
+Update `MEMORY.md` index if new memory files were created.
+
+If nothing durable emerged this session, skip this step — not every session produces long-term learnings.
+
+### Step 4 — Commit WIP if uncommitted work exists
 
 If there are uncommitted changes, create a checkpoint commit:
 
@@ -87,25 +133,26 @@ git commit -m "wip: session paused — [brief description of current state]"
 
 This ensures no work is lost between sessions. Never leave uncommitted changes across session boundaries.
 
+### Step 5 — Confirm
+
+Confirm to the user:
+
+- SESSION.md updated with the current state
+- Memory files saved (list which ones, if any)
+- WIP committed (if applicable)
+- Next steps recorded
+- You can safely close the session
+
 ## Example Session
 
 ```text
 User: /session-end
 
 Saving session state...
-Task: user-preferences
-Phase: 4 — Implementation (in progress)
-Files modified: 3 files
-WIP committed: wip: session paused — user-preferences phase 4
-
-SESSION.md updated. Safe to close.
-```
 
-### Step 4 — Confirm
-
-Confirm to the user:
+SESSION.md: task=executor-v1.2, branch=feature/executor-v1.2, phase=complete
+Memory: saved feedback/delegation-approach.md (recursive > plan-expansion)
+WIP: no uncommitted changes
 
-- SESSION.md updated with the current state
-- WIP committed (if applicable)
-- Next steps recorded
-- You can safely close the session
+Safe to close. Next session: create PR and update docs.
+```

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

@@ -7,24 +7,22 @@ workflow:
   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]
+      intent: "Read CLAUDE.md, SESSION.md, PROJECT.md, and Claude Code memory (MEMORY.md index + relevant memory files)."
+      produces: [claude-md, session-md, project-md, memory-context]
     - 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]
+      intent: "Display unified summary: ephemeral state from SESSION.md + durable context from memory."
+      requires: [session-md, memory-context, resumable-branches]
       produces: [state-display]
       gate: true
     - id: suggest-continuation
       role: system
-      intent: "Suggest appropriate skill to continue based on current state."
+      intent: "Suggest appropriate skill to continue based on current state and memory context."
       requires: [state-display]
       produces: [suggested-action]
       gate: true
@@ -38,7 +36,7 @@ workflow:
 
 # Session Start
 
-Loads the project context and resumes work from where it was left off in the previous session. This is the first skill you should run when starting a work session.
+Loads project context from two sources — SESSION.md (ephemeral work state) and Claude Code memory (durable learnings) — to resume where you left off. This is the first skill you should run when starting a work session.
 
 ## When to use
 
@@ -49,16 +47,36 @@ Loads the project context and resumes work from where it was left off in the pre
 
 `/session-start`
 
+## Two context sources
+
+| Source | What it provides | Example |
+| --- | --- | --- |
+| **SESSION.md** | Where you stopped: task, branch, phase, next steps | "Implementing executor v1.2, branch feature/executor, tests passing, next: write delegation tests" |
+| **Claude Code Memory** | What you know: decisions, lessons, references | "Chose recursive execution for delegation because plan-expansion breaks retry semantics" |
+
+Both are read and combined into a unified summary.
+
 ## Process
 
 ### Step 1 — Load context
 
-Read the Guild state files:
+Read from both persistence layers:
+
+**Ephemeral state (SESSION.md):**
 
 - `CLAUDE.md` — project instructions, conventions, and rules
 - `SESSION.md` — last session state, task in progress, next steps
 - `PROJECT.md` — project identity, stack, configured agents
 
+**Durable context (Claude Code memory):**
+
+- Read `MEMORY.md` index from the project's memory directory
+- Load relevant memory files, especially:
+  - `project` type — active decisions, ongoing initiatives
+  - `feedback` type — lessons learned, corrections, validated approaches
+
+If either source is missing (no SESSION.md or no memory files), work with what's available.
+
 ### Step 2 — Detect resumable work
 
 Check for `wip:` checkpoint commits on active branches:
@@ -71,16 +89,23 @@ done
 
 If `wip:` commits are found, present them to the user with the phase they were in when interrupted.
 
-### Step 3 — Present state
+### Step 3 — Present unified state
+
+Show a combined summary from both sources:
 
-Show a summary of the previous session:
+**From SESSION.md (where you stopped):**
 
 - Date of the last session
 - Task in progress (if any)
-- State where the work left off
-- Decisions made previously
+- Branch and pipeline phase
 - Recorded next steps
-- **Resumable pipelines** (if wip: commits detected)
+- Resumable pipelines (if wip: commits detected)
+
+**From memory (what you know):**
+
+- Recent project decisions that affect current work
+- Relevant lessons or corrections from past sessions
+- References to external systems or resources
 
 ### Step 4 — Suggest how to continue
 
@@ -89,12 +114,11 @@ If there is a task in progress:
 - Show the task state
 - Suggest continuing with the appropriate skill (e.g., `/build-feature` if in implementation)
 - Show the next steps recorded in SESSION.md
+- Flag any memory entries that are relevant to the current task
 
 If there is no task in progress, suggest options:
 
 - `/build-feature [description]` — to implement a new feature
-- `/new-feature [name]` — to prepare the environment for a feature
-- `/status` — to see the general project state
 - `/council [question]` — to debate an important decision
 
 ### Step 5 — Update session
@@ -107,9 +131,16 @@ Update SESSION.md with the current date to record that the session has started.
 User: /session-start
 
 Loading context...
-Last session: 2026-02-22
-Task in progress: user-preferences (Phase 4 — Implementation)
-Resumable: feature/user-preferences (wip: phase 3 complete)
 
-Suggested: Continue with /build-feature to resume implementation.
+SESSION.md: Last session 2026-05-25
+  Task: executor-v1.2 (complete)
+  Branch: main (clean)
+  Next steps: 1. MCP server  2. Agent Teams v2
+
+Memory: 3 entries loaded
+  - project: "v1.5.0 shipped — 7 agents, 5-phase pipeline"
+  - feedback: "Recursive execution for delegation > plan-expansion"
+  - feedback: "npm audit fix resolves transitive vulns"
+
+Suggested: Pick a backlog item — /build-feature or /council to decide.
 ```

package/src/utils/eval-runner.js

@@ -8,7 +8,7 @@
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { parseSkill } from './workflow-parser.js';
+import { parseSkill } from './skill-parser.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', 'templates', 'skills');
@@ -63,13 +63,7 @@ export function evaluateAssertion(workflow, assertion) {
         : { passed: false, evidence: `Step "${stepId}" requires [${step.requires.join(', ')}], missing "${dep}"` };
     }
 
-    case 'step-parallel': {
-      const step = workflow.steps.find(s => s.id === args);
-      if (!step) return { passed: false, evidence: `Step "${args}" not found` };
-      return step.parallel && step.parallel.length > 0
-        ? { passed: true, evidence: `Step "${args}" is parallel with [${step.parallel.join(', ')}]` }
-        : { passed: false, evidence: `Step "${args}" has no parallel group` };
-    }
+
 
     case 'gate-exists': {
       const step = workflow.steps.find(s => s.id === args);

package/src/utils/generators.js

@@ -137,15 +137,14 @@ ${workspaceSection}
 ## Available skills
 - /guild-specialize  — enrich CLAUDE.md by exploring the actual project
 - /build-feature     — full development pipeline
-- /new-feature       — create branch and scaffold for a feature
 - /create-pr         — create a structured pull request from current branch
 - /council           — debate decisions with multiple agents
-- /review            — code review on the current diff
 - /qa-cycle          — QA + bugfix cycle
-- /status            — view project status
-- /dev-flow          — view current pipeline phase
 - /session-start     — load context and resume work
 - /session-end       — save state to SESSION.md
+- /tdd               — TDD red-green-refactor discipline
+- /debug             — systematic 4-phase debugging
+- /re-specialize     — incremental re-specialization of auto-generated zones
 `;
 
   writeFileSync('CLAUDE.md', content, 'utf8');

package/src/utils/skill-parser.js

@@ -0,0 +1,83 @@
+/**
+ * skill-parser.js — Parses SKILL.md frontmatter for the eval system.
+ *
+ * Extracted from workflow-parser.js. Contains only the parsing functions
+ * needed by eval-runner.js and trigger-runner.js.
+ */
+
+import YAML from 'yaml';
+
+/**
+ * Extracts the raw YAML frontmatter string and body from markdown content.
+ * @param {string} content - Raw markdown content
+ * @returns {{ yaml: string, body: string } | null} Null if no frontmatter found
+ */
+export function extractFrontmatterBlock(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  return {
+    yaml: match[1],
+    body: content.slice(match[0].length).trim(),
+  };
+}
+
+/**
+ * Parses YAML frontmatter with full nested structure support.
+ * @param {string} yamlString - Raw YAML frontmatter
+ * @returns {object} Parsed frontmatter object
+ */
+export function parseYamlFrontmatter(yamlString) {
+  return YAML.parse(yamlString) || {};
+}
+
+function normalizeStep(raw) {
+  return {
+    id: raw.id,
+    role: raw.role,
+    intent: raw.intent,
+    requires: raw.requires || [],
+    produces: raw.produces || [],
+    modelTier: raw['model-tier'] || undefined,
+    gate: raw.gate || false,
+  };
+}
+
+/**
+ * Parses a SKILL.md file and extracts the skill definition.
+ * @param {string} content - Raw content of SKILL.md
+ * @returns {{ name: string, description: string, userInvocable: boolean, workflow: object|null, body: string }}
+ */
+export function parseSkill(content) {
+  const block = extractFrontmatterBlock(content);
+  if (!block) {
+    return {
+      name: '',
+      description: '',
+      userInvocable: false,
+      workflow: null,
+      body: content,
+    };
+  }
+
+  const frontmatter = parseYamlFrontmatter(block.yaml);
+
+  const skill = {
+    name: frontmatter.name || '',
+    description: frontmatter.description || '',
+    userInvocable: frontmatter['user-invocable'] === true,
+    workflow: null,
+    body: block.body,
+  };
+
+  if (frontmatter.workflow) {
+    const raw = frontmatter.workflow;
+    skill.workflow = {
+      version: raw.version,
+      steps: Array.isArray(raw.steps)
+        ? raw.steps.map(normalizeStep)
+        : [],
+    };
+  }
+
+  return skill;
+}

package/src/utils/trigger-runner.js

@@ -6,7 +6,7 @@ import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { rankSkills } from './trigger-matcher.js';
-import { extractFrontmatterBlock, parseYamlFrontmatter } from './workflow-parser.js';
+import { extractFrontmatterBlock, parseYamlFrontmatter } from './skill-parser.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', 'templates', 'skills');

package/src/commands/logs.js

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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}`);
-}