guild-agents 0.2.7 → 0.2.9

package/README.md

@@ -3,62 +3,64 @@
 [![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)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-A multi-agent framework for Claude Code.
+Claude Code is powerful but chaotic. Guild gives it structure.
 
-Sets up 8 specialized agents and 10 skill-based workflows as `.claude/` files in any project.
+Guild is an npm CLI that sets up 9 specialized agents and 10 skill-based workflows as `.claude/` files in any project. Agents define **who** does the work. Skills define **how** it gets done. Everything is markdown, tracked by git, works offline.
 
-## Installation
+## Why Guild?
 
-```bash
-npm install -g guild-agents
-```
+- **Structure over chaos.** Claude Code without guidance produces inconsistent results. Guild gives every task a clear owner and a repeatable process.
+- **Agents = WHO, Skills = HOW.** Agents are flat `.md` files with identity and expertise. Skills are workflow definitions invoked as slash commands. Clean separation, no magic.
+- **State that persists.** Context lives in `CLAUDE.md`, `PROJECT.md`, and `SESSION.md` -- tracked by git, readable by humans, never lost between sessions.
+- **Zero infrastructure.** No servers, no APIs, no config files. Just markdown files that Claude Code reads natively.
 
-Or run directly without installing:
+## How It Works
 
-```bash
-npx guild-agents init
 ```
+You ──> /build-feature "Add JWT auth"
+         │
+         ▼
+    ┌─────────┐     ┌───────────────┐     ┌───────────────┐
+    │ Advisor  │────>│  Tech Lead    │────>│  Developer    │
+    │ evaluate │     │  plan         │     │  implement    │
+    └─────────┘     └───────────────┘     └───────┬───────┘
+                                                  │
+                                    ┌─────────────┼─────────────┐
+                                    ▼             ▼             ▼
+                              ┌──────────┐ ┌──────────┐ ┌──────────┐
+                              │ Reviewer │ │    QA    │ │  Bugfix  │
+                              │ review   │ │  test    │ │  fix     │
+                              └──────────┘ └──────────┘ └──────────┘
+```
+
+Skills orchestrate agents through structured pipelines. You invoke a skill as a slash command, and it coordinates the right agents in the right order.
 
 ## Quick Start
 
 ```bash
-npx guild-agents init
+npm install -g guild-agents
+guild init
 ```
 
-Interactive onboarding asks for project name, type, stack, and repo details, then generates the full agent and skill structure.
+The interactive onboarding asks for project name, type, stack, and repo details, then generates the full structure: 9 agents, 10 skills, and 3 state files.
 
-Open Claude Code in your project and run:
+Next, let Guild learn your codebase:
 
 ```
 /guild-specialize
 ```
 
-This explores your actual codebase and enriches CLAUDE.md with real conventions, patterns, and stack details.
+This explores your actual code and enriches `CLAUDE.md` with real conventions, patterns, and stack details. Every agent now understands your project.
 
-Then start building:
+Then build something:
 
 ```
 /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.
+This runs the full pipeline -- advisor evaluation, tech lead planning, developer implementation, code review, and QA -- all coordinated automatically.
 
 ## Agents
 
@@ -72,6 +74,7 @@ After init, agents are generic. Running `/guild-specialize` reads the real codeb
 | qa | Testing, edge cases, regression validation |
 | bugfix | Bug diagnosis and resolution |
 | db-migration | Schema changes and safe migrations |
+| platform-expert | Diagnoses and resolves Claude Code integration issues |
 
 ## Skills
 
@@ -94,6 +97,8 @@ After init, agents are generic. Running `/guild-specialize` reads the real codeb
 guild init                  # Interactive project onboarding
 guild new-agent <name>      # Create a custom agent
 guild status                # Show project status
+guild doctor                # Diagnose installation state
+guild list                  # List installed agents and skills
 ```
 
 ## Generated Structure
@@ -114,6 +119,7 @@ SESSION.md
     qa.md
     bugfix.md
     db-migration.md
+    platform-expert.md
   skills/
     guild-specialize/SKILL.md
     build-feature/SKILL.md
@@ -129,9 +135,13 @@ SESSION.md
 
 All files are markdown, tracked by git, and work fully offline.
 
+## Guild Builds Itself
+
+This project uses its own agents and skills to develop itself. Every feature, review, and bugfix goes through the same pipelines that Guild installs in your project.
+
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 20
 - Claude Code
 - `gh` CLI (optional, for GitHub integration)
 
@@ -139,11 +149,11 @@ All files are markdown, tracked by git, and work fully offline.
 
 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.
+- **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).
+MIT -- see [LICENSE](LICENSE).

package/bin/guild.js

@@ -6,6 +6,8 @@
  *   guild init           — interactive onboarding v1
  *   guild new-agent      — create a new agent
  *   guild status         — view project status
+ *   guild doctor         — verify setup and report issues
+ *   guild list           — list installed agents and skills
  */
 
 import { program } from 'commander';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guild-agents",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "A multi-agent framework for Claude Code — specialized AI teams for every project",
   "type": "module",
   "files": [
@@ -8,7 +8,7 @@
     "src/commands/",
     "src/templates/",
     "src/utils/",
-    "!src/utils/__tests__/"
+    "!src/**/__tests__/"
   ],
   "bin": {
     "guild": "bin/guild.js"
@@ -39,7 +39,7 @@
     "code-review",
     "nodejs"
   ],
-  "author": "",
+  "author": "Guild Agents <guild-agents@users.noreply.github.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -52,8 +52,7 @@
   "dependencies": {
     "@clack/prompts": "^1.0.1",
     "chalk": "^5.3.0",
-    "commander": "^14.0.3",
-    "picocolors": "^1.0.0"
+    "commander": "^14.0.3"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/commands/init.js

@@ -13,7 +13,7 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { existsSync } from 'fs';
 import { generateProjectMd, generateSessionMd, generateClaudeMd } from '../utils/generators.js';
-import { copyTemplates } from '../utils/files.js';
+import { copyTemplates, getAgentNames } from '../utils/files.js';
 
 export async function runInit() {
   console.log('');
@@ -125,7 +125,7 @@ export async function runInit() {
   p.log.success('CLAUDE.md');
   p.log.success('PROJECT.md');
   p.log.success('SESSION.md');
-  p.log.success('.claude/agents/    (8 base agents)');
+  p.log.success(`.claude/agents/    (${getAgentNames().length} base agents)`);
   p.log.success('.claude/skills/    (10 skills)');
 
   p.note(

package/src/templates/agents/platform-expert.md

@@ -1,6 +1,8 @@
 ---
 name: platform-expert
 description: "Diagnoses and resolves Claude Code integration issues -- permissions, subagents, hooks, settings"
+tools: Read, Write, Edit, Bash, Glob, Grep
+permissionMode: bypassPermissions
 ---
 
 # Platform Expert

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

@@ -87,6 +87,7 @@ For each agent in `.claude/agents/*.md`, add project-specific context:
 - **qa.md**: testing framework, commands to run tests, current coverage
 - **bugfix.md**: debugging stack, logs, available tools
 - **db-migration.md**: ORM, migration tool, current schema (if applicable)
+- **platform-expert.md**: Claude Code version, known permission bugs, hook configuration
 
 Use the `Task` tool to invoke each agent by reading their `.claude/agents/[name].md` if you need a specialized perspective to enrich their configuration.
 

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

@@ -75,7 +75,7 @@ Session: 2026-02-23
 Task: Implementing user preferences
 State: Phase 4 — Developer implementing
 
-Agents: advisor, product-owner, tech-lead, developer, code-reviewer, qa, bugfix, db-migration
+Agents: advisor, product-owner, tech-lead, developer, code-reviewer, qa, bugfix, db-migration, platform-expert
 Skills: guild-specialize, build-feature, new-feature, council, qa-cycle, review, dev-flow,
   status, session-start, session-end
 ```

package/src/utils/files.js

@@ -1,5 +1,5 @@
 /**
- * files.js — Utilidades de sistema de archivos para Guild v1
+ * files.js — File system utilities for Guild v1
  */
 
 import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync } from 'fs';
