guild-agents 1.1.0 → 1.2.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,61 @@ 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);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guild-agents",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Specification-driven development CLI for Claude Code — think before you build",
   "type": "module",
   "files": [

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,55 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+import { findWorkspaceRoot, 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 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/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).

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/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

package/src/utils/workspace.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+
+export const WORKSPACE_FILE = 'guild-workspace.json';
+
+export function findWorkspaceRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, WORKSPACE_FILE))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function loadWorkspace(startDir = process.cwd()) {
+  const root = findWorkspaceRoot(startDir);
+  if (!root) return null;
+
+  const filePath = join(root, WORKSPACE_FILE);
+  const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+
+  return {
+    ...raw,
+    root,
+    members: (raw.members || []).map(m => ({
+      ...m,
+      absolutePath: resolve(root, m.path),
+    })),
+  };
+}
+
+export function resolveWorkspaceAgents(workspace, localAgentsDir) {
+  const agents = new Map();
+
+  if (workspace?.shared?.agents) {
+    const sharedDir = resolve(workspace.root, workspace.shared.agents);
+    if (existsSync(sharedDir)) {
+      for (const file of readdirSync(sharedDir).filter(f => f.endsWith('.md'))) {
+        const name = file.replace('.md', '');
+        agents.set(name, { name, path: join(sharedDir, file), source: 'workspace' });
+      }
+    }
+  }
+
+  if (existsSync(localAgentsDir)) {
+    for (const file of readdirSync(localAgentsDir).filter(f => f.endsWith('.md'))) {
+      const name = file.replace('.md', '');
+      agents.set(name, { name, path: join(localAgentsDir, file), source: 'local' });
+    }
+  }
+
+  return [...agents.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function generateWorkspaceContext(workspace, currentMemberName) {
+  if (!workspace) return '';
+
+  const otherMembers = workspace.members.filter(m => m.name !== currentMemberName);
+  if (otherMembers.length === 0) return '';
+
+  const lines = [
+    '## Workspace context',
+    `- **Workspace:** ${workspace.name}`,
+    `- **Members:** ${workspace.members.map(m => m.name === currentMemberName ? `${m.name} (this)` : m.name).join(', ')}`,
+  ];
+
+  for (const member of otherMembers) {
+    const projectMdPath = join(member.absolutePath, 'PROJECT.md');
+    if (existsSync(projectMdPath)) {
+      const content = readFileSync(projectMdPath, 'utf8');
+      const stackMatch = content.match(/\*\*Stack:\*\*\s*(.+)/);
+      if (stackMatch) {
+        lines.push(`- **${member.name} stack:** ${stackMatch[1].trim()}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/utils/zones.js

@@ -0,0 +1,39 @@
+const MARKER_START = 'guild:auto-start';
+const MARKER_END = 'guild:auto-end';
+
+export function wrapZone(zoneId, content) {
+  const trimmed = content.endsWith('\n') ? content.slice(0, -1) : content;
+  return `<!-- ${MARKER_START}:${zoneId} -->\n${trimmed}\n<!-- ${MARKER_END}:${zoneId} -->`;
+}
+
+export function extractZones(content) {
+  const zones = new Map();
+  const startPattern = /^<!-- guild:auto-start:(\S+) -->$/gm;
+  let match;
+
+  while ((match = startPattern.exec(content)) !== null) {
+    const zoneId = match[1];
+    const contentStart = match.index + match[0].length + 1; // +1 for newline
+    const endMarker = `<!-- ${MARKER_END}:${zoneId} -->`;
+    const endIndex = content.indexOf(endMarker, contentStart);
+    if (endIndex === -1) continue;
+
+    zones.set(zoneId, {
+      start: match.index,
+      end: endIndex + endMarker.length,
+      content: content.slice(contentStart, endIndex - 1), // -1 to trim newline before end marker
+    });
+  }
+
+  return zones;
+}
+
+export function replaceZone(content, zoneId, newContent) {
+  const zones = extractZones(content);
+  if (!zones.has(zoneId)) return content;
+
+  const zone = zones.get(zoneId);
+  const before = content.slice(0, zone.start);
+  const after = content.slice(zone.end);
+  return before + wrapZone(zoneId, newContent) + after;
+}