guild-agents 1.1.0 → 1.3.0

package/README.md

@@ -62,7 +62,7 @@ Six phases: **evaluate**, **specify**, **plan**, **implement**, **review**, **va
 
 ## Skills Reference
 
-All 11 skills, grouped by function:
+All 15 skills, grouped by function:
 
 | Skill | Group | Description |
 | --- | --- | --- |
@@ -72,7 +72,11 @@ All 11 skills, grouped by function:
 | `/council` | Decision | Multi-perspective deliberation on a decision or feature |
 | `/review` | Quality | Code review on the current diff |
 | `/qa-cycle` | Quality | QA and bugfix loop until clean |
+| `/tdd` | Discipline | TDD red-green-refactor cycle |
+| `/debug` | Discipline | Systematic 4-phase debugging |
+| `/verify` | Discipline | Evidence-before-claims verification |
 | `/guild-specialize` | Context | Explore codebase, enrich CLAUDE.md with real conventions |
+| `/re-specialize` | Context | Incremental update of auto-generated CLAUDE.md zones |
 | `/session-start` | Context | Load context and resume work |
 | `/session-end` | Context | Save state to SESSION.md |
 | `/status` | Context | Project and session state overview |
@@ -89,6 +93,9 @@ 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)
+guild workspace init <name> <members...>  # Create a workspace
+guild workspace add <path>                # Add a member repo
+guild workspace status                    # Show workspace state
 ```
 
 ## Under the Hood

package/bin/guild.js

@@ -168,4 +168,88 @@ logsCmd
     }
   });
 
+// guild workspace
+const workspaceCmd = program
+  .command('workspace')
+  .description('Manage multi-repo workspaces');
+
+// guild workspace init
+workspaceCmd
+  .command('init')
+  .description('Initialize a workspace in the current directory')
+  .argument('<name>', 'Workspace name')
+  .argument('<members...>', 'Paths to member repos (e.g., ./backend ./frontend)')
+  .action(async (name, members) => {
+    try {
+      const { createWorkspaceFile } = await import('../src/commands/workspace.js');
+      await createWorkspaceFile(name, members);
+      console.log(`Workspace "${name}" created with ${members.length} member(s).`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild workspace add
+workspaceCmd
+  .command('add')
+  .description('Add a member repo to the workspace')
+  .argument('<path>', 'Path to the member repo')
+  .action(async (memberPath) => {
+    try {
+      const { addWorkspaceMember } = await import('../src/commands/workspace.js');
+      await addWorkspaceMember(memberPath);
+      console.log(`Added "${memberPath}" to workspace.`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild workspace status
+workspaceCmd
+  .command('status')
+  .description('Show workspace members and their state')
+  .action(async () => {
+    try {
+      const { getWorkspaceStatus } = await import('../src/commands/workspace.js');
+      const status = await getWorkspaceStatus();
+      console.log(`Workspace: ${status.name}`);
+      for (const m of status.members) {
+        const state = m.initialized ? 'initialized' : 'not initialized';
+        console.log(`  ${m.name} (${m.path}) — ${state}`);
+      }
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild workspace run
+workspaceCmd
+  .command('run')
+  .description('Run a command in a workspace member repo')
+  .argument('[member]', 'Member name (or omit with --all)')
+  .argument('[preset]', 'Preset command: test, lint, build')
+  .option('--cmd <command>', 'Custom command to run')
+  .option('--all', 'Run in all workspace members')
+  .action(async (member, preset, options) => {
+    try {
+      const { runWorkspaceCommand } = await import('../src/commands/workspace.js');
+      const results = runWorkspaceCommand(member, preset, options);
+      for (const r of results) {
+        const icon = r.status === 'passed' ? '\u2705' : '\u274C';
+        console.log(`${icon} ${r.member}: ${r.status} (${r.duration}ms)`);
+        if (r.status === 'failed' && r.output) {
+          console.log(r.output);
+        }
+      }
+      const failed = results.filter(r => r.status === 'failed');
+      if (failed.length > 0) process.exit(1);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guild-agents",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Specification-driven development CLI for Claude Code — think before you build",
   "type": "module",
   "files": [
@@ -28,7 +28,10 @@
     "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"
+    "publish:promote-beta": "npm dist-tag add guild-agents@$(node --input-type=commonjs -p \"require('./package.json').version\") beta",
+    "eval": "node scripts/run-evals.js",
+    "eval:build-feature": "node scripts/run-evals.js build-feature",
+    "eval:council": "node scripts/run-evals.js council"
   },
   "keywords": [
     "claude",

package/src/commands/init.js

@@ -14,11 +14,18 @@ import chalk from 'chalk';
 import { existsSync } from 'fs';
 import { generateProjectMd, generateSessionMd, generateClaudeMd } from '../utils/generators.js';
 import { copyTemplates, getAgentNames, getSkillNames } from '../utils/files.js';
+import { loadWorkspace } from '../utils/workspace.js';
 
 export async function runInit() {
   console.log('');
   p.intro(chalk.bold.cyan('Guild v1 — New project'));
 
+  // Detect workspace membership
+  const workspace = loadWorkspace();
+  if (workspace) {
+    p.log.info(chalk.gray(`Workspace detected: ${workspace.name} (${workspace.root})`));
+  }
+
   // Check for existing installation
   if (existsSync('.claude/agents')) {
     const overwrite = await p.confirm({
@@ -107,7 +114,7 @@ export async function runInit() {
   try {
     await copyTemplates();
     spinner.message('Generating CLAUDE.md...');
-    await generateClaudeMd(projectData);
+    await generateClaudeMd(projectData, workspace, name);
 
     spinner.message('Generating PROJECT.md...');
     await generateProjectMd(projectData);

package/src/commands/workspace.js

@@ -0,0 +1,92 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+import { findWorkspaceRoot, loadWorkspace, runInMember, PRESET_COMMANDS, WORKSPACE_FILE } from '../utils/workspace.js';
+
+export async function createWorkspaceFile(name, memberPaths) {
+  const members = memberPaths.map(p => ({
+    name: basename(p),
+    path: p,
+  }));
+
+  const config = {
+    name,
+    members,
+    shared: {
+      agents: '.guild/agents',
+      skills: '.guild/skills',
+    },
+  };
+
+  writeFileSync(WORKSPACE_FILE, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  mkdirSync(join('.guild', 'agents'), { recursive: true });
+  mkdirSync(join('.guild', 'skills'), { recursive: true });
+}
+
+export async function addWorkspaceMember(memberPath) {
+  const root = findWorkspaceRoot();
+  if (!root) throw new Error('No workspace found. Run `guild workspace init` first.');
+
+  const filePath = join(root, WORKSPACE_FILE);
+  const config = JSON.parse(readFileSync(filePath, 'utf8'));
+  const name = basename(memberPath);
+
+  if (config.members.some(m => m.path === memberPath || m.name === name)) {
+    throw new Error(`"${name}" is already a member of this workspace.`);
+  }
+
+  config.members.push({ name, path: memberPath });
+  writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+export function runWorkspaceCommand(memberName, preset, options) {
+  const workspace = loadWorkspace();
+  if (!workspace) throw new Error('No workspace found. Run `guild workspace init` first.');
+
+  // Resolve command
+  let cmd, args;
+  if (options.cmd) {
+    const parts = options.cmd.split(/\s+/);
+    cmd = parts[0];
+    args = parts.slice(1);
+  } else if (preset && PRESET_COMMANDS[preset]) {
+    ({ cmd, args } = PRESET_COMMANDS[preset]);
+  } else {
+    throw new Error(`Unknown command: "${preset}". Use test, lint, build, or --cmd "...".`);
+  }
+
+  // Resolve members
+  let targets;
+  if (options.all) {
+    targets = workspace.members;
+  } else {
+    const member = workspace.members.find(m => m.name === memberName);
+    if (!member) {
+      const available = workspace.members.map(m => m.name).join(', ');
+      throw new Error(`Member "${memberName}" not found. Available: ${available}`);
+    }
+    targets = [member];
+  }
+
+  // Execute sequentially, collect all
+  const results = [];
+  for (const target of targets) {
+    results.push(runInMember(target, cmd, args));
+  }
+  return results;
+}
+
+export async function getWorkspaceStatus() {
+  const root = findWorkspaceRoot();
+  if (!root) throw new Error('No workspace found. Run `guild workspace init` first.');
+
+  const filePath = join(root, WORKSPACE_FILE);
+  const config = JSON.parse(readFileSync(filePath, 'utf8'));
+
+  const members = config.members.map(m => {
+    const absPath = join(root, m.path);
+    const initialized = existsSync(join(absPath, '.claude'));
+    return { ...m, absolutePath: absPath, initialized };
+  });
+
+  return { name: config.name, root, members };
+}

package/src/templates/skills/build-feature/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "skill": "build-feature",
+  "evals": [
+    {
+      "id": "bf-has-core-phases",
+      "description": "Plan contains evaluate, specify, design, implement phases",
+      "expectations": [
+        { "text": "Has evaluate step", "assertion": "step-exists:evaluate" },
+        { "text": "Has specify step", "assertion": "step-exists:specify" },
+        { "text": "Has design step", "assertion": "step-exists:design" },
+        { "text": "Has implement step", "assertion": "step-exists:implement" }
+      ]
+    },
+    {
+      "id": "bf-has-quality-phases",
+      "description": "Plan contains review, QA, and completion phases",
+      "expectations": [
+        { "text": "Has review step", "assertion": "step-exists:review" },
+        { "text": "Has QA phase", "assertion": "step-exists:qa-phase" },
+        { "text": "Has completion step", "assertion": "step-exists:completion" }
+      ]
+    },
+    {
+      "id": "bf-advisor-uses-reasoning",
+      "description": "Advisor (evaluate) uses reasoning tier",
+      "expectations": [
+        { "text": "Evaluate uses reasoning tier", "assertion": "step-model-tier:evaluate:reasoning" }
+      ]
+    },
+    {
+      "id": "bf-developer-uses-execution",
+      "description": "Developer (implement) uses execution tier",
+      "expectations": [
+        { "text": "Implement uses execution tier", "assertion": "step-model-tier:implement:execution" }
+      ]
+    },
+    {
+      "id": "bf-gates-exist",
+      "description": "Quality gates exist at pre-review and final",
+      "expectations": [
+        { "text": "Pre-review gate exists", "assertion": "gate-exists:gate-pre-review" },
+        { "text": "Final gate exists", "assertion": "gate-exists:gate-final" }
+      ]
+    },
+    {
+      "id": "bf-minimum-steps",
+      "description": "Plan has at least 10 steps",
+      "expectations": [
+        { "text": "At least 10 steps", "assertion": "step-count:10" }
+      ]
+    }
+  ]
+}

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

@@ -11,24 +11,30 @@ workflow:
       requires: [user-question]
       produces: [council-type, participant-roles]
       gate: true
+    - id: workspace-context
+      role: system
+      intent: "Detect workspace membership. If in a workspace, collect context from sibling repos (CLAUDE.md, PROJECT.md, SESSION.md) and build workspace context block."
+      requires: [council-type]
+      produces: [workspace-context]
+      condition: in-workspace
     - id: agent-1
       role: dynamic
       intent: "Analyze the question from specialized perspective. State position with concrete arguments."
-      requires: [user-question, council-type]
+      requires: [user-question, council-type, workspace-context]
       produces: [perspective-1]
       model-tier: reasoning
       parallel: [agent-2, agent-3]
     - id: agent-2
       role: dynamic
       intent: "Analyze the question from specialized perspective. State position with concrete arguments."
-      requires: [user-question, council-type]
+      requires: [user-question, council-type, workspace-context]
       produces: [perspective-2]
       model-tier: reasoning
       parallel: [agent-1, agent-3]
     - id: agent-3
       role: dynamic
       intent: "Analyze the question from specialized perspective. State position with concrete arguments."
-      requires: [user-question, council-type]
+      requires: [user-question, council-type, workspace-context]
       produces: [perspective-3]
       model-tier: reasoning
       parallel: [agent-1, agent-2]
@@ -114,12 +120,23 @@ Analyze the user's question and determine which council type applies:
 
 ### Step 2 — Convene agents
 
+**Workspace detection:** Before invoking agents, check if the project is inside a workspace:
+
+1. Look for a `guild-workspace.json` file by searching upward from the project root
+2. If found, load the workspace config and identify which member this project is
+3. Read CLAUDE.md, PROJECT.md, and SESSION.md from each sibling member repo
+4. Build a workspace context block with:
+   - Workspace name
+   - Each sibling's stack, structure summary, and current task
+   - Absolute paths so the agent can read any sibling file for deeper analysis
+
 Invoke the 3 corresponding agents IN PARALLEL using Task tool with `model: "opus"` (all council agents use reasoning tier). Each agent:
 
 1. Reads their `.claude/agents/[name].md` file to assume their role
 2. Reads `CLAUDE.md` and `SESSION.md` for project context
-3. Analyzes the question from their specialized perspective
-4. States their position with concrete arguments
+3. **If in a workspace:** receives the workspace context block and considers cross-repo impact as part of their analysis. They may read files from sibling repos using the provided paths.
+4. Analyzes the question from their specialized perspective
+5. States their position with concrete arguments
 
 ### Step 3 — Present debate
 
@@ -191,7 +208,11 @@ Example:
 Task tool with:
   subagent_type: "general-purpose"
   model: "opus"
-  prompt: "Read .claude/agents/tech-lead.md and assume that role. Then: [debate question]"
+  prompt: "Read .claude/agents/tech-lead.md and assume that role. Then: [debate question]
+
+[If in workspace, append:]
+## Workspace context
+[workspace context block from Step 2]"
 ```
 
 The `model` parameter is resolved from the step's `model-tier`: all council agents use reasoning→`"opus"`.

