guild-agents 1.5.0 → 2.0.0

package/src/templates/skills/guild-specialize/SKILL.md

@@ -8,12 +8,10 @@ workflow:
     - id: read-base
       role: system
       intent: "Read CLAUDE.md, PROJECT.md, and SESSION.md for current Guild configuration."
-      commands: [cat CLAUDE.md, cat PROJECT.md, cat SESSION.md]
       produces: [claude-md, project-md, session-md]
     - id: explore-project
       role: system
       intent: "Scan project structure, dependency files, configs, CI, and documentation to detect stack and architecture."
-      commands: [ls -R src/, cat package.json]
       produces: [detected-stack, detected-architecture, detected-conventions]
       gate: true
     - id: enrich-claude-md
@@ -37,7 +35,6 @@ workflow:
     - id: commit-enrichment
       role: system
       intent: "Commit enriched CLAUDE.md and agent files as an atomic commit."
-      commands: [git add CLAUDE.md .claude/agents/*.md, git commit]
       requires: [enriched-claude-md, specialized-agents]
       produces: [enrichment-commit]
 ---
@@ -165,7 +162,7 @@ Architecture:
 Updated agents:
 - [list of agents with their applied specialization]
 
-Run /status to see the full state.
+Run /session-start to see the full state.
 ```
 
 ### Step 6 — Commit enrichment immediately
@@ -202,7 +199,7 @@ Agents updated:
 - developer.md: Specialized for Next.js + TypeScript
 - qa.md: Configured for Vitest + Playwright
 
-Run /status to see the full state.
+Run /session-start to see the full state.
 ```
 
 ## Important Notes

package/src/templates/skills/qa-cycle/SKILL.md

@@ -8,7 +8,6 @@ workflow:
     - id: gate-pre-qa
       role: system
       intent: "Run project tests and lint before QA validation."
-      commands: [npm test, npm run lint]
       gate: true
       produces: [test-result, lint-result]
     - id: qa-validate
@@ -17,21 +16,15 @@ workflow:
       requires: [acceptance-criteria, test-result, lint-result]
       produces: [qa-report]
       model-tier: execution
-      retry:
-        max: 3
-        on: has-bugs
     - id: bugfix
       role: bugfix
       intent: "Diagnose and fix bugs reported by QA. Run tests after fixing."
       requires: [qa-report]
       produces: [bugfix-result]
       model-tier: execution
-      condition: step.qa-validate.has-bugs
-      on-failure: goto:qa-validate
     - id: gate-post-qa
       role: system
       intent: "Run project tests and lint after QA cycle completes."
-      commands: [npm test, npm run lint]
       gate: true
       produces: [final-test-result, final-lint-result]
 ---

package/src/templates/skills/re-specialize/SKILL.md

@@ -8,12 +8,10 @@ workflow:
     - id: read-current
       role: system
       intent: "Read current CLAUDE.md and agent files to identify existing zones."
-      commands: [cat CLAUDE.md]
       produces: [current-claude-md, current-agents]
     - id: explore-project
       role: system
       intent: "Scan project for current stack, dependencies, architecture, conventions."
-      commands: [ls -R src/, cat package.json]
       produces: [detected-stack, detected-architecture, detected-conventions]
       gate: true
     - id: check-zones
@@ -43,7 +41,6 @@ workflow:
     - id: commit
       role: system
       intent: "Commit re-specialized files."
-      commands: [git add CLAUDE.md .claude/agents/*.md, git commit -m "chore: re-specialize via guild-re-specialize"]
       requires: [updated-claude-md, updated-agents, confirmation]
       produces: [re-specialize-commit]
 ---

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.');
-}