@@ -12,7 +12,7 @@ const AGENTS_DIR = join('.claude', 'agents');
 const SKILLS_DIR = join('.claude', 'skills');
 
 /**
- * Lista los nombres de los 9 agentes v1.
+ * Returns the names of the 9 v1 agents.
  */
 export function getAgentNames() {
   return [
@@ -29,7 +29,7 @@ export function getAgentNames() {
 }
 
 /**
- * Copia los templates de agentes y skills al proyecto del usuario.
+ * Copies agent and skill templates to the user's project.
  */
 export async function copyTemplates() {
   mkdirSync(AGENTS_DIR, { recursive: true });
@@ -65,7 +65,7 @@ export async function copyTemplates() {
 }
 
 /**
- * Lee el contenido de PROJECT.md si existe.
+ * Reads the contents of PROJECT.md if it exists.
  */
 export function readProjectMd() {
   const path = 'PROJECT.md';
@@ -74,7 +74,7 @@ export function readProjectMd() {
 }
 
 /**
- * Lee el contenido de SESSION.md si existe.
+ * Reads the contents of SESSION.md if it exists.
  */
 export function readSessionMd() {
   const path = 'SESSION.md';
@@ -83,9 +83,9 @@ export function readSessionMd() {
 }
 
 /**
- * Resuelve la raiz del proyecto Guild caminando hacia arriba desde startDir.
- * Busca .claude/ o PROJECT.md como marcadores de un proyecto Guild.
- * Retorna la ruta absoluta del proyecto o null si no se encuentra.
+ * Resolves the Guild project root by walking up from startDir.
+ * Looks for .claude/ or PROJECT.md as markers of a Guild project.
+ * Returns the absolute path to the project or null if not found.
  */
 export function resolveProjectRoot(startDir = process.cwd()) {
   let dir = resolve(startDir);

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

@@ -1,85 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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('Invalid name');
-  });
-
-  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 is not installed');
-  });
-
-  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('already exists');
-  });
-});

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

@@ -1,35 +0,0 @@
-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 is not installed');
-  });
-
-  it('should not throw when PROJECT.md exists', async () => {
-    process.chdir(tempDir);
-    writeFileSync(join(tempDir, 'PROJECT.md'), '**Name:** 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();
-  });
-});