package/src/templates/skills/council/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill": "council",
+  "evals": [
+    {
+      "id": "council-three-parallel-agents",
+      "description": "Council has 3 agent steps in parallel",
+      "expectations": [
+        { "text": "Agent-1 exists", "assertion": "step-exists:agent-1" },
+        { "text": "Agent-2 exists", "assertion": "step-exists:agent-2" },
+        { "text": "Agent-3 exists", "assertion": "step-exists:agent-3" },
+        { "text": "Agent-1 is parallel", "assertion": "step-parallel:agent-1" },
+        { "text": "Agent-2 is parallel", "assertion": "step-parallel:agent-2" },
+        { "text": "Agent-3 is parallel", "assertion": "step-parallel:agent-3" }
+      ]
+    },
+    {
+      "id": "council-agents-use-reasoning",
+      "description": "All council agents use reasoning tier",
+      "expectations": [
+        { "text": "Agent-1 uses reasoning", "assertion": "step-model-tier:agent-1:reasoning" },
+        { "text": "Agent-2 uses reasoning", "assertion": "step-model-tier:agent-2:reasoning" },
+        { "text": "Agent-3 uses reasoning", "assertion": "step-model-tier:agent-3:reasoning" }
+      ]
+    },
+    {
+      "id": "council-synthesize-gate",
+      "description": "Synthesize step exists with gate",
+      "expectations": [
+        { "text": "Synthesize step exists", "assertion": "step-exists:synthesize" },
+        { "text": "Synthesize has gate", "assertion": "gate-exists:synthesize" }
+      ]
+    },
+    {
+      "id": "council-workspace-context",
+      "description": "Workspace context step exists with condition",
+      "expectations": [
+        { "text": "Workspace-context step exists", "assertion": "step-exists:workspace-context" }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,145 @@
+---
+name: debug
+description: "Discipline skill — systematic debugging process. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes."
+user-invocable: true
+---
+
+# Systematic Debugging
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes.
+
+## Usage
+
+`/debug`
+
+Invoke this skill when encountering any bug, test failure, or unexpected behavior. Follow the four phases in order.
+
+## When to use
+
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+
+## The Iron Law
+
+```text
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## The Four Phases
+
+Complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - If not reproducible, gather more data — don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+
+4. **Gather Evidence in Multi-Component Systems**
+   - Log what data enters each component boundary
+   - Log what data exits each component boundary
+   - Verify environment/config propagation
+   - Run once to gather evidence showing WHERE it breaks
+   - THEN investigate that specific component
+
+5. **Trace Data Flow**
+   - Where does the bad value originate?
+   - What called this with the bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+1. **Find Working Examples** — locate similar working code in the same codebase
+2. **Compare Against References** — read reference implementations COMPLETELY, don't skim
+3. **Identify Differences** — list every difference between working and broken, however small
+4. **Understand Dependencies** — what components, settings, environment does it need?
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form Single Hypothesis** — "I think X is the root cause because Y"
+2. **Test Minimally** — smallest possible change, one variable at a time
+3. **Verify** — did it work? Yes = Phase 4. No = new hypothesis. DON'T stack fixes.
+
+### Phase 4: Implementation
+
+1. **Create Failing Test Case** — simplest possible reproduction, automated if possible. Use `/tdd` for proper failing tests.
+2. **Implement Single Fix** — address the root cause, ONE change at a time, no "while I'm here" improvements.
+3. **Verify Fix** — test passes? No other tests broken? Issue actually resolved? Use `/verify` before claiming done.
+
+**If fix doesn't work:**
+
+- If < 3 attempts: return to Phase 1, re-analyze with new information
+- **If >= 3 attempts: STOP and question the architecture**
+
+**3+ failed fixes indicate an architectural problem:**
+
+- Each fix reveals new coupling in different places
+- Fixes require massive refactoring
+- Each fix creates new symptoms elsewhere
+- Discuss with the user before attempting more fixes
+
+## Red Flags - STOP and Follow Process
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" (when already tried 2+)
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse                                    | Reality                                                                  |
+| ----------------------------------------- | ------------------------------------------------------------------------ |
+| "Issue is simple, don't need process"     | Simple issues have root causes too. Process is fast for simple bugs.     |
+| "Emergency, no time for process"          | Systematic debugging is FASTER than guess-and-check thrashing.           |
+| "Just try this first, then investigate"   | First fix sets the pattern. Do it right from the start.                  |
+| "I'll write test after confirming fix"    | Untested fixes don't stick. Test first proves it.                        |
+| "Multiple fixes at once saves time"       | Can't isolate what worked. Causes new bugs.                              |
+| "I see the problem, let me fix it"        | Seeing symptoms is not understanding root cause.                         |
+
+## Quick Reference
+
+| Phase                  | Key Activities                                         | Success Criteria            |
+| ---------------------- | ------------------------------------------------------ | --------------------------- |
+| **1. Root Cause**      | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY     |
+| **2. Pattern**         | Find working examples, compare                         | Identify differences        |
+| **3. Hypothesis**      | Form theory, test minimally                            | Confirmed or new hypothesis |
+| **4. Implementation**  | Create test, fix, verify                               | Bug resolved, tests pass    |
+
+## Related Skills
+
+- `/tdd` — TDD cycle for creating failing test cases in Phase 4
+- `/verify` — verification before claiming the fix is complete

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

@@ -113,6 +113,13 @@ Invoke the Tech Lead agent using Task tool with `model: "opus"` (reasoning tier)
 - **Visible limitations and technical debt**: outdated dependencies, TODOs found
 - **Useful project commands**: detected npm/make/cargo scripts
 
+CLAUDE.md now uses zone markers (`<!-- guild:auto-start:ID -->` / `<!-- guild:auto-end:ID -->`) to delimit auto-generated sections. When enriching:
+
+- Replace content BETWEEN the markers, preserving the markers themselves
+- The following zones exist: `structure`, `architecture`, `conventions`, `env-vars`
+- Do NOT modify content outside of zone markers (user-owned sections)
+- If markers are missing (legacy project), replace `[PENDING: guild-specialize]` placeholders directly
+
 ### Step 4 — Specialize agents
 
 Invoke the Tech Lead agent using Task tool with `model: "sonnet"` (execution tier) to add project-specific context for each agent in `.claude/agents/*.md`:
@@ -127,6 +134,19 @@ Invoke the Tech Lead agent using Task tool with `model: "sonnet"` (execution tie
 - **db-migration.md**: ORM, migration tool, current schema (if applicable)
 - **platform-expert.md**: Claude Code version, known permission bugs, hook configuration
 
+When specializing agents, append a zone at the bottom of each agent file:
+
+```markdown
+<!-- guild:auto-start:agent-context -->
+## Project-Specific Context
+- Stack: [detected stack]
+- Architecture: [detected patterns]
+- Conventions: [detected conventions]
+<!-- guild:auto-end:agent-context -->
+```
+
+This zone allows `guild-re-specialize` to update agent context later without touching the agent's core role definition.
+
 Use the `Task` tool with `model: "sonnet"` to invoke each agent by reading their `.claude/agents/[name].md` if you need a specialized perspective to enrich their configuration.
 
 The `model` parameter is resolved from the step's `model-tier`: reasoning→`"opus"`, execution→`"sonnet"`. System/gate steps run inline (no Task tool).