guild-agents 0.2.9 → 0.3.1

package/README.md

@@ -5,37 +5,25 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-Claude Code is powerful but chaotic. Guild gives it structure.
+**Guild makes Claude Code think before it builds.**
 
-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.
+Guild is a spec-driven development CLI for Claude Code. It installs structured design and development workflows as `.claude/` markdown files in any project. Before code is written, features are evaluated, debated by independent AI perspectives, and specified in a design doc. Everything is markdown, tracked by git, works offline, zero infrastructure.
 
-## Why Guild?
+## The Problem
 
-- **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.
+Without structure, Claude Code:
 
-## How It Works
+- Writes code before understanding the problem
+- Has no design phase and no review gate
+- Loses decisions between sessions
+- Produces results that vary with every conversation
 
-```
-You ──> /build-feature "Add JWT auth"
-         │
-         ▼
-    ┌─────────┐     ┌───────────────┐     ┌───────────────┐
-    │ Advisor  │────>│  Tech Lead    │────>│  Developer    │
-    │ evaluate │     │  plan         │     │  implement    │
-    └─────────┘     └───────────────┘     └───────┬───────┘
-                                                  │
-                                    ┌─────────────┼─────────────┐
-                                    ▼             ▼             ▼
-                              ┌──────────┐ ┌──────────┐ ┌──────────┐
-                              │ Reviewer │ │    QA    │ │  Bugfix  │
-                              │ review   │ │  test    │ │  fix     │
-                              └──────────┘ └──────────┘ └──────────┘
-```
+## How Guild Solves It
 
-Skills orchestrate agents through structured pipelines. You invoke a skill as a slash command, and it coordinates the right agents in the right order.
+- **Spec before code**: every feature starts with a design doc
+- **Structured deliberation**: `/council` runs parallel independent analysis -- multiple perspectives evaluate independently, then synthesize
+- **Decisions that persist**: design docs, session state, and project context live in git-tracked markdown
+- **Zero infrastructure**: no servers, no APIs, just markdown files and Claude Code
 
 ## Quick Start
 
@@ -44,28 +32,68 @@ npm install -g guild-agents
 guild init
 ```
 
-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.
-
-Next, let Guild learn your codebase:
+Then use skills as slash commands in Claude Code:
 
+```text
+/guild-specialize        # Learn your codebase, enrich CLAUDE.md
+/council "Add JWT auth"  # Spec a feature through structured deliberation
+/build-feature           # Implement from spec through the full pipeline
 ```
-/guild-specialize
+
+## The Pipeline
+
+```text
+You ──> /council "Add JWT auth"
+         │
+         ▼
+    ┌──────────┐     ┌──────────────┐     ┌──────────┐
+    │ Evaluate │────>│  Design Doc  │────>│  Build   │
+    │ debate   │     │  spec        │     │ implement│
+    └──────────┘     └──────────────┘     └────┬─────┘
+                                               │
+                                         ┌─────┴─────┐
+                                         ▼           ▼
+                                   ┌──────────┐┌──────────┐
+                                   │  Review  ││    QA    │
+                                   └──────────┘└──────────┘
 ```
 
-This explores your actual code and enriches `CLAUDE.md` with real conventions, patterns, and stack details. Every agent now understands your project.
+Six phases: **evaluate**, **specify**, **plan**, **implement**, **review**, **validate**. Phases 1-3 happen before any code is written.
 
-Then build something:
+## Skills Reference
 
-```
-/build-feature Add user authentication with JWT
+All 11 skills, grouped by function:
+
+| Skill | Group | Description |
+| --- | --- | --- |
+| `/build-feature` | Pipeline | Full pipeline: evaluate, spec, implement, review, QA |
+| `/new-feature` | Pipeline | Create branch and scaffold for a new feature |
+| `/create-pr` | Pipeline | Create a structured pull request from current branch |
+| `/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 |
+| `/guild-specialize` | Context | Explore codebase, enrich CLAUDE.md with real conventions |
+| `/session-start` | Context | Load context and resume work |
+| `/session-end` | Context | Save state to SESSION.md |
+| `/status` | Context | Project and session state overview |
+| `/dev-flow` | Context | Show current pipeline phase and next step |
+
+## CLI Commands
+
+```bash
+guild init              # Interactive project onboarding
+guild new-agent <name>  # Create a custom agent
+guild status            # Show project status
+guild doctor            # Diagnose setup
+guild list              # List agents and skills
 ```
 
-This runs the full pipeline -- advisor evaluation, tech lead planning, developer implementation, code review, and QA -- all coordinated automatically.
+## Under the Hood
 
-## Agents
+Guild coordinates 9 specialized agents through the pipeline. Each agent handles one phase.
 
 | Agent | Role |
-|---|---|
+| --- | --- |
 | advisor | Evaluates ideas and provides strategic direction |
 | product-owner | Turns approved ideas into concrete tasks |
 | tech-lead | Defines technical approach and architecture |
@@ -74,70 +102,13 @@ This runs the full pipeline -- advisor evaluation, tech lead planning, developer
 | 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
-
-| 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
-guild doctor                # Diagnose installation state
-guild list                  # List installed agents and skills
-```
-
-## Generated Structure
+| platform-expert | Diagnoses Claude Code integration issues |
 
