guild-agents 0.2.6 → 0.2.8

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

@@ -3,9 +3,11 @@
 /**
  * Guild v1 — CLI entry point
  * Usage:
- *   guild init           — onboarding interactivo v1
- *   guild new-agent      — crear un nuevo agente
- *   guild status         — ver estado del proyecto
+ *   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';
@@ -24,7 +26,7 @@ program
 // guild init
 program
   .command('init')
-  .description('Inicializar Guild v1 en el proyecto actual')
+  .description('Initialize Guild v1 in the current project')
   .action(async () => {
     try {
       const { runInit } = await import('../src/commands/init.js');
@@ -38,8 +40,8 @@ program
 // guild new-agent
 program
   .command('new-agent')
-  .description('Crear un nuevo agente')
-  .argument('<name>', 'Nombre del agente (lowercase, guiones)')
+  .description('Create a new agent')
+  .argument('<name>', 'Agent name (lowercase, hyphens)')
   .action(async (name) => {
     try {
       const { runNewAgent } = await import('../src/commands/new-agent.js');
@@ -53,7 +55,7 @@ program
 // guild status
 program
   .command('status')
-  .description('Ver estado del proyecto Guild')
+  .description('View Guild project status')
   .action(async () => {
     try {
       const { runStatus } = await import('../src/commands/status.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guild-agents",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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",
@@ -50,10 +50,9 @@
     "url": "https://github.com/guild-agents/guild/issues"
   },
   "dependencies": {
-    "@clack/prompts": "^0.9.0",
+    "@clack/prompts": "^1.0.1",
     "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "picocolors": "^1.0.0"
+    "commander": "^14.0.3"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/commands/init.js

@@ -1,12 +1,12 @@
 /**
- * guild init — Onboarding interactivo v1
+ * guild init — Interactive onboarding v1
  *
- * Flujo:
- * 1. Verificar que no existe ya una instalacion de Guild
- * 2. Recopilar: nombre, tipo, stack, GitHub, codigo existente
- * 3. Generar PROJECT.md, CLAUDE.md, SESSION.md
- * 4. Copiar agentes y skills
- * 5. Instrucciones para /guild-specialize
+ * Flow:
+ * 1. Verify that a Guild installation does not already exist
+ * 2. Collect: name, type, stack, GitHub, existing code
+ * 3. Generate PROJECT.md, CLAUDE.md, SESSION.md
+ * 4. Copy agents and skills
+ * 5. Instructions for /guild-specialize
  */
 
 import * as p from '@clack/prompts';
