guild-agents 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guild-agents
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# Guild
+
+[![npm version](https://img.shields.io/npm/v/guild-agents)](https://www.npmjs.com/package/guild-agents)
+[![CI](https://github.com/guild-agents/guild/actions/workflows/ci.yml/badge.svg)](https://github.com/guild-agents/guild/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+A multi-agent framework for Claude Code.
+
+Sets up 8 specialized agents and 10 skill-based workflows as `.claude/` files in any project.
+
+## Installation
+
+```bash
+npm install -g guild-agents
+```
+
+Or run directly without installing:
+
+```bash
+npx guild-agents init
+```
+
+## Quick Start
+
+```bash
+npx guild-agents init
+```
+
+Interactive onboarding asks for project name, type, stack, and repo details, then generates the full agent and skill structure.
+
+Open Claude Code in your project and run:
+
+```
+/guild-specialize
+```
+
+This explores your actual codebase and enriches CLAUDE.md with real conventions, patterns, and stack details.
+
+Then start building:
+
+```
+/build-feature Add user authentication with JWT
+```
+
+This runs the full pipeline: evaluation, spec, implementation, review, and QA.
+
+`guild init` generates: CLAUDE.md, PROJECT.md, SESSION.md, `.claude/agents/` (8 agents), `.claude/skills/` (10 skills).
+
+## How It Works
+
+**Agents** are the WHO. Each agent is a flat `.md` file in `.claude/agents/` that defines identity, responsibilities, and process. Skills invoke agents via the Task tool when their expertise is needed.
+
+**Skills** are the HOW. Each skill is a workflow defined in `.claude/skills/*/SKILL.md` and invoked as a slash command. Skills orchestrate one or more agents through a structured process.
+
+**State** is maintained across sessions through three files:
+- `CLAUDE.md` — central enriched context (stack, conventions, rules)
+- `PROJECT.md` — project metadata (name, type, architecture)
+- `SESSION.md` — session continuity (current task, progress, next steps)
+
+After init, agents are generic. Running `/guild-specialize` reads the real codebase and tailors each agent to the project's specific stack and patterns.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| advisor | Evaluates ideas and provides strategic direction |
+| product-owner | Turns approved ideas into concrete tasks |
+| tech-lead | Defines technical approach and architecture |
+| developer | Implements features following project conventions |
+| code-reviewer | Reviews quality, patterns, and technical debt |
+| qa | Testing, edge cases, regression validation |
+| bugfix | Bug diagnosis and resolution |
+| db-migration | Schema changes and safe migrations |
+
+## Skills
+
+| Skill | Description |
+|---|---|
+| `/guild-specialize` | Explores codebase, enriches CLAUDE.md with real stack and conventions |
+| `/build-feature` | Full pipeline: evaluation, spec, implementation, review, QA |
+| `/new-feature` | Creates branch and scaffold for a new feature |
+| `/council` | Convenes multiple agents to debate a decision |
+| `/qa-cycle` | QA and bugfix loop until clean |
+| `/review` | Code review on the current diff |
+| `/dev-flow` | Shows current pipeline phase and next step |
+| `/status` | Project and session state overview |
+| `/session-start` | Loads context and resumes work |
+| `/session-end` | Saves state to SESSION.md |
+
+## CLI Commands
+
+```bash
+guild init                  # Interactive project onboarding
+guild new-agent <name>      # Create a custom agent
+guild status                # Show project status
+```
+
+## Generated Structure
+
+Running `guild init` creates the following in your project root:
+
+```
+CLAUDE.md
+PROJECT.md
+SESSION.md
+.claude/
+  agents/
+    advisor.md
+    product-owner.md
+    tech-lead.md
+    developer.md
+    code-reviewer.md
+    qa.md
+    bugfix.md
+    db-migration.md
+  skills/
+    guild-specialize/SKILL.md
+    build-feature/SKILL.md
+    new-feature/SKILL.md
+    council/SKILL.md
+    qa-cycle/SKILL.md
+    review/SKILL.md
+    dev-flow/SKILL.md
+    status/SKILL.md
+    session-start/SKILL.md
+    session-end/SKILL.md
+```
+
+All files are markdown, tracked by git, and work fully offline.
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code
+- `gh` CLI (optional, for GitHub integration)
+
+## Contributing
+
+Two types of contributions:
+
+- **Agent and skill templates** (`src/templates/`) — improve agent definitions or skill workflows.
+- **CLI code** (`src/`, `bin/`) — bug fixes, new commands, onboarding improvements.
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/guild.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * Guild v1 — CLI entry point
+ * Usage:
+ *   guild init           — onboarding interactivo v1
+ *   guild new-agent      — crear un nuevo agente
+ *   guild status         — ver estado del proyecto
+ */
+
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+program
+  .name('guild')
+  .description('Multi-agent framework for Claude Code')
+  .version(pkg.version);
+
+// guild init
+program
+  .command('init')
+  .description('Inicializar Guild v1 en el proyecto actual')
+  .action(async () => {
+    try {
+      const { runInit } = await import('../src/commands/init.js');
+      await runInit();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild new-agent
+program
+  .command('new-agent')
+  .description('Crear un nuevo agente')
+  .argument('<name>', 'Nombre del agente (lowercase, guiones)')
+  .action(async (name) => {
+    try {
+      const { runNewAgent } = await import('../src/commands/new-agent.js');
+      await runNewAgent(name);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild status
+program
+  .command('status')
+  .description('Ver estado del proyecto Guild')
+  .action(async () => {
+    try {
+      const { runStatus } = await import('../src/commands/status.js');
+      await runStatus();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild doctor
+program
+  .command('doctor')
+  .description('Verify Guild setup and report issues')
+  .action(async () => {
+    try {
+      const { runDoctor } = await import('../src/commands/doctor.js');
+      await runDoctor();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// guild list
+program
+  .command('list')
+  .description('List installed agents and skills')
+  .action(async () => {
+    try {
+      const { runList } = await import('../src/commands/list.js');
+      await runList();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -1,13 +1,64 @@
 {
   "name": "guild-agents",
-  "version": "0.0.1",
-  "description": "A multi-agent framework for Claude Code",
-  "main": "index.js",
-  "keywords": ["claude", "claude-code", "agents", "ai", "workflow"],
-  "author": "tu-nombre",
+  "version": "0.2.0",
+  "description": "A multi-agent framework for Claude Code — specialized AI teams for every project",
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/commands/",
+    "src/templates/",
+    "src/utils/",
+    "!src/utils/__tests__/"
+  ],
+  "bin": {
+    "guild": "bin/guild.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "dev": "node bin/guild.js",
+    "prepublishOnly": "npm test && npm run lint"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "ai",
+    "workflow",
+    "multi-agent",
+    "developer-tools",
+    "cli",
+    "framework",
+    "anthropic",
+    "ai-agents",
+    "automation",
+    "code-review",
+    "nodejs"
+  ],
+  "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guild-ai/guild"
+    "url": "git+https://github.com/guild-agents/guild.git"
+  },
+  "homepage": "https://github.com/guild-agents/guild",
+  "bugs": {
+    "url": "https://github.com/guild-agents/guild/issues"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "picocolors": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.1",
+    "vitest": "^4.0.18"
   }
-}
+}

package/src/commands/__tests__/doctor.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, rmSync, mkdtempSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('runDoctor', () => {
+  let tempDir;
+  let originalCwd;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'guild-doctor-'));
+    originalCwd = process.cwd();
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should pass all checks for a healthy project', async () => {
+    // Setup a complete Guild project
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills', 'build-feature'), { recursive: true });
+    writeFileSync(join(tempDir, '.claude', 'agents', 'advisor.md'), '---\nname: advisor\n---');
+    writeFileSync(join(tempDir, '.claude', 'skills', 'build-feature', 'SKILL.md'), '---\nname: build-feature\n---');
+    writeFileSync(join(tempDir, 'CLAUDE.md'), '# CLAUDE');
+    writeFileSync(join(tempDir, 'PROJECT.md'), '# PROJECT');
+    writeFileSync(join(tempDir, 'SESSION.md'), '# SESSION');
+
+    process.chdir(tempDir);
+    const { runDoctor } = await import('../doctor.js');
+    // Should not throw for healthy project
+    await expect(runDoctor()).resolves.toBeUndefined();
+  });
+
+  it('should throw when .claude directory is missing', async () => {
+    writeFileSync(join(tempDir, 'CLAUDE.md'), '# CLAUDE');
+    writeFileSync(join(tempDir, 'PROJECT.md'), '# PROJECT');
+    writeFileSync(join(tempDir, 'SESSION.md'), '# SESSION');
+
+    process.chdir(tempDir);
+    const { runDoctor } = await import('../doctor.js');
+    await expect(runDoctor()).rejects.toThrow('Guild setup has issues');
+  });
+
+  it('should throw when agents directory is empty', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills', 'test-skill'), { recursive: true });
+    writeFileSync(join(tempDir, '.claude', 'skills', 'test-skill', 'SKILL.md'), '---\nname: test\n---');
+    writeFileSync(join(tempDir, 'CLAUDE.md'), '# CLAUDE');
+    writeFileSync(join(tempDir, 'PROJECT.md'), '# PROJECT');
+    writeFileSync(join(tempDir, 'SESSION.md'), '# SESSION');
+
+    process.chdir(tempDir);
+    const { runDoctor } = await import('../doctor.js');
+    await expect(runDoctor()).rejects.toThrow('Guild setup has issues');
+  });
+
+  it('should throw when CLAUDE.md is missing', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills', 'test-skill'), { recursive: true });
+    writeFileSync(join(tempDir, '.claude', 'agents', 'advisor.md'), '---\nname: advisor\n---');
+    writeFileSync(join(tempDir, '.claude', 'skills', 'test-skill', 'SKILL.md'), '---\nname: test\n---');
+    writeFileSync(join(tempDir, 'PROJECT.md'), '# PROJECT');
+    writeFileSync(join(tempDir, 'SESSION.md'), '# SESSION');
+
+    process.chdir(tempDir);
+    const { runDoctor } = await import('../doctor.js');
+    await expect(runDoctor()).rejects.toThrow('Guild setup has issues');
+  });
+
+  it('should throw when PROJECT.md is missing', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills', 'test-skill'), { recursive: true });
+    writeFileSync(join(tempDir, '.claude', 'agents', 'advisor.md'), '---\nname: advisor\n---');
+    writeFileSync(join(tempDir, '.claude', 'skills', 'test-skill', 'SKILL.md'), '---\nname: test\n---');
+    writeFileSync(join(tempDir, 'CLAUDE.md'), '# CLAUDE');
+    writeFileSync(join(tempDir, 'SESSION.md'), '# SESSION');
+
+    process.chdir(tempDir);
+    const { runDoctor } = await import('../doctor.js');
+    await expect(runDoctor()).rejects.toThrow('Guild setup has issues');
+  });
+});

package/src/commands/__tests__/list.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, rmSync, mkdtempSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('runList', () => {
+  let tempDir;
+  let originalCwd;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'guild-list-'));
+    originalCwd = process.cwd();
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should list agents and skills with descriptions', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills', 'build-feature'), { recursive: true });
+    writeFileSync(
+      join(tempDir, '.claude', 'agents', 'advisor.md'),
+      '---\nname: advisor\ndescription: "Strategic advisor"\n---\n# Advisor'
+    );
+    writeFileSync(
+      join(tempDir, '.claude', 'skills', 'build-feature', 'SKILL.md'),
+      '---\nname: build-feature\ndescription: "Full pipeline"\n---\n# Build Feature'
+    );
+
+    process.chdir(tempDir);
+    const { runList } = await import('../list.js');
+    await expect(runList()).resolves.toBeUndefined();
+  });
+
+  it('should handle missing agents directory', async () => {
+    mkdirSync(join(tempDir, '.claude', 'skills', 'test'), { recursive: true });
+    writeFileSync(
+      join(tempDir, '.claude', 'skills', 'test', 'SKILL.md'),
+      '---\nname: test\n---'
+    );
+
+    process.chdir(tempDir);
+    const { runList } = await import('../list.js');
+    await expect(runList()).resolves.toBeUndefined();
+  });
+
+  it('should handle missing skills directory', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    writeFileSync(
+      join(tempDir, '.claude', 'agents', 'advisor.md'),
+      '---\nname: advisor\n---'
+    );
+
+    process.chdir(tempDir);
+    const { runList } = await import('../list.js');
+    await expect(runList()).resolves.toBeUndefined();
+  });
+
+  it('should handle empty directories', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills'), { recursive: true });
+
+    process.chdir(tempDir);
+    const { runList } = await import('../list.js');
+    await expect(runList()).resolves.toBeUndefined();
+  });
+
+  it('should handle agents without frontmatter', async () => {
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    writeFileSync(
+      join(tempDir, '.claude', 'agents', 'custom.md'),
+      '# Custom Agent\nNo frontmatter here'
+    );
+
+    process.chdir(tempDir);
+    const { runList } = await import('../list.js');
+    await expect(runList()).resolves.toBeUndefined();
+  });
+});

package/src/commands/__tests__/new-agent.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, rmSync, mkdtempSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('runNewAgent', () => {
+  let tempDir;
+  let originalCwd;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'guild-test-'));
+    originalCwd = process.cwd();
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should throw with invalid agent name', async () => {
+    process.chdir(tempDir);
+    const { runNewAgent } = await import('../new-agent.js');
+    await expect(runNewAgent('Invalid Name!')).rejects.toThrow('Nombre invalido');
+  });
+
+  it('should throw when .claude/agents/ does not exist', async () => {
+    process.chdir(tempDir);
+    const { runNewAgent } = await import('../new-agent.js');
+    await expect(runNewAgent('valid-name')).rejects.toThrow('Guild no esta instalado');
+  });
+
+  it('should throw when agent already exists', async () => {
+    process.chdir(tempDir);
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    writeFileSync(join(tempDir, '.claude', 'agents', 'existing.md'), '# existing');
+    const { runNewAgent } = await import('../new-agent.js');
+    await expect(runNewAgent('existing')).rejects.toThrow('ya existe');
+  });
+});