-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
-    platform-expert.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.
+Agents are flat `.md` files with identity and expertise. Skills orchestrate agents through structured pipelines. Everything lives in `.claude/`, readable by humans, tracked by git.
 
 ## 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.
+Every feature in Guild goes through the same spec-first pipeline that Guild installs in your project. Guild's own design decisions live in `docs/specs/`.
 
 ## Requirements
 
@@ -147,12 +118,7 @@ This project uses its own agents and skills to develop itself. Every feature, re
 
 ## 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.
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for setup, branching, and contribution guidelines.
 
 ## License
 

package/bin/guild.js

@@ -20,7 +20,7 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'))
 
 program
   .name('guild')
-  .description('Multi-agent framework for Claude Code')
+  .description('Specification-driven development CLI for Claude Code')
   .version(pkg.version);
 
 // guild init

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "guild-agents",
-  "version": "0.2.9",
-  "description": "A multi-agent framework for Claude Code — specialized AI teams for every project",
+  "version": "0.3.1",
+  "description": "Specification-driven development CLI for Claude Code — think before you build",
   "type": "module",
   "files": [
     "bin/",
@@ -26,15 +26,16 @@
   "keywords": [
     "claude",
     "claude-code",
+    "anthropic",
+    "specification-driven",
+    "spec-driven",
+    "spec-first",
+    "design-docs",
+    "developer-tools",
+    "cli",
     "agents",
     "ai",
     "workflow",
-    "multi-agent",
-    "developer-tools",
-    "cli",
-    "framework",
-    "anthropic",
-    "ai-agents",
     "automation",
     "code-review",
     "nodejs"
@@ -45,14 +46,15 @@
     "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"
   },
   "dependencies": {
     "@clack/prompts": "^1.0.1",
     "chalk": "^5.3.0",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "guild-agents": "^0.3.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/commands/doctor.js

@@ -6,8 +6,14 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { resolveProjectRoot } from '../utils/files.js';
 
 export async function runDoctor() {
+  const root = resolveProjectRoot();
+  if (root) {
+    process.chdir(root);
+  }
+
   p.intro(chalk.bold.cyan('Guild — Doctor'));
 
   const checks = [];

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, getAgentNames } 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/    (${getAgentNames().length} 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'
-  );
-
-  p.outro(chalk.bold.cyan('Guild v1 ready.'));
+  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', '/council', '/build-feature']
+    : ['/council', '/build-feature', '/new-feature'];
+  p.log.info(`Start with: ${relevantSkills.join('  ')}`);
+
+  const quickStart = projectData.hasExistingCode
+    ? '1. Run /guild-specialize to analyze your codebase\n' +
+      '2. Run /council to spec your first feature\n' +
+      '3. Build it with /build-feature'
+    : '1. Run /council to spec your first feature\n' +
+      '2. Build it with /build-feature\n' +
+      '3. Run /guild-specialize once you have code';
+
+  p.note(quickStart, 'Quick start');
+
+  p.outro(chalk.bold.cyan('Guild ready — spec before you build.'));
 }

package/src/commands/list.js

@@ -6,26 +6,11 @@ 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 { ensureProjectRoot, parseFrontmatter } from '../utils/files.js';
 
 export async function runList() {
+  ensureProjectRoot();
+
   p.intro(chalk.bold.cyan('Guild — Agents & Skills'));
 
   // List agents

package/src/commands/new-agent.js

@@ -13,10 +13,13 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { existsSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { ensureProjectRoot } from '../utils/files.js';
 
 const AGENTS_DIR = join('.claude', 'agents');
 
 export async function runNewAgent(agentName) {
+  ensureProjectRoot();
+
   p.intro(chalk.bold.cyan('Guild — New agent'));
 
   // Validate name

package/src/commands/status.js

@@ -6,11 +6,10 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { ensureProjectRoot } from '../utils/files.js';
 
 export async function runStatus() {
-  if (!existsSync('PROJECT.md')) {
-    throw new Error('Guild is not installed. Run: guild init');
-  }
+  ensureProjectRoot();
 
   const projectMd = readFileSync('PROJECT.md', 'utf8');
   const nameMatch = projectMd.match(/\*\*Name:\*\*\s*(.+)/);

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:**
@@ -46,10 +69,12 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 3. Issues evaluation: Approved / Rejected / Requires adjustments
 
 **Output:** Evaluation with reasoning and identified risks
+**Trace data:** Verdict (Approved/Rejected/Approved with conditions), risks identified, conditions if any
 **Exit condition:** If the Advisor rejects the feature, the pipeline stops here. Inform the user of the reason and suggest adjustments if any.
 
 ### 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:**
@@ -59,9 +84,11 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 3. Estimates effort and suggests implementation order
 
 **Output:** Task list with acceptance criteria, estimation, and order
+**Trace data:** Tasks defined count, acceptance criteria count, estimated effort
 
 ### 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:**
@@ -71,9 +98,11 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 3. Anticipates technical risks and proposes mitigations
 
 **Output:** Technical plan with files, patterns, interfaces, and risks
+**Trace data:** Key patterns identified, files to modify, technical risks
 
 ### 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:**
@@ -84,6 +113,7 @@ When running a single build-feature, a simple `git checkout -b` is sufficient.
 4. Verifies that tests pass
 
 **Output:** Implemented code + tests + commits made
+**Trace data:** Files created/modified, tests added, commits made
 
 ### Pre-Review Gate (mandatory)
 
@@ -95,8 +125,11 @@ Before advancing to Phase 5, run automated verification:
 
 This gate CANNOT be skipped, even if the user requested phase skipping. The specific commands are in the "CLI commands" section of CLAUDE.md.
 
+**Trace data:** Tests pass/fail, lint pass/fail
+
 ### 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:**
@@ -105,10 +138,13 @@ This gate CANNOT be skipped, even if the user requested phase skipping. The spec
 2. Classifies findings as Blocker, Warning, or Suggestion
 
 **Output:** Review report with classified findings
+**Trace data:** Blockers count, warnings count, suggestions count, review-fix loops
 **Loop condition:** If there are Blocker findings, return to **Phase 4** for the Developer to fix them. Maximum 2 review-fix iterations.
 
 ### 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
@@ -116,6 +152,7 @@ Runs the `/qa-cycle` skill passing the PO acceptance criteria as context. The qa
 3. Testing edge cases and error scenarios
 4. Bugfix cycle if issues arise (maximum 3 cycles)
 
+**Trace data:** Acceptance criteria verified count, bugs found, QA cycles
 **Additional loop condition:** If the qa-cycle bugfix introduces significant changes, return to **Phase 5** (Review) for verification. Maximum 2 review-QA cycles.
 
 ## Checkpoint Commits
@@ -132,7 +169,7 @@ Pattern for each phase:
 - After Phase 1: `wip: [feature] phase 1 — advisor approved`
 - After Phase 2: `wip: [feature] phase 2 — PO spec ready`
 - After Phase 3: `wip: [feature] phase 3 — tech approach defined`
-- After Phase 4: `wip: [feature] phase 4 — implementation done`
+- After Phase 4: `wip: [feature] phase 4 — implementation done` -- also write partial trace (phases 1-4) to spec and update status to `implementing`
 - After Phase 5: `wip: [feature] phase 5 — review passed`
 - After Phase 6: `wip: [feature] phase 6 — QA passed`
 
@@ -142,6 +179,110 @@ Also update SESSION.md at each phase transition:
 - [timestamp] | build-feature | Phase N ([phase-name]) complete for [feature]
 ```
 
+## Pipeline Trace
+
+After pipeline completion, append a `## Pipeline Trace` section to the feature's spec file in `docs/specs/`. This provides a structured record of what happened in each phase.
+
+### Spec file discovery
+
+1. Search `docs/specs/` for a file whose `spec-id` frontmatter matches the feature name (kebab-case)
+2. If no matching spec exists, auto-create a minimal spec file at `docs/specs/[feature-name].md`
+
+### Auto-created spec format
+
+When no prior council spec exists, create a minimal spec:
+
+````markdown
+---
+spec-id: [feature-name]
+status: implementing
+date: [YYYY-MM-DD]
+council-type: none (pipeline-generated)
+---
+
+# Spec: [Feature Name]
+
+## Context
+
+Spec auto-generated by /build-feature pipeline. No prior council session.
+
+## Pipeline Trace
+
+[trace content appended here]
+````
+
+### Status field updates
+
+- At Phase 4 checkpoint: set `status: implementing`
+- At pipeline completion: set `status: implemented`
+
+### Trace section format
+
+Append this section to the spec file:
+
+````markdown
+## Pipeline Trace
+
+pipeline-start: [YYYY-MM-DD]
+pipeline-end: [YYYY-MM-DD]
+phases-completed: [N]/6
+review-fix-loops: [N]
+qa-cycles: [N]
+final-gate: pass | fail
+
+### Phase 1 — Evaluation
+
+- **Verdict**: [Approved/Rejected/Approved with conditions]
+- **Risks identified**: [list or "None"]
+
+### Phase 2 — Specification
+
+- **Tasks defined**: [N]
+- **Acceptance criteria**: [N]
+- **Estimated effort**: [summary]
+
+### Phase 3 — Technical Approach
+
+- **Key patterns**: [list]
+- **Files to modify**: [list]
+- **Technical risks**: [list or "None"]
+
+### Phase 4 — Implementation
+
+- **Files created/modified**: [list]
+- **Tests added**: [N]
+- **Commits**: [list of commit summaries]
+
+### Pre-Review Gate
+
+- **Tests**: pass | fail
+- **Lint**: pass | fail
+
+### Phase 5 — Review
+
+- **Blockers**: [N]
+- **Warnings**: [N]
+- **Suggestions**: [N]
+- **Review-fix loops**: [N]
+
+### Phase 6 — QA
+
+- **Acceptance criteria verified**: [N]/[total]
+- **Bugs found**: [N]
+- **QA cycles**: [N]
+
+### Final Gate
+
+- **Tests**: pass | fail
+- **Lint**: pass | fail
+- **Result**: pass | fail
+````
+
+### When to write the trace
+
+- **Phase 4 checkpoint:** Write a partial trace covering phases 1-4 to the spec file. Set status to `implementing`. Include the spec file in the checkpoint commit.
+- **Pipeline completion:** Write the complete trace (all phases) to the spec file. Set status to `implemented`. Include the spec file in the final checkpoint commit.
+
 ## Final Gate (mandatory before Completion)
 
 Before declaring the pipeline as complete, run final verification:
@@ -152,23 +293,27 @@ Before declaring the pipeline as complete, run final verification:
 
 This gate is the last safety net. It CANNOT be skipped under any circumstances.
 
+**Trace data:** Tests pass/fail, lint pass/fail, result (pass/fail)
+
 ## Completion
 
 Upon successfully completing all phases and the final gate:
 
-1. Present pipeline summary:
+1. Write the complete Pipeline Trace to the spec file (see "Pipeline Trace" section above). Update the spec status to `implemented`. Include the spec file in the final checkpoint commit.
+
+2. Present pipeline summary:
    - Feature implemented
    - Files modified/created
    - Tests run and result
    - Review issues resolved
    - Final QA result
 
-2. Update `SESSION.md` with:
+3. Update `SESSION.md` with:
    - Feature completed
    - Decisions made during the pipeline
    - Next steps if any
 
-3. Close the GitHub Issue (if applicable):
+4. Close the GitHub Issue (if applicable):
    - Do NOT use `Closes #N` in PR description (only works when merging to default branch)
    - After the PR is merged, run: `gh issue close N --comment "Resolved in PR #X"`
 
@@ -197,12 +342,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/council/SKILL.md

@@ -111,6 +111,33 @@ Present clear options to the user based on the debate:
 
 Ask the user to decide. If the user decides, document the decision in SESSION.md.
 
+### Step 5 — Write Spec Document
+
+After the user makes their decision in Step 4, offer to write a spec document to `docs/specs/`.
+
+1. **Suggest filename**: Derive a kebab-case filename (3-5 words) from the council question. Present the suggested filename to the user for confirmation. Example: `docs/specs/graphql-migration-strategy.md`
+2. **Create directory**: Create `docs/specs/` if it does not already exist.
+3. **Read the spec template**: Read `src/templates/specs/SPEC_TEMPLATE.md` (or the project's local copy) to use as the structural guide.
+4. **Assemble spec content**: Map the council debate to the template format:
+   - **Title**: From the council question
+   - **spec-id**: Matches the filename (without `.md`)
+   - **status**: Always `draft`
+   - **date**: Current date in `YYYY-MM-DD` format
+   - **council-type**: From Step 1 (architecture, feature-scope, or tech-debt)
+   - **Context**: From the council question and background provided by the user
+   - **Decision**: The user's chosen option from Step 4
+   - **Constraints**: Extracted from agent arguments during the debate
+   - **Acceptance Criteria**: Derived from the decision, as checkboxes (`- [ ]`)
+   - **Technical Approach**: Synthesis of implementation details from agents
+   - **Trade-offs Considered**: Options A/B/C from Step 4 with their pros and cons
+   - **Unresolved Questions**: Open risks and unknowns identified during debate
+   - **Test Strategy**: How to verify the implementation meets the acceptance criteria
+   - **Council Perspectives**: Summary of each agent's independent position
+   - **Points of Dissent**: Where agents disagreed and how it was resolved, or "None — consensus reached"
+5. **Write the file**: Use the Write tool to create the spec at `docs/specs/<filename>.md`.
+6. **Report**: Tell the user the file path of the written spec.
+7. **Trivial decisions**: For trivial or low-impact decisions, offer SESSION.md-only logging instead of a full spec document.
+
 ## Subagent Configuration
 
 When spawning council agents via the Task tool, always use `subagent_type: "general-purpose"`. Guild agent role names (advisor, developer, tech-lead, etc.) are NOT valid Claude Code subagent_types.
@@ -143,3 +170,6 @@ Consensus: Incremental adoption. New endpoints in GraphQL, existing stay REST.
 - Each perspective must be independent — not "responding" to another agent
 - The synthesis is done by you (the skill), not by the agents
 - If all 3 agents agree, indicate consensus and suggest taking action
+- After the user decides, always offer to write the spec to `docs/specs/`
+- The spec document is the primary output of `/council` — it captures the debate, decision, and rationale
+- If the user declines the spec, log the decision to SESSION.md as before

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/templates/specs/SPEC_TEMPLATE.md

@@ -0,0 +1,46 @@
+# Spec: [Feature Name]
+
+spec-id: [kebab-case-identifier]
+status: draft
+date: [YYYY-MM-DD]
+council-type: [architecture | feature-scope | tech-debt]
+
+## Context
+
+[Why this spec exists. What problem or opportunity triggered it. Include relevant background, current state, and what happens if we do nothing.]
+
+## Decision
+
+[What we decided to do. The core design choice and key sub-decisions. Written in present tense: "Create X that does Y."]
+
+## Constraints
+
+[Hard boundaries: compatibility, performance, dependencies, timeline, and non-negotiable requirements.]
+
+## Acceptance Criteria
+
+[Checkboxes. Each criterion is independently verifiable. These are the contract between spec and implementation.]
+
+## Technical Approach
+
+[How to implement the decision. Files involved, patterns to follow, integration points. Enough detail for a developer to start working without ambiguity about direction.]
+
+## Trade-offs Considered
+
+[Options evaluated and rejected, with reasoning. Table format preferred: Option | Pros | Cons | Decision.]
+
+## Unresolved Questions
+
+[Open items that need answers before or during implementation. Include recommendations where possible.]
+
+## Test Strategy
+
+[How to verify the implementation meets acceptance criteria. Automated tests, manual checks, linting, integration tests.]
+
+## Council Perspectives
+
+[Summary of each agent's independent analysis. One subsection per agent with their key arguments and position.]
+
+## Points of Dissent
+
+[Where agents disagreed and how the disagreement was resolved. If consensus was unanimous, state that explicitly.]

package/src/utils/files.js

@@ -2,7 +2,7 @@
  * files.js — File system utilities for Guild v1
  */
 
-import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync } from 'fs';
+import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -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;
 }
 
 /**
@@ -44,6 +80,14 @@ export async function copyTemplates() {
     }
   }
 
+  // Create docs/specs/ directory with .gitkeep
+  const specsDir = join('docs', 'specs');
+  mkdirSync(specsDir, { recursive: true });
+  const gitkeep = join(specsDir, '.gitkeep');
+  if (!existsSync(gitkeep)) {
+    writeFileSync(gitkeep, '', 'utf8');
+  }
+
   // Copy skill directories with SKILL.md
   const skillsTemplate = join(TEMPLATES_DIR, 'skills');
   if (existsSync(skillsTemplate)) {
@@ -101,3 +145,17 @@ export function resolveProjectRoot(startDir = process.cwd()) {
     dir = parent;
   }
 }
+
+/**
+ * Resolves the Guild project root and changes the working directory to it.
+ * Throws if no Guild project is found.
+ * Returns the absolute path to the project root.
+ */
+export function ensureProjectRoot() {
+  const root = resolveProjectRoot();
+  if (!root) {
+    throw new Error('Guild project not found. Run `guild init` to initialize.');
+  }
+  process.chdir(root);
+  return root;
+}

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.
  */
@@ -46,14 +107,17 @@ ${data.stack}
 ## Project structure
 [PENDING: guild-specialize]
 
+docs/
+  specs/                              # Design documents (SDD specs)
+
 ## 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 +136,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
@@ -103,8 +168,9 @@ export async function generateSessionMd() {
 - CLAUDE.md has placeholders — run /guild-specialize to enrich.
 
 ## Next steps
-1. Open Claude Code and run /guild-specialize
-2. Define the first feature with /build-feature
+1. Run /guild-specialize to analyze your codebase
+2. Spec your first feature with /council
+3. Build it with /build-feature
 `;
 
   writeFileSync('SESSION.md', content, 'utf8');