guild-agents 0.3.0 → 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.3.0",
-  "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"
@@ -52,7 +53,8 @@
   "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

@@ -127,19 +127,19 @@ export async function runInit() {
   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'];
+    ? ['/guild-specialize', '/council', '/build-feature']
+    : ['/council', '/build-feature', '/new-feature'];
   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' +
+    ? '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 v1 ready.'));
+  p.outro(chalk.bold.cyan('Guild ready — spec before you build.'));
 }

package/src/commands/list.js

@@ -6,9 +6,11 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { parseFrontmatter } from '../utils/files.js';
+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

@@ -69,6 +69,7 @@ This indicator MUST be displayed before spawning the agent for that phase.
 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)
@@ -83,6 +84,7 @@ This indicator MUST be displayed before spawning the agent for that phase.
 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)
 
@@ -96,6 +98,7 @@ This indicator MUST be displayed before spawning the agent for that phase.
 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)
 
@@ -110,6 +113,7 @@ This indicator MUST be displayed before spawning the agent for that phase.
 4. Verifies that tests pass
 
 **Output:** Implemented code + tests + commits made
+**Trace data:** Files created/modified, tests added, commits made
 
 ### Pre-Review Gate (mandatory)
 
@@ -121,6 +125,8 @@ 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...`
@@ -132,6 +138,7 @@ 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)
@@ -145,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
@@ -161,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`
 
@@ -171,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:
@@ -181,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"`
 

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/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';
 
@@ -80,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)) {
@@ -137,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

@@ -107,6 +107,9 @@ ${data.stack}
 ## Project structure
 [PENDING: guild-specialize]
 
+docs/
+  specs/                              # Design documents (SDD specs)
+
 ## Code conventions
 ${inferCodeConventions(data.type, data.stack)}
 
@@ -165,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');