guild-agents 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guild-agents",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "A multi-agent framework for Claude Code — specialized AI teams for every project",
   "type": "module",
   "files": [
@@ -45,7 +45,7 @@
     "type": "git",
     "url": "git+https://github.com/guild-agents/guild.git"
   },
-  "homepage": "https://github.com/guild-agents/guild",
+  "homepage": "https://guildagents.dev",
   "bugs": {
     "url": "https://github.com/guild-agents/guild/issues"
   },

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, getSkillNames } from '../utils/files.js';
 
 export async function runInit() {
   console.log('');
@@ -122,19 +122,24 @@ export async function runInit() {
   }
 
   // ─── Summary ──────────────────────────────────────────────────────────────
-  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/skills/    (10 skills)');
-
-  p.note(
-    'Open Claude Code in this directory and run:\n\n' +
-    '  /guild-specialize\n\n' +
-    'This skill will explore your code and enrich CLAUDE.md\n' +
-    'with the actual project information.',
-    'Next step'
-  );
+  const agentCount = getAgentNames().length;
+  const skillCount = getSkillNames().length;
+  p.log.success(`Created: CLAUDE.md, PROJECT.md, SESSION.md, ${agentCount} agents, ${skillCount} skills`);
+
+  const relevantSkills = projectData.hasExistingCode
+    ? ['/guild-specialize', '/build-feature', '/review']
+    : ['/build-feature', '/new-feature', '/council'];
+  p.log.info(`Start with: ${relevantSkills.join('  ')}`);
+
+  const quickStart = projectData.hasExistingCode
+    ? '1. Open Claude Code in this directory\n' +
+      '2. Run /guild-specialize to analyze your codebase\n' +
+      '3. Start building with /build-feature'
+    : '1. Open Claude Code in this directory\n' +
+      '2. Start building with /build-feature\n' +
+      '3. Run /guild-specialize once you have code';
+
+  p.note(quickStart, 'Quick start');
 
   p.outro(chalk.bold.cyan('Guild v1 ready.'));
 }

package/src/commands/list.js

