guild-agents 1.1.0 → 1.3.0

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

@@ -0,0 +1,153 @@
+---
+name: re-specialize
+description: "Incremental re-specialization — re-scans the project and updates only auto-generated zones in CLAUDE.md and agents"
+user-invocable: true
+workflow:
+  version: 1
+  steps:
+    - 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
+      role: system
+      intent: "Check if CLAUDE.md has guild zone markers. If not, offer to inject them."
+      requires: [current-claude-md]
+      produces: [zone-status]
+      gate: true
+    - id: regenerate-zones
+      role: tech-lead
+      intent: "Generate new content for each auto zone based on fresh project scan. Present diff to user."
+      requires: [current-claude-md, detected-stack, detected-architecture, detected-conventions, zone-status]
+      produces: [updated-claude-md, zone-diffs]
+      model-tier: reasoning
+    - id: update-agents
+      role: tech-lead
+      intent: "Update agent-context zones in agent files with fresh project context."
+      requires: [detected-stack, detected-architecture, detected-conventions]
+      produces: [updated-agents]
+      model-tier: execution
+    - id: confirm
+      role: system
+      intent: "Present summary of changes and get user confirmation."
+      requires: [zone-diffs, updated-agents]
+      produces: [confirmation]
+      gate: true
+    - 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]
+---
+
+# Re-Specialize
+
+Incrementally updates auto-generated content in CLAUDE.md and agent files
+without touching user customizations. Uses protected zone markers to identify
+what can be safely regenerated.
+
+## When to use
+
+- When project dependencies have changed (new framework, updated versions)
+- When architecture has evolved (new patterns, restructured folders)
+- When agents need refreshed context about the project
+- Periodically to keep CLAUDE.md in sync with the actual codebase
+
+## Process
+
+### Step 1 -- Read current state
+
+Read CLAUDE.md and all agent files in `.claude/agents/`:
+
+- Identify existing zone markers (`<!-- guild:auto-start:ID -->` / `<!-- guild:auto-end:ID -->`)
+- Note which zones exist and their current content
+- Identify any user customizations outside of zones
+
+### Step 2 -- Explore the project
+
+Same exploration as guild-specialize:
+
+- Scan dependency files for current stack and versions
+- Analyze project structure and architecture patterns
+- Detect code conventions from linter/formatter configs
+- Check environment variable examples
+
+### Step 3 -- Check zone markers
+
+If CLAUDE.md has zone markers, proceed to regeneration.
+
+If CLAUDE.md does NOT have zone markers (legacy project):
+
+- Offer to inject markers around the auto-generated sections
+- Show the user where markers would be placed
+- Require explicit confirmation before modifying
+- If user declines, abort gracefully
+
+### Step 4 -- Regenerate zone content
+
+Invoke the Tech Lead agent using Task tool with `model: "opus"` (reasoning tier):
+
+- Generate fresh content for each zone based on the project scan
+- Compare new content with existing zone content
+- Present a diff for each zone to the user
+- Only replace zones where content has actually changed
+
+Zones to regenerate:
+
+| Zone ID        | Content                                    |
+|----------------|--------------------------------------------|
+| `structure`    | Project folder structure with descriptions |
+| `architecture` | Architecture patterns and design decisions |
+| `conventions`  | Code conventions from linter/formatter     |
+| `env-vars`     | Environment variables from .env.example    |
+
+### Step 5 -- Update agent context
+
+Invoke the Tech Lead agent using Task tool with `model: "sonnet"` (execution tier):
+
+- For each agent in `.claude/agents/*.md`, update the `agent-context` zone
+- If no `agent-context` zone exists, append one at the bottom
+- Preserve everything outside the zone (role definition, process, rules)
+
+### Step 6 -- Confirm changes
+
+Present a summary:
+
+```text
+Re-specialization complete for [project-name]
+
+Zones updated:
+- structure: [changed/unchanged]
+- architecture: [changed/unchanged]
+- conventions: [changed/unchanged]
+- env-vars: [changed/unchanged]
+
+Agents updated: [count] of [total]
+
+Review the changes above. Confirm to commit.
+```
+
+### Step 7 -- Commit
+
+Commit all changes as an atomic commit:
+
+```bash
+git add CLAUDE.md .claude/agents/*.md
+git commit -m "chore: re-specialize via guild-re-specialize"
+```
+
+## Important Notes
+
+- NEVER modify content outside of zone markers
+- NEVER read real `.env` files -- only `.env.example`
+- If a zone's content hasn't changed, skip it (no-op)
+- Present diffs before applying changes
+- User confirmation is required before committing

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