package/src/commands/__tests__/status.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('runStatus', () => {
+  let tempDir;
+  let originalCwd;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'guild-test-'));
+    originalCwd = process.cwd();
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should throw when PROJECT.md does not exist', async () => {
+    process.chdir(tempDir);
+    const { runStatus } = await import('../status.js');
+    await expect(runStatus()).rejects.toThrow('Guild no esta instalado');
+  });
+
+  it('should not throw when PROJECT.md exists', async () => {
+    process.chdir(tempDir);
+    writeFileSync(join(tempDir, 'PROJECT.md'), '**Nombre:** TestProject\n**Stack:** Node.js');
+    mkdirSync(join(tempDir, '.claude', 'agents'), { recursive: true });
+    mkdirSync(join(tempDir, '.claude', 'skills'), { recursive: true });
+    const { runStatus } = await import('../status.js');
+    await expect(runStatus()).resolves.not.toThrow();
+  });
+});

package/src/commands/doctor.js

@@ -0,0 +1,99 @@
+/**
+ * doctor.js — Validates Guild setup and reports actionable fixes
+ */
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+export async function runDoctor() {
+  p.intro(chalk.bold.cyan('Guild — Doctor'));
+
+  const checks = [];
+  let healthy = true;
+
+  // Check .claude/ directory
+  if (existsSync('.claude')) {
+    checks.push({ name: '.claude/ directory', pass: true });
+  } else {
+    checks.push({ name: '.claude/ directory', pass: false, fix: 'Run: guild init' });
+    healthy = false;
+  }
+
+  // Check agents
+  const agentsDir = join('.claude', 'agents');
+  if (existsSync(agentsDir)) {
+    const agents = readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+    if (agents.length > 0) {
+      checks.push({ name: `Agents (${agents.length} found)`, pass: true });
+    } else {
+      checks.push({ name: 'Agents', pass: false, fix: 'Run: guild init (no agent .md files found in .claude/agents/)' });
+      healthy = false;
+    }
+  } else {
+    checks.push({ name: 'Agents directory', pass: false, fix: 'Run: guild init (missing .claude/agents/)' });
+    healthy = false;
+  }
+
+  // Check skills
+  const skillsDir = join('.claude', 'skills');
+  if (existsSync(skillsDir)) {
+    const skills = readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .filter(d => existsSync(join(skillsDir, d.name, 'SKILL.md')));
+    if (skills.length > 0) {
+      checks.push({ name: `Skills (${skills.length} found)`, pass: true });
+    } else {
+      checks.push({ name: 'Skills', pass: false, fix: 'Run: guild init (no SKILL.md files found in .claude/skills/)' });
+      healthy = false;
+    }
+  } else {
+    checks.push({ name: 'Skills directory', pass: false, fix: 'Run: guild init (missing .claude/skills/)' });
+    healthy = false;
+  }
+
+  // Check CLAUDE.md
+  if (existsSync('CLAUDE.md')) {
+    checks.push({ name: 'CLAUDE.md', pass: true });
+  } else {
+    checks.push({ name: 'CLAUDE.md', pass: false, fix: 'Run: guild init (creates CLAUDE.md with project instructions)' });
+    healthy = false;
+  }
+
+  // Check PROJECT.md
+  if (existsSync('PROJECT.md')) {
+    checks.push({ name: 'PROJECT.md', pass: true });
+  } else {
+    checks.push({ name: 'PROJECT.md', pass: false, fix: 'Run: guild init (creates PROJECT.md with project identity)' });
+    healthy = false;
+  }
+
+  // Check SESSION.md
+  if (existsSync('SESSION.md')) {
+    checks.push({ name: 'SESSION.md', pass: true });
+  } else {
+    checks.push({ name: 'SESSION.md', pass: false, fix: 'Run: guild init (creates SESSION.md for session tracking)' });
+    healthy = false;
+  }
+
+  // Display results
+  for (const check of checks) {
+    if (check.pass) {
+      p.log.success(`${chalk.green('✓')} ${check.name}`);
+    } else {
+      p.log.error(`${chalk.red('✗')} ${check.name}`);
+      p.log.info(chalk.gray(`  Fix: ${check.fix}`));
+    }
+  }
+
+  const passed = checks.filter(c => c.pass).length;
+  const total = checks.length;
+
+  if (healthy) {
+    p.outro(chalk.green(`All checks passed (${passed}/${total})`));
+  } else {
+    p.outro(chalk.red(`${total - passed} issue(s) found (${passed}/${total} passed)`));
+    throw new Error('Guild setup has issues. Run the suggested fixes above.');
+  }
+}