@@ -6,24 +6,7 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
-
-/**
- * Parses YAML frontmatter from a markdown file content.
- * Returns an object with key-value pairs from the frontmatter.
- */
-function parseFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return {};
-  const fm = {};
-  for (const line of match[1].split('\n')) {
-    const colonIndex = line.indexOf(':');
-    if (colonIndex === -1) continue;
-    const key = line.slice(0, colonIndex).trim();
-    const value = line.slice(colonIndex + 1).trim().replace(/^["']|["']$/g, '');
-    if (key && value) fm[key] = value;
-  }
-  return fm;
-}
+import { parseFrontmatter } from '../utils/files.js';
 
 export async function runList() {
   p.intro(chalk.bold.cyan('Guild — Agents & Skills'));

package/src/templates/skills/build-feature/SKILL.md

@@ -35,8 +35,31 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 
 ## 6-Phase Pipeline
 
+### Progress Display
+
+At the start of each phase, display a progress indicator to the user before any agent output:
+
+```text
+[1/6] Advisor — Evaluating feature...
+[2/6] Product Owner — Defining spec...
+[3/6] Tech Lead — Defining technical approach...
+[4/6] Developer — Implementing...
+[5/6] Code Reviewer — Reviewing changes...
+[6/6] QA — Validating acceptance criteria...
+```
+
+When a phase loops (review-fix or QA-review cycles), show the iteration:
+
+```text
+[5/6 · round 2] Code Reviewer — Re-reviewing after fixes...
+[4/6 · round 2] Developer — Fixing review blockers...
+```
+
+This indicator MUST be displayed before spawning the agent for that phase.
+
 ### Phase 1 — Evaluation (Advisor)
 
+**Progress:** `[1/6] Advisor — Evaluating feature...`
 **Agent:** Reads `.claude/agents/advisor.md` via Task tool
 **Input:** The feature description provided by the user
 **Process:**
@@ -50,6 +73,7 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 
 ### Phase 2 — Specification (Product Owner)
 
+**Progress:** `[2/6] Product Owner — Defining spec...`
 **Agent:** Reads `.claude/agents/product-owner.md` via Task tool
 **Input:** The feature approved by the Advisor + their observations
 **Process:**
@@ -62,6 +86,7 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 
 ### Phase 3 — Technical Approach (Tech Lead)
 
+**Progress:** `[3/6] Tech Lead — Defining technical approach...`
 **Agent:** Reads `.claude/agents/tech-lead.md` via Task tool
 **Input:** Product Owner tasks + acceptance criteria
 **Process:**
@@ -74,6 +99,7 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 
 ### Phase 4 — Implementation (Developer)
 
+**Progress:** `[4/6] Developer — Implementing...`
 **Agent:** Reads `.claude/agents/developer.md` via Task tool
 **Input:** Tech Lead technical plan + PO acceptance criteria
 **Process:**
@@ -97,6 +123,7 @@ This gate CANNOT be skipped, even if the user requested phase skipping. The spec
 
 ### Phase 5 — Review (Code Reviewer)
 
+**Progress:** `[5/6] Code Reviewer — Reviewing changes...`
 **Agent:** Reads `.claude/agents/code-reviewer.md` via Task tool
 **Input:** The implemented changes (git diff)
 **Process:**
@@ -109,6 +136,8 @@ This gate CANNOT be skipped, even if the user requested phase skipping. The spec
 
 ### Phase 6 — QA (delegates to /qa-cycle)
 
+**Progress:** `[6/6] QA — Validating acceptance criteria...`
+
 Runs the `/qa-cycle` skill passing the PO acceptance criteria as context. The qa-cycle handles:
 
 1. Running project tests and lint
@@ -197,12 +226,23 @@ Task tool with:
 ```text
 User: /build-feature add dark mode toggle to settings page
 
-Phase 1 — Advisor: Approved. Low risk, aligns with UX roadmap.
-Phase 2 — PO: 3 tasks defined with acceptance criteria.
-Phase 3 — Tech Lead: Use CSS variables + context provider pattern.
-Phase 4 — Developer: Implemented ThemeContext, toggle component, CSS vars.
-Phase 5 — Review: Passed. 1 suggestion (memoize context value).
-Phase 6 — QA: All 3 acceptance criteria verified. 0 bugs.
+[1/6] Advisor — Evaluating feature...
+  Approved. Low risk, aligns with UX roadmap.
+
+[2/6] Product Owner — Defining spec...
+  3 tasks defined with acceptance criteria.
+
+[3/6] Tech Lead — Defining technical approach...
+  Use CSS variables + context provider pattern.
+
+[4/6] Developer — Implementing...
+  Implemented ThemeContext, toggle component, CSS vars.
+
+[5/6] Code Reviewer — Reviewing changes...
+  Passed. 1 suggestion (memoize context value).
+
+[6/6] QA — Validating acceptance criteria...
+  All 3 acceptance criteria verified. 0 bugs.
 
 Feature complete. PR ready for merge.
 ```

package/src/templates/skills/create-pr/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: create-pr
+description: "Create a pull request from the current branch with structured summary"
+user-invocable: true
+---
+
+# Create PR
+
+Creates a pull request from the current feature branch with a structured summary, test results, and change description. Closes the pipeline loop: init -> build-feature -> create-pr.
+
+## When to use
+
+- After completing a feature with `/build-feature`
+- When you have changes on a feature branch ready for review
+- To create a well-structured PR without manual formatting
+
+## Usage
+
+`/create-pr`
+
+## Process
+
+### Step 1 -- Verify branch state
+
+1. Confirm you are NOT on `main` or `develop` -- refuse to create PR from default branches
+2. Run `git status` to check for uncommitted changes -- if any, warn the user and ask whether to commit first
+3. Run `git log main..HEAD --oneline` to get the list of commits that will be in the PR
+4. If there are no commits ahead of main, report that there is nothing to PR
+
+### Step 2 -- Gather context
+
+Collect the information needed for the PR description:
+
+1. **Commits**: `git log main..HEAD --oneline` -- list of all commits on this branch
+2. **Diff summary**: `git diff main..HEAD --stat` -- files changed with line counts
+3. **Test results**: Run project tests (e.g., `npm test`) and capture pass/fail
+4. **Lint results**: Run project lint (e.g., `npm run lint`) and capture pass/fail
+5. **Branch name**: Extract feature name from the branch (e.g., `feature/dark-mode` -> `dark-mode`)
+
+If tests or lint fail, warn the user but allow them to proceed (some PRs are draft/WIP).
+
+### Step 3 -- Generate PR description
+
+Build a structured PR description:
+
+```markdown
+## Summary
+[2-4 bullet points describing what this PR does, derived from commit messages]
+
+## Changes
+[File-level summary from git diff --stat]
+
+## Test plan
+- [x] Tests: [pass/fail] ([count] tests)
+- [x] Lint: [pass/fail]
+- [ ] [Any manual verification steps if applicable]
+```
+
+### Step 4 -- Create the PR
+
+1. Push the branch to origin: `git push -u origin [branch-name]`
+2. Create the PR using `gh pr create`:
+   - Title: derived from branch name or first commit message (max 70 chars)
+   - Body: the generated description from Step 3
+   - Base: `main` (or the project's default branch)
+3. Report the PR URL to the user
+
+### Step 5 -- Post-creation
+
+1. Display the PR URL
+2. Suggest next steps:
+   - "Request review from a teammate"
+   - "Run `/review` for an AI code review"
+   - "Merge when ready with `gh pr merge [number]`"
+
+## Example Session
+
+```text
+User: /create-pr
+
+Checking branch state...
+Branch: feature/dark-mode (4 commits ahead of main)
+Tests: 82 passed, 0 failed
+Lint: 0 errors
+
+Creating PR...
+PR #42: "feat: add dark mode toggle to settings"
+https://github.com/org/repo/pull/42
+
+Next steps:
+- Request review from a teammate
+- Run /review for AI code review
+- Merge when ready
+```
+
+## Notes
+
+- The PR title should be concise (under 70 characters) and follow conventional commits format when the project uses it
+- If the branch has `wip:` commits from build-feature checkpoints, consider squashing them before creating the PR
+- This skill does NOT merge the PR -- that is a manual step or a separate command

package/src/utils/files.js

@@ -12,20 +12,56 @@ const AGENTS_DIR = join('.claude', 'agents');
 const SKILLS_DIR = join('.claude', 'skills');
 
 /**
- * Returns the names of the 9 v1 agents.
+ * Returns the names of the v1 agents by reading the templates directory.
+ * Adding a new .md file to src/templates/agents/ automatically includes it.
  */
 export function getAgentNames() {
-  return [
-    'advisor',
-    'product-owner',
-    'tech-lead',
-    'developer',
-    'code-reviewer',
-    'qa',
-    'bugfix',
-    'db-migration',
-    'platform-expert',
-  ];
+  const agentsDir = join(TEMPLATES_DIR, 'agents');
+  if (!existsSync(agentsDir)) {
+    return [];
+  }
+  return readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace('.md', ''))
+    .sort();
+}
+
+/**
+ * Returns the names of the v1 skills by reading the templates directory.
+ * Adding a new directory to src/templates/skills/ automatically includes it.
+ */
+export function getSkillNames() {
+  const skillsDir = join(TEMPLATES_DIR, 'skills');
+  if (!existsSync(skillsDir)) {
+    return [];
+  }
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .sort();
+}
+
+/**
+ * Parses YAML frontmatter from markdown content.
+ * Returns an object with { name, description, ...other fields } or empty object if no frontmatter.
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const frontmatter = {};
+  for (const line of match[1].split('\n')) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    let value = line.slice(colonIndex + 1).trim();
+    // Remove surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key) frontmatter[key] = value;
+  }
+  return frontmatter;
 }
 
 /**

package/src/utils/generators.js

@@ -31,6 +31,67 @@ export async function generateProjectMd(data) {
   writeFileSync('PROJECT.md', content, 'utf8');
 }
 
+/**
+ * Infers code conventions based on project type and stack.
+ * Rules accumulate (not exclusive). Deduplicates lines.
+ */
+export function inferCodeConventions(type, stack) {
+  const s = (stack || '').toLowerCase();
+  const rules = [];
+
+  // Stack-specific rules
+  if (s.includes('next') || s.includes('react')) {
+    rules.push('- Components in PascalCase', '- CSS Modules or Tailwind utility classes');
+  }
+  if (s.includes('express') || (s.includes('node') && type === 'api')) {
+    rules.push('- Controllers/routes pattern', '- Async/await error handling');
+  }
+  if (s.includes('typescript') || /\bts\b/.test(s)) {
+    rules.push('- Strict TypeScript', '- Interfaces over types where possible');
+  }
+
+  // Type-specific fallbacks (only if no stack rules matched)
+  if (rules.length === 0) {
+    if (type === 'cli') {
+      rules.push('- Commander.js command pattern', '- ESModules throughout');
+    } else if (type === 'api') {
+      rules.push('- REST or GraphQL endpoint conventions', '- Input validation on all endpoints');
+    } else {
+      rules.push('- Consistent naming conventions', '- ESModules throughout');
+    }
+  }
+
+  // Deduplicate
+  return [...new Set(rules)].join('\n');
+}
+
+/**
+ * Infers likely environment variables based on project type and stack.
+ * Rules accumulate. Deduplicates lines.
+ */
+export function inferEnvVars(type, stack) {
+  const s = (stack || '').toLowerCase();
+  const vars = [];
+
+  // Stack-specific
+  if (s.includes('supabase')) vars.push('- `SUPABASE_URL`', '- `SUPABASE_ANON_KEY`');
+  if (s.includes('firebase')) vars.push('- `FIREBASE_API_KEY`', '- `FIREBASE_PROJECT_ID`');
+  if (s.includes('postgres')) vars.push('- `DATABASE_URL`');
+  if (s.includes('redis')) vars.push('- `REDIS_URL`');
+  if (s.includes('stripe')) vars.push('- `STRIPE_SECRET_KEY`', '- `STRIPE_WEBHOOK_SECRET`');
+  if (s.includes('vercel')) vars.push('- `VERCEL_URL`');
+  if (/\baws\b/.test(s)) vars.push('- `AWS_ACCESS_KEY_ID`', '- `AWS_SECRET_ACCESS_KEY`', '- `AWS_REGION`');
+
+  // Type-specific fallbacks
+  if (vars.length === 0) {
+    if (type === 'webapp') vars.push('- `NODE_ENV`', '- `API_URL`');
+    else if (type === 'api') vars.push('- `NODE_ENV`', '- `PORT`', '- `DATABASE_URL`');
+    else vars.push('- `NODE_ENV`');
+  }
+
+  return [...new Set(vars)].join('\n');
+}
+
 /**
  * Generates CLAUDE.md — central document with placeholders for guild-specialize.
  */
@@ -47,13 +108,13 @@ ${data.stack}
 [PENDING: guild-specialize]
 
 ## Code conventions
-[PENDING: guild-specialize]
+${inferCodeConventions(data.type, data.stack)}
 
 ## Architecture patterns
 [PENDING: guild-specialize]
 
 ## Environment variables
-[PENDING: guild-specialize]
+${inferEnvVars(data.type, data.stack)}
 
 ## Global rules
 - Do not implement without an approved plan
@@ -72,6 +133,7 @@ ${data.stack}
 - /guild-specialize  — enrich CLAUDE.md by exploring the actual project
 - /build-feature     — full development pipeline
 - /new-feature       — create branch and scaffold for a feature
+- /create-pr         — create a structured pull request from current branch
 - /council           — debate decisions with multiple agents
 - /review            — code review on the current diff
 - /qa-cycle          — QA + bugfix cycle