@@ -0,0 +1,159 @@
+---
+name: tdd
+description: "Discipline skill — TDD red-green-refactor cycle. Use when implementing any feature or bugfix, before writing implementation code."
+user-invocable: true
+---
+
+# Test-Driven Development (TDD)
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+## Usage
+
+`/tdd`
+
+Invoke this skill before implementing any feature or bugfix. It establishes the discipline for your implementation session.
+
+## When to use
+
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask the user):** throwaway prototypes, generated code, configuration files.
+
+## The Iron Law
+
+```text
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+## Red-Green-Refactor
+
+### RED - Write Failing Test
+
+Write one minimal test showing what should happen.
+
+**Requirements:**
+
+- One behavior per test
+- Clear name that describes behavior
+- Real code (no mocks unless unavoidable)
+
+**Run the test. Confirm:**
+
+- Test fails (not errors)
+- Failure message is expected
+- Fails because feature missing (not typos)
+
+Test passes? You're testing existing behavior. Fix the test.
+
+### GREEN - Minimal Code
+
+Write the simplest code to pass the test.
+
+Don't add features, refactor other code, or "improve" beyond the test.
+
+**Run the test. Confirm:**
+
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+Test fails? Fix code, not test.
+
+### REFACTOR - Clean Up
+
+After green only:
+
+- Remove duplication
+- Improve names
+- Extract helpers
+
+Keep tests green. Don't add behavior.
+
+### Repeat
+
+Next failing test for next behavior.
+
+## Good Tests
+
+| Quality          | Good                                | Bad                                                 |
+| ---------------- | ----------------------------------- | --------------------------------------------------- |
+| **Minimal**      | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear**        | Name describes behavior             | `test('test1')`                                     |
+| **Shows intent** | Demonstrates desired API            | Obscures what code should do                        |
+
+## Common Rationalizations
+
+| Excuse                           | Reality                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
+| "I'll test after"                | Tests passing immediately prove nothing.                                |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested"        | Ad-hoc is not systematic. No record, can't re-run.                      |
+| "Deleting X hours is wasteful"   | Sunk cost fallacy. Keeping unverified code is technical debt.           |
+| "Need to explore first"          | Fine. Throw away exploration, start with TDD.                           |
+| "Test hard = design unclear"     | Listen to the test. Hard to test = hard to use.                         |
+| "TDD will slow me down"          | TDD is faster than debugging.                                           |
+
+## Red Flags - STOP and Start Over
+
+- Code before test
+- Test after implementation
+- Test passes immediately
+- Can't explain why test failed
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Keep as reference"
+
+**All of these mean: Delete code. Start over with TDD.**
+
+## Bug Fix Flow
+
+1. Write failing test reproducing the bug
+2. Verify RED (test fails as expected)
+3. Implement minimal fix
+4. Verify GREEN (test passes, all tests pass)
+5. Refactor if needed
+
+Never fix bugs without a test.
+
+## When Stuck
+
+| Problem                  | Solution                                              |
+| ------------------------ | ----------------------------------------------------- |
+| Don't know how to test   | Write wished-for API. Write assertion first.          |
+| Test too complicated     | Design too complicated. Simplify interface.           |
+| Must mock everything     | Code too coupled. Use dependency injection.           |
+| Test setup huge          | Extract helpers. Still complex? Simplify design.      |
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.
+
+## Related Skills
+
+- `/debug` — systematic debugging when tests reveal unexpected failures
+- `/verify` — verification before claiming work is complete

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

@@ -0,0 +1,114 @@
+---
+name: verify
+description: "Discipline skill — verification before completion. Use when about to claim work is complete, fixed, or passing, before committing or creating PRs."
+user-invocable: true
+---
+
+# Verification Before Completion
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+## Usage
+
+`/verify`
+
+Invoke this skill before claiming any work is done, before committing, and before creating PRs.
+
+## When to use
+
+**ALWAYS before:**
+
+- Any success or completion claim
+- Committing, pushing, or creating PRs
+- Moving to the next task
+- Expressing satisfaction about work state
+
+## The Iron Law
+
+```text
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this step, you cannot claim it passes.
+
+## The Gate Function
+
+```text
+BEFORE claiming any status:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## What Each Claim Requires
+
+| Claim            | Requires                        | Not Sufficient                 |
+| ---------------- | ------------------------------- | ------------------------------ |
+| Tests pass       | Test command output: 0 failures | Previous run, "should pass"    |
+| Linter clean     | Linter output: 0 errors         | Partial check, extrapolation   |
+| Build succeeds   | Build command: exit 0           | Linter passing, logs look good |
+| Bug fixed        | Test original symptom: passes   | Code changed, assumed fixed    |
+| Regression test  | Red-green cycle verified        | Test passes once               |
+| Requirements met | Line-by-line checklist          | Tests passing                  |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Relying on partial verification
+- Thinking "just this once"
+- ANY wording implying success without having run verification
+
+## Common Rationalizations
+
+| Excuse                       | Reality                        |
+| ---------------------------- | ------------------------------ |
+| "Should work now"            | RUN the verification           |
+| "I'm confident"              | Confidence is not evidence     |
+| "Just this once"             | No exceptions                  |
+| "Linter passed"              | Linter is not compiler         |
+| "Partial check is enough"    | Partial proves nothing         |
+
+## Verification Patterns
+
+**Tests:**
+
+```text
+OK:  [Run test command] [See: 34/34 pass] "All tests pass"
+BAD: "Should pass now" / "Looks correct"
+```
+
+**Build:**
+
+```text
+OK:  [Run build] [See: exit 0] "Build passes"
+BAD: "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+
+```text
+OK:  Re-read plan -> Create checklist -> Verify each -> Report gaps or completion
+BAD: "Tests pass, phase complete"
+```
+
+## The Bottom Line
+
+Run the command. Read the output. THEN claim the result.
+
+No shortcuts. Non-negotiable.
+
+## Related Skills
+
+- `/tdd` — TDD ensures tests exist before claiming code works
+- `/debug` — systematic debugging when verification reveals failures

package/src/utils/eval-runner.js

@@ -0,0 +1,139 @@
+/**
+ * eval-runner.js — Skill evaluation framework for Guild.
+ *
+ * Runs assertions against parsed skill workflows to verify
+ * structural correctness. Compatible with anthropics/skills eval format.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parseSkill } from './workflow-parser.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates', 'skills');
+
+/**
+ * Evaluates a single assertion against a parsed workflow.
+ * @param {object} workflow - Parsed workflow with { version, steps[] }
+ * @param {string} assertion - Assertion string (e.g. "step-exists:evaluate")
+ * @returns {{ passed: boolean, evidence: string }}
+ */
+export function evaluateAssertion(workflow, assertion) {
+  const colonIdx = assertion.indexOf(':');
+  if (colonIdx === -1) {
+    return { passed: false, evidence: `Malformed assertion: "${assertion}"` };
+  }
+
+  const type = assertion.slice(0, colonIdx);
+  const args = assertion.slice(colonIdx + 1);
+
+  switch (type) {
+    case 'step-exists': {
+      const step = workflow.steps.find(s => s.id === args);
+      return step
+        ? { passed: true, evidence: `Step "${args}" found` }
+        : { passed: false, evidence: `Step "${args}" not found in ${workflow.steps.map(s => s.id).join(', ')}` };
+    }
+
+    case 'step-role': {
+      const [stepId, expectedRole] = args.split(':');
+      const step = workflow.steps.find(s => s.id === stepId);
+      if (!step) return { passed: false, evidence: `Step "${stepId}" not found` };
+      return step.role === expectedRole
+        ? { passed: true, evidence: `Step "${stepId}" has role "${expectedRole}"` }
+        : { passed: false, evidence: `Step "${stepId}" has role "${step.role}", expected "${expectedRole}"` };
+    }
+
+    case 'step-model-tier': {
+      const [stepId, expectedTier] = args.split(':');
+      const step = workflow.steps.find(s => s.id === stepId);
+      if (!step) return { passed: false, evidence: `Step "${stepId}" not found` };
+      return step.modelTier === expectedTier
+        ? { passed: true, evidence: `Step "${stepId}" uses tier "${expectedTier}"` }
+        : { passed: false, evidence: `Step "${stepId}" uses tier "${step.modelTier}", expected "${expectedTier}"` };
+    }
+
+    case 'step-requires': {
+      const [stepId, dep] = args.split(':');
+      const step = workflow.steps.find(s => s.id === stepId);
+      if (!step) return { passed: false, evidence: `Step "${stepId}" not found` };
+      return step.requires.includes(dep)
+        ? { passed: true, evidence: `Step "${stepId}" requires "${dep}"` }
+        : { 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);
+      if (!step) return { passed: false, evidence: `Step "${args}" not found` };
+      return step.gate === true
+        ? { passed: true, evidence: `Step "${args}" has gate: true` }
+        : { passed: false, evidence: `Step "${args}" has gate: ${step.gate}` };
+    }
+
+    case 'step-count': {
+      const min = parseInt(args, 10);
+      const actual = workflow.steps.length;
+      return actual >= min
+        ? { passed: true, evidence: `Workflow has ${actual} steps (minimum ${min})` }
+        : { passed: false, evidence: `Workflow has ${actual} steps, expected at least ${min}` };
+    }
+
+    default:
+      return { passed: false, evidence: `Unknown assertion type: "${type}"` };
+  }
+}
+
+/**
+ * Loads evals.json for a skill template.
+ * @param {string} skillName - Skill directory name (e.g. 'build-feature')
+ * @returns {object|null} Parsed evals object or null if no evals exist
+ */
+export function loadEvals(skillName) {
+  const evalsPath = join(TEMPLATES_DIR, skillName, 'evals', 'evals.json');
+  if (!existsSync(evalsPath)) return null;
+  return JSON.parse(readFileSync(evalsPath, 'utf8'));
+}
+
+/**
+ * Runs all evals for a skill template.
+ * Parses the SKILL.md, loads evals.json, and evaluates each assertion.
+ * @param {string} skillName - Skill directory name
+ * @returns {{ skill: string, results: Array<{ id: string, description: string, passed: boolean, expectations: Array }> }}
+ */
+export function runEvals(skillName) {
+  const evals = loadEvals(skillName);
+  if (!evals) throw new Error(`No evals found for skill "${skillName}"`);
+
+  const skillPath = join(TEMPLATES_DIR, skillName, 'SKILL.md');
+  const content = readFileSync(skillPath, 'utf8');
+  const skill = parseSkill(content);
+
+  if (!skill.workflow) {
+    throw new Error(`Skill "${skillName}" has no workflow definition`);
+  }
+
+  const results = evals.evals.map(evalCase => {
+    const expectations = evalCase.expectations.map(exp => {
+      const result = evaluateAssertion(skill.workflow, exp.assertion);
+      return { text: exp.text, assertion: exp.assertion, ...result };
+    });
+    const passed = expectations.every(e => e.passed);
+    return {
+      id: evalCase.id,
+      description: evalCase.description,
+      passed,
+      expectations,
+    };
+  });
+
+  return { skill: skillName, results };
+}