@@ -17,68 +17,68 @@ import { copyTemplates } from '../utils/files.js';
 
 export async function runInit() {
   console.log('');
-  p.intro(chalk.bold.cyan('Guild v1 — Nuevo proyecto'));
+  p.intro(chalk.bold.cyan('Guild v1 — New project'));
 
-  // Verificar instalacion existente
+  // Check for existing installation
   if (existsSync('.claude/agents')) {
     const overwrite = await p.confirm({
-      message: 'Guild ya esta instalado en este proyecto. Reinicializar?',
+      message: 'Guild is already installed in this project. Reinitialize?',
       initialValue: false,
     });
 
     if (p.isCancel(overwrite) || !overwrite) {
-      p.cancel('Cancelado.');
+      p.cancel('Cancelled.');
       return;
     }
   }
 
-  // ─── Nombre ─────────────────────────────────────────────────────────────────
+  // ─── Name ─────────────────────────────────────────────────────────────────
   const name = await p.text({
-    message: 'Nombre del proyecto:',
-    placeholder: 'mi-proyecto',
+    message: 'Project name:',
+    placeholder: 'my-project',
     validate: (val) => {
-      if (!val) return 'El nombre es requerido';
+      if (!val) return 'Name is required';
     },
   });
-  if (p.isCancel(name)) { p.cancel('Cancelado.'); return; }
+  if (p.isCancel(name)) { p.cancel('Cancelled.'); return; }
 
-  // ─── Tipo ───────────────────────────────────────────────────────────────────
+  // ─── Type ───────────────────────────────────────────────────────────────────
   const type = await p.select({
-    message: 'Tipo de proyecto:',
+    message: 'Project type:',
     options: [
       { value: 'webapp', label: 'Web app (React/Vue/Angular)' },
       { value: 'api', label: 'API / Backend service' },
       { value: 'cli', label: 'CLI tool' },
       { value: 'mobile', label: 'Mobile (React Native)' },
-      { value: 'fullstack', label: 'Otro / Fullstack' },
+      { value: 'fullstack', label: 'Other / Fullstack' },
     ],
   });
-  if (p.isCancel(type)) { p.cancel('Cancelado.'); return; }
+  if (p.isCancel(type)) { p.cancel('Cancelled.'); return; }
 
   // ─── Stack ──────────────────────────────────────────────────────────────────
   const stack = await p.text({
-    message: 'Stack principal:',
-    placeholder: 'ej: Next.js, Supabase, Vercel',
+    message: 'Main stack:',
+    placeholder: 'e.g.: Next.js, Supabase, Vercel',
     validate: (val) => {
-      if (!val) return 'El stack es requerido';
+      if (!val) return 'Stack is required';
     },
   });
-  if (p.isCancel(stack)) { p.cancel('Cancelado.'); return; }
+  if (p.isCancel(stack)) { p.cancel('Cancelled.'); return; }
 
   // ─── GitHub ─────────────────────────────────────────────────────────────────
   let github = null;
   const hasRepo = await p.confirm({
-    message: 'Tiene repositorio GitHub?',
+    message: 'Has a GitHub repository?',
     initialValue: true,
   });
 
   if (!p.isCancel(hasRepo) && hasRepo) {
     const repoUrl = await p.text({
-      message: 'URL del repositorio:',
+      message: 'Repository URL:',
       placeholder: 'https://github.com/org/repo',
       validate: (val) => {
-        if (!val) return 'La URL es requerida';
-        if (!val.includes('github.com')) return 'Debe ser una URL de GitHub';
+        if (!val) return 'URL is required';
+        if (!val.includes('github.com')) return 'Must be a GitHub URL';
       },
     });
     if (!p.isCancel(repoUrl)) {
@@ -86,15 +86,15 @@ export async function runInit() {
     }
   }
 
-  // ─── Codigo existente ───────────────────────────────────────────────────────
+  // ─── Existing code ────────────────────────────────────────────────────────
   const hasExistingCode = await p.confirm({
-    message: 'Tiene codigo existente?',
+    message: 'Has existing code?',
     initialValue: true,
   });
 
-  // ─── Generacion ─────────────────────────────────────────────────────────────
+  // ─── Generation ───────────────────────────────────────────────────────────
   const spinner = p.spinner();
-  spinner.start('Generando estructura Guild v1...');
+  spinner.start('Generating Guild v1 structure...');
 
   const projectData = {
     name,
@@ -106,35 +106,35 @@ export async function runInit() {
 
   try {
     await copyTemplates();
-    spinner.message('Generando CLAUDE.md...');
+    spinner.message('Generating CLAUDE.md...');
     await generateClaudeMd(projectData);
 
-    spinner.message('Generando PROJECT.md...');
+    spinner.message('Generating PROJECT.md...');
     await generateProjectMd(projectData);
 
-    spinner.message('Generando SESSION.md...');
+    spinner.message('Generating SESSION.md...');
     await generateSessionMd();
 
-    spinner.stop('Estructura creada.');
+    spinner.stop('Structure created.');
   } catch (error) {
-    spinner.stop('Error durante la inicializacion.');
+    spinner.stop('Error during initialization.');
     throw error;
   }
 
-  // ─── Resumen ────────────────────────────────────────────────────────────────
+  // ─── Summary ──────────────────────────────────────────────────────────────
   p.log.success('CLAUDE.md');
   p.log.success('PROJECT.md');
   p.log.success('SESSION.md');
-  p.log.success('.claude/agents/    (8 agentes base)');
+  p.log.success('.claude/agents/    (8 base agents)');
   p.log.success('.claude/skills/    (10 skills)');
 
   p.note(
-    'Abre Claude Code en este directorio y ejecuta:\n\n' +
+    'Open Claude Code in this directory and run:\n\n' +
     '  /guild-specialize\n\n' +
-    'Este skill explorara tu codigo y enriquecera CLAUDE.md\n' +
-    'con la informacion real del proyecto.',
-    'Siguiente paso'
+    'This skill will explore your code and enrich CLAUDE.md\n' +
+    'with the actual project information.',
+    'Next step'
   );
 
-  p.outro(chalk.bold.cyan('Guild v1 listo.'));
+  p.outro(chalk.bold.cyan('Guild v1 ready.'));
 }

package/src/commands/new-agent.js

@@ -1,12 +1,12 @@
 /**
- * new-agent.js — Crea un nuevo agente v1 (archivo plano)
+ * new-agent.js — Creates a new v1 agent (plain file)
  *
- * Flujo:
- * 1. Validar nombre (lowercase, guiones, sin espacios)
- * 2. Verificar que Guild esta instalado
- * 3. Verificar que el agente NO existe
- * 4. Pedir descripcion del agente
- * 5. Crear .claude/agents/[nombre].md con placeholder
+ * Flow:
+ * 1. Validate name (lowercase, hyphens, no spaces)
+ * 2. Verify that Guild is installed
+ * 3. Verify that the agent does NOT exist
+ * 4. Ask for agent description
+ * 5. Create .claude/agents/[name].md with placeholder
  */
 
 import * as p from '@clack/prompts';
@@ -17,35 +17,35 @@ import { join } from 'path';
 const AGENTS_DIR = join('.claude', 'agents');
 
 export async function runNewAgent(agentName) {
-  p.intro(chalk.bold.cyan('Guild — Nuevo agente'));
+  p.intro(chalk.bold.cyan('Guild — New agent'));
 
-  // Validar nombre
+  // Validate name
   if (!isValidAgentName(agentName)) {
-    throw new Error(`Nombre invalido: "${agentName}". Solo lowercase, numeros y guiones. Ejemplo: guild new-agent security-auditor`);
+    throw new Error(`Invalid name: "${agentName}". Only lowercase, numbers, and hyphens allowed. Example: guild new-agent security-auditor`);
   }
 
-  // Verificar Guild instalado
+  // Verify Guild is installed
   if (!existsSync(AGENTS_DIR)) {
-    throw new Error('Guild no esta instalado. Ejecuta: guild init');
+    throw new Error('Guild is not installed. Run: guild init');
   }
 
-  // Verificar que el agente NO existe
+  // Verify that the agent does NOT exist
   const agentPath = join(AGENTS_DIR, `${agentName}.md`);
   if (existsSync(agentPath)) {
-    throw new Error(`El agente "${agentName}" ya existe.`);
+    throw new Error(`Agent "${agentName}" already exists.`);
   }
 
-  // Pedir descripcion
+  // Ask for description
   const description = await p.text({
-    message: `Que hace "${agentName}"? (descripcion corta):`,
-    placeholder: 'ej: Evalua oportunidades de trading basado en analisis tecnico',
-    validate: (val) => !val ? 'La descripcion es requerida' : undefined,
+    message: `What does "${agentName}" do? (short description):`,
+    placeholder: 'e.g.: Evaluates trading opportunities based on technical analysis',
+    validate: (val) => !val ? 'Description is required' : undefined,
   });
-  if (p.isCancel(description)) { p.cancel('Cancelado.'); return; }
+  if (p.isCancel(description)) { p.cancel('Cancelled.'); return; }
 
-  // Crear agente
+  // Create agent
   const spinner = p.spinner();
-  spinner.start(`Creando agente "${agentName}"...`);
+  spinner.start(`Creating agent "${agentName}"...`);
 
   try {
     const content = `---
@@ -55,34 +55,34 @@ description: "${description}"
 
 # ${agentName}
 
-Eres ${agentName} de [PROYECTO].
+You are ${agentName} of [PROJECT].
 
-## Responsabilidades
-[Definir con /guild-specialize]
+## Responsibilities
+[Define with /guild-specialize]
 
-## Lo que NO haces
-[Definir con /guild-specialize]
+## What you do NOT do
+[Define with /guild-specialize]
 
-## Proceso
-[Definir con /guild-specialize]
+## Process
+[Define with /guild-specialize]
 
-## Reglas de comportamiento
-- Siempre lee CLAUDE.md y SESSION.md al inicio de la sesion
+## Behavioral rules
+- Always read CLAUDE.md and SESSION.md at the start of the session
 `;
 
     writeFileSync(agentPath, content, 'utf8');
 
-    spinner.stop(`Agente "${agentName}" creado.`);
+    spinner.stop(`Agent "${agentName}" created.`);
 
-    p.log.success(`Archivo: ${agentPath}`);
+    p.log.success(`File: ${agentPath}`);
     p.note(
-      `Ejecuta /guild-specialize para que Claude\n` +
-      `genere las instrucciones completas de "${agentName}".`,
-      'Especializacion pendiente'
+      `Run /guild-specialize so that Claude\n` +
+      `generates the full instructions for "${agentName}".`,
+      'Specialization pending'
     );
-    p.outro(chalk.bold.cyan(`Agente ${agentName} listo.`));
+    p.outro(chalk.bold.cyan(`Agent ${agentName} ready.`));
   } catch (error) {
-    spinner.stop('Error al crear agente.');
+    spinner.stop('Error creating agent.');
     throw error;
   }
 }

package/src/commands/status.js

@@ -1,5 +1,5 @@
 /**
- * status.js — Muestra el estado actual del proyecto v1
+ * status.js — Shows the current project status v1
  */
 
 import * as p from '@clack/prompts';
@@ -9,13 +9,13 @@ import { join } from 'path';
 
 export async function runStatus() {
   if (!existsSync('PROJECT.md')) {
-    throw new Error('Guild no esta instalado. Ejecuta: guild init');
+    throw new Error('Guild is not installed. Run: guild init');
   }
 
   const projectMd = readFileSync('PROJECT.md', 'utf8');
-  const nameMatch = projectMd.match(/\*\*Nombre:\*\*\s*(.+)/);
+  const nameMatch = projectMd.match(/\*\*Name:\*\*\s*(.+)/);
   const stackMatch = projectMd.match(/\*\*Stack:\*\*\s*(.+)/);
-  const projectName = nameMatch ? nameMatch[1].trim() : 'Proyecto';
+  const projectName = nameMatch ? nameMatch[1].trim() : 'Project';
 
   p.intro(chalk.bold.cyan(`Guild — ${projectName}`));
 
@@ -23,20 +23,20 @@ export async function runStatus() {
     p.log.info(chalk.gray(`Stack: ${stackMatch[1].trim()}`));
   }
 
-  // Sesion activa
+  // Active session
   if (existsSync('SESSION.md')) {
-    p.log.step('Sesion activa');
+    p.log.step('Active session');
     const sessionMd = readFileSync('SESSION.md', 'utf8');
-    const taskMatch = sessionMd.match(/\*\*Tarea en curso:\*\*\s*(.+)/);
-    const stateMatch = sessionMd.match(/\*\*Estado:\*\*\s*(.+)/);
-    if (taskMatch && taskMatch[1].trim() !== '—') p.log.info(`  Tarea: ${taskMatch[1].trim()}`);
+    const taskMatch = sessionMd.match(/\*\*Current task:\*\*\s*(.+)/);
+    const stateMatch = sessionMd.match(/\*\*Status:\*\*\s*(.+)/);
+    if (taskMatch && taskMatch[1].trim() !== '—') p.log.info(`  Task: ${taskMatch[1].trim()}`);
     if (stateMatch) p.log.info(chalk.gray(`  ${stateMatch[1].trim()}`));
   }
 
-  // Agentes
+  // Agents
   const agentsDir = join('.claude', 'agents');
   if (existsSync(agentsDir)) {
-    p.log.step('Agentes');
+    p.log.step('Agents');
     const agents = readdirSync(agentsDir)
       .filter(f => f.endsWith('.md'))
       .map(f => f.replace('.md', ''));