package/src/utils/generators.js

@@ -3,6 +3,8 @@
  */
 
 import { writeFileSync } from 'fs';
+import { wrapZone } from './zones.js';
+import { generateWorkspaceContext } from './workspace.js';
 
 /**
  * Generates PROJECT.md with the onboarding data.
@@ -95,7 +97,10 @@ export function inferEnvVars(type, stack) {
 /**
  * Generates CLAUDE.md — central document with placeholders for guild-specialize.
  */
-export async function generateClaudeMd(data) {
+export async function generateClaudeMd(data, workspace = null, currentMemberName = null) {
+  const wsContext = generateWorkspaceContext(workspace, currentMemberName);
+  const workspaceSection = wsContext ? `\n${wsContext}\n` : '';
+
   const content = `# ${data.name}
 
 ## Framework
@@ -105,20 +110,17 @@ This project uses Guild. Read SESSION.md at the start of each session.
 ${data.stack}
 
 ## Project structure
-[PENDING: guild-specialize]
-
-docs/
-  specs/                              # Design documents (SDD specs)
+${wrapZone('structure', '[PENDING: guild-specialize]\n\ndocs/\n  specs/                              # Design documents (SDD specs)')}
 
 ## Code conventions
-${inferCodeConventions(data.type, data.stack)}
+${wrapZone('conventions', inferCodeConventions(data.type, data.stack))}
 
 ## Architecture patterns
-[PENDING: guild-specialize]
+${wrapZone('architecture', '[PENDING: guild-specialize]')}
 
 ## Environment variables
-${inferEnvVars(data.type, data.stack)}
-
+${wrapZone('env-vars', inferEnvVars(data.type, data.stack))}
+${workspaceSection}
 ## Global rules
 - Do not implement without an approved plan
 - Update SESSION.md at the end of each session