lean-spec 0.2.5 → 0.2.6-dev.20251125010539

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { analyzeCommand, archiveCommand, backfillCommand, boardCommand, checkCommand, compactCommand, createCommand, depsCommand, filesCommand, ganttCommand, initCommand, linkCommand, listCommand, mcpCommand, migrateCommand, openCommand, searchCommand, splitCommand, statsCommand, templatesCommand, timelineCommand, tokensCommand, uiCommand, unlinkCommand, updateCommand, validateCommand, viewCommand } from './chunk-7WXYOHZU.js';
+import { analyzeCommand, archiveCommand, backfillCommand, boardCommand, checkCommand, compactCommand, createCommand, depsCommand, examplesCommand, filesCommand, ganttCommand, initCommand, linkCommand, listCommand, mcpCommand, migrateCommand, openCommand, searchCommand, splitCommand, statsCommand, templatesCommand, timelineCommand, tokensCommand, uiCommand, unlinkCommand, updateCommand, validateCommand, viewCommand } from './chunk-RTEGSMVL.js';
 import './chunk-LVD7ZAVZ.js';
 import { Command } from 'commander';
 import { readFileSync } from 'fs';
@@ -15,6 +15,7 @@ function registerCommands(program2) {
   program2.addCommand(compactCommand());
   program2.addCommand(createCommand());
   program2.addCommand(depsCommand());
+  program2.addCommand(examplesCommand());
   program2.addCommand(filesCommand());
   program2.addCommand(ganttCommand());
   program2.addCommand(initCommand());
@@ -51,6 +52,7 @@ Command Groups:
     archive <spec>                Move spec to archived/
     backfill [specs...]           Backfill timestamps from git history
     create <name>                 Create new spec
+    examples                      List example projects for tutorials
     init                          Initialize LeanSpec in current directory
     link <spec>                   Add relationships between specs
     migrate <input-path>          Migrate specs from other SDD tools
@@ -90,6 +92,10 @@ Command Groups:
 
 Examples:
   $ lean-spec init
+  $ lean-spec init -y
+  $ lean-spec init --example dark-theme
+  $ lean-spec init --example dashboard-widgets --name my-demo
+  $ lean-spec examples
   $ lean-spec create my-feature --priority high
   $ lean-spec list --status in-progress
   $ lean-spec view 042

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/commands/registry.ts","../src/cli.ts"],"names":["program"],"mappings":"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","file":"cli.js","sourcesContent":["import { Command } from 'commander';\nimport {\n  analyzeCommand,\n  archiveCommand,\n  backfillCommand,\n  boardCommand,\n  checkCommand,\n  compactCommand,\n  createCommand,\n  depsCommand,\n  filesCommand,\n  ganttCommand,\n  initCommand,\n  linkCommand,\n  listCommand,\n  mcpCommand,\n  migrateCommand,\n  openCommand,\n  searchCommand,\n  splitCommand,\n  statsCommand,\n  templatesCommand,\n  timelineCommand,\n  tokensCommand,\n  uiCommand,\n  unlinkCommand,\n  updateCommand,\n  validateCommand,\n  viewCommand,\n} from './index.js';\n\n/**\n * Register all commands in alphabetical order\n */\nexport function registerCommands(program: Command): void {\n  // Alphabetically sorted command registration\n  program.addCommand(analyzeCommand());\n  program.addCommand(archiveCommand());\n  program.addCommand(backfillCommand());\n  program.addCommand(boardCommand());\n  program.addCommand(checkCommand());\n  program.addCommand(compactCommand());\n  program.addCommand(createCommand());\n  program.addCommand(depsCommand());\n  program.addCommand(filesCommand());\n  program.addCommand(ganttCommand());\n  program.addCommand(initCommand());\n  program.addCommand(linkCommand());\n  program.addCommand(listCommand());\n  program.addCommand(mcpCommand());\n  program.addCommand(migrateCommand());\n  program.addCommand(openCommand());\n  program.addCommand(searchCommand());\n  program.addCommand(splitCommand());\n  program.addCommand(statsCommand());\n  program.addCommand(templatesCommand());\n  program.addCommand(timelineCommand());\n  program.addCommand(tokensCommand());\n  program.addCommand(uiCommand());\n  program.addCommand(unlinkCommand());\n  program.addCommand(updateCommand());\n  program.addCommand(validateCommand());\n  program.addCommand(viewCommand());\n}\n","import { Command } from 'commander';\nimport { readFileSync } from 'fs';\nimport { fileURLToPath } from 'url';\nimport { dirname, join } from 'path';\nimport { registerCommands } from './commands/registry.js';\n\n// Get version from package.json\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst packageJson = JSON.parse(\n  readFileSync(join(__dirname, '../package.json'), 'utf-8')\n);\n\nconst program = new Command();\n\nprogram\n  .name('lean-spec')\n  .description('Manage LeanSpec documents')\n  .version(packageJson.version);\n\n// Add custom help text with grouped commands\nprogram.addHelpText('after', `\nCommand Groups:\n\n  Core Workflow:\n    archive <spec>                Move spec to archived/\n    backfill [specs...]           Backfill timestamps from git history\n    create <name>                 Create new spec\n    init                          Initialize LeanSpec in current directory\n    link <spec>                   Add relationships between specs\n    migrate <input-path>          Migrate specs from other SDD tools\n    unlink <spec>                 Remove relationships between specs\n    update <spec>                 Update spec metadata\n    \n  Discovery & Search:\n    files <spec>                  List files in a spec\n    list                          List all specs\n    open <spec>                   Open spec in editor\n    search <query>                Full-text search with metadata filters\n    view <spec>                   View spec content\n    \n  Project Analytics:\n    board                         Show Kanban-style board view\n    deps <spec>                   Show dependency graph for a spec\n    gantt                         Show timeline with dependencies\n    stats                         Show aggregate statistics\n    timeline                      Show creation/completion over time\n    \n  Quality & Optimization:\n    analyze <spec>                Analyze spec complexity and structure\n    check                         Check for sequence conflicts\n    tokens [spec]                 Count tokens for LLM context management\n    validate [specs...]           Validate specs for quality issues\n    \n  Advanced Editing:\n    compact <spec>                Remove specified line ranges from spec\n    split <spec>                  Split spec into multiple files\n    \n  Configuration:\n    templates                     Manage spec templates\n    \n  Integration:\n    mcp                           Start MCP server for AI assistants\n    ui                            Start local web UI for spec management\n\nExamples:\n  $ lean-spec init\n  $ lean-spec create my-feature --priority high\n  $ lean-spec list --status in-progress\n  $ lean-spec view 042\n  $ lean-spec link 085 --depends-on 042,035\n  $ lean-spec link 085 --related 082\n  $ lean-spec unlink 085 --depends-on 042\n  $ lean-spec deps 085\n  $ lean-spec backfill --dry-run\n  $ lean-spec migrate ./docs/adr\n  $ lean-spec migrate ./docs/rfcs --with copilot\n  $ lean-spec board --tag backend\n  $ lean-spec search \"authentication\"\n  $ lean-spec validate\n  $ lean-spec tokens 059\n  $ lean-spec analyze 045 --json\n  $ lean-spec split 045 --output README.md:1-150 --output DESIGN.md:151-end\n  $ lean-spec ui\n  $ lean-spec ui --port 3001 --no-open\n  $ lean-spec ui --specs ./docs/specs --dry-run\n`);\n\n// Register all commands (alphabetically ordered)\nregisterCommands(program);\n\n// Parse and execute\nprogram.parse();\n"]}
+{"version":3,"sources":["../src/commands/registry.ts","../src/cli.ts"],"names":["program"],"mappings":"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","file":"cli.js","sourcesContent":["import { Command } from 'commander';\nimport {\n  analyzeCommand,\n  archiveCommand,\n  backfillCommand,\n  boardCommand,\n  checkCommand,\n  compactCommand,\n  createCommand,\n  depsCommand,\n  examplesCommand,\n  filesCommand,\n  ganttCommand,\n  initCommand,\n  linkCommand,\n  listCommand,\n  mcpCommand,\n  migrateCommand,\n  openCommand,\n  searchCommand,\n  splitCommand,\n  statsCommand,\n  templatesCommand,\n  timelineCommand,\n  tokensCommand,\n  uiCommand,\n  unlinkCommand,\n  updateCommand,\n  validateCommand,\n  viewCommand,\n} from './index.js';\n\n/**\n * Register all commands in alphabetical order\n */\nexport function registerCommands(program: Command): void {\n  // Alphabetically sorted command registration\n  program.addCommand(analyzeCommand());\n  program.addCommand(archiveCommand());\n  program.addCommand(backfillCommand());\n  program.addCommand(boardCommand());\n  program.addCommand(checkCommand());\n  program.addCommand(compactCommand());\n  program.addCommand(createCommand());\n  program.addCommand(depsCommand());\n  program.addCommand(examplesCommand());\n  program.addCommand(filesCommand());\n  program.addCommand(ganttCommand());\n  program.addCommand(initCommand());\n  program.addCommand(linkCommand());\n  program.addCommand(listCommand());\n  program.addCommand(mcpCommand());\n  program.addCommand(migrateCommand());\n  program.addCommand(openCommand());\n  program.addCommand(searchCommand());\n  program.addCommand(splitCommand());\n  program.addCommand(statsCommand());\n  program.addCommand(templatesCommand());\n  program.addCommand(timelineCommand());\n  program.addCommand(tokensCommand());\n  program.addCommand(uiCommand());\n  program.addCommand(unlinkCommand());\n  program.addCommand(updateCommand());\n  program.addCommand(validateCommand());\n  program.addCommand(viewCommand());\n}\n","import { Command } from 'commander';\nimport { readFileSync } from 'fs';\nimport { fileURLToPath } from 'url';\nimport { dirname, join } from 'path';\nimport { registerCommands } from './commands/registry.js';\n\n// Get version from package.json\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst packageJson = JSON.parse(\n  readFileSync(join(__dirname, '../package.json'), 'utf-8')\n);\n\nconst program = new Command();\n\nprogram\n  .name('lean-spec')\n  .description('Manage LeanSpec documents')\n  .version(packageJson.version);\n\n// Add custom help text with grouped commands\nprogram.addHelpText('after', `\nCommand Groups:\n\n  Core Workflow:\n    archive <spec>                Move spec to archived/\n    backfill [specs...]           Backfill timestamps from git history\n    create <name>                 Create new spec\n    examples                      List example projects for tutorials\n    init                          Initialize LeanSpec in current directory\n    link <spec>                   Add relationships between specs\n    migrate <input-path>          Migrate specs from other SDD tools\n    unlink <spec>                 Remove relationships between specs\n    update <spec>                 Update spec metadata\n    \n  Discovery & Search:\n    files <spec>                  List files in a spec\n    list                          List all specs\n    open <spec>                   Open spec in editor\n    search <query>                Full-text search with metadata filters\n    view <spec>                   View spec content\n    \n  Project Analytics:\n    board                         Show Kanban-style board view\n    deps <spec>                   Show dependency graph for a spec\n    gantt                         Show timeline with dependencies\n    stats                         Show aggregate statistics\n    timeline                      Show creation/completion over time\n    \n  Quality & Optimization:\n    analyze <spec>                Analyze spec complexity and structure\n    check                         Check for sequence conflicts\n    tokens [spec]                 Count tokens for LLM context management\n    validate [specs...]           Validate specs for quality issues\n    \n  Advanced Editing:\n    compact <spec>                Remove specified line ranges from spec\n    split <spec>                  Split spec into multiple files\n    \n  Configuration:\n    templates                     Manage spec templates\n    \n  Integration:\n    mcp                           Start MCP server for AI assistants\n    ui                            Start local web UI for spec management\n\nExamples:\n  $ lean-spec init\n  $ lean-spec init -y\n  $ lean-spec init --example dark-theme\n  $ lean-spec init --example dashboard-widgets --name my-demo\n  $ lean-spec examples\n  $ lean-spec create my-feature --priority high\n  $ lean-spec list --status in-progress\n  $ lean-spec view 042\n  $ lean-spec link 085 --depends-on 042,035\n  $ lean-spec link 085 --related 082\n  $ lean-spec unlink 085 --depends-on 042\n  $ lean-spec deps 085\n  $ lean-spec backfill --dry-run\n  $ lean-spec migrate ./docs/adr\n  $ lean-spec migrate ./docs/rfcs --with copilot\n  $ lean-spec board --tag backend\n  $ lean-spec search \"authentication\"\n  $ lean-spec validate\n  $ lean-spec tokens 059\n  $ lean-spec analyze 045 --json\n  $ lean-spec split 045 --output README.md:1-150 --output DESIGN.md:151-end\n  $ lean-spec ui\n  $ lean-spec ui --port 3001 --no-open\n  $ lean-spec ui --specs ./docs/specs --dry-run\n`);\n\n// Register all commands (alphabetically ordered)\nregisterCommands(program);\n\n// Parse and execute\nprogram.parse();\n"]}

package/dist/mcp-server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export { createMcpServer } from './chunk-7WXYOHZU.js';
+export { createMcpServer } from './chunk-RTEGSMVL.js';
 import './chunk-LVD7ZAVZ.js';
 //# sourceMappingURL=mcp-server.js.map
 //# sourceMappingURL=mcp-server.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lean-spec",
-  "version": "0.2.5",
+  "version": "0.2.6-dev.20251125010539",
   "description": "Specification-driven development made simple",
   "type": "module",
   "bin": {
@@ -48,7 +48,6 @@
     "commander": "^14.0.2",
     "dayjs": "^1.11.19",
     "gray-matter": "^4.0.3",
-    "handlebars": "^4.7.8",
     "ink": "^6.4.0",
     "ink-gradient": "^3.0.0",
     "ink-progress-bar": "^3.0.0",
@@ -68,7 +67,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@leanspec/core": "^0.2.5",
+    "@leanspec/core": "workspace:*",
     "@types/js-yaml": "^4.0.9",
     "@types/marked-terminal": "^6.1.1",
     "@types/node": "^20.10.0",

package/templates/detailed/AGENTS.md

@@ -0,0 +1,113 @@
+# AI Agent Instructions
+
+## Project: {project_name}
+
+Lightweight spec methodology for AI-powered development.
+
+## Core Rules
+
+1. **Read README.md first** - Understand project context
+2. **Check specs/** - Review existing specs before starting
+3. **Use `lean-spec --help`** - When unsure about commands, check the built-in help
+4. **Follow LeanSpec principles** - Clarity over documentation
+5. **Keep it minimal** - If it doesn't add clarity, cut it
+6. **NEVER manually edit system-managed frontmatter** - Fields like `status`, `priority`, `tags`, `assignee`, `transitions`, `created_at`, `updated_at`, `completed_at`, `depends_on`, `related` are system-managed. Always use `lean-spec update`, `lean-spec link`, `lean-spec unlink`, or `lean-spec create` commands. Manual edits will cause metadata corruption and tracking issues.
+7. **Never use nested code blocks** - Markdown doesn't support code blocks within code blocks. If you need to show code examples in documentation, use indentation or describe the structure instead of nesting backticks.
+
+## When to Use Specs
+
+Write a spec for:
+- Features affecting multiple parts of the system
+- Breaking changes or significant refactors
+- Design decisions needing team alignment
+
+Skip specs for:
+- Bug fixes
+- Trivial changes
+- Self-explanatory refactors
+
+## Essential Commands
+
+**Quick Reference** (for full details, see `lean-spec --help`):
+
+**Discovery:**
+- `lean-spec list` - See all specs
+- `lean-spec search "<query>"` - Find relevant specs
+
+**Working with specs:**
+- `lean-spec create <name>` - Create new spec
+- `lean-spec update <spec> --status <status>` - Update status (REQUIRED - never edit frontmatter manually)
+- `lean-spec update <spec> --priority <priority>` - Update priority
+- `lean-spec deps <spec>` - Show dependency graph
+- `lean-spec tokens <spec>` - Count tokens for context management
+
+**Project overview:**
+- `lean-spec board` - Kanban view with project health
+- `lean-spec stats` - Quick project metrics
+
+**When in doubt:** Run `lean-spec --help` or `lean-spec <command> --help` to discover commands.
+
+## Spec Relationships
+
+LeanSpec has two types of relationships:
+
+### `related` - Bidirectional Soft Reference
+Informational relationship between specs. Automatically shown from both sides.
+
+**Use when:** Specs cover related topics, work is coordinated but not blocking.
+
+### `depends_on` - Directional Blocking Dependency
+Hard dependency - spec cannot start until dependencies complete.
+
+**Use when:** Spec truly cannot start until another completes, work order matters.
+
+**Best Practice:** Use `related` by default. Reserve `depends_on` for true blocking dependencies.
+
+## SDD Workflow
+
+1. **Discover** - Check existing specs with `lean-spec list`
+2. **Plan** - Create spec with `lean-spec create <name>` (status: `planned`)
+3. **Start Work** - Run `lean-spec update <spec> --status in-progress` before implementing
+4. **Implement** - Write code/docs, keep spec in sync as you learn
+5. **Complete** - Run `lean-spec update <spec> --status complete` after implementation done
+6. **Document** - Report progress and document changes into the spec
+
+**CRITICAL - What "Work" Means:**
+- ❌ **NOT**: Creating/writing the spec document itself
+- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+
+**Frontmatter Editing Rules:**
+- **NEVER manually edit**: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on`, `related`
+- **Use CLI commands**: `lean-spec update`, `lean-spec link`, `lean-spec unlink`
+
+**Note on Archiving**: Archive specs when they're no longer actively referenced (weeks/months after completion), not immediately. Use `lean-spec archive <spec>` to move old/stale specs to `archived/` directory.
+
+## Quality Standards
+
+- Code is clear and maintainable
+- Tests cover critical paths
+- Specs stay in sync with implementation
+- **Status tracking is mandatory:**
+  - Specs start as `planned` after creation
+  - Mark `in-progress` BEFORE starting implementation work
+  - Mark `complete` AFTER implementation is finished
+  - **Remember**: Status tracks implementation, not spec document completion
+  - Never leave specs with stale status
+
+## Spec Complexity Guidelines
+
+**Token Thresholds:**
+- **<2,000 tokens**: ✅ Optimal
+- **2,000-3,500 tokens**: ✅ Good
+- **3,500-5,000 tokens**: ⚠️ Warning - Consider splitting
+- **>5,000 tokens**: 🔴 Should split
+
+**Check with:** `lean-spec tokens <spec>`
+
+**When to split:** >3,500 tokens, multiple concerns, takes >10 min to read
+
+**How to split:** Use sub-specs or split into related specs with `lean-spec link --related`
+
+---
+
+**Remember**: LeanSpec is a mindset, not a rulebook. When in doubt, keep it simple and use `lean-spec --help` to discover features as needed.

package/templates/detailed/README.md

@@ -0,0 +1,28 @@
+# Detailed Template
+
+For complex specs that benefit from structured sub-specs. Demonstrates how to manage token limits.
+
+## What's Included
+
+- **AGENTS.md** - Same AI agent instructions as standard template
+- **Sub-spec structure** - README.md + DESIGN.md + PLAN.md + TEST.md
+- Demonstrates splitting specs to stay under token limits
+- Example of real-world sub-spec organization
+
+## When to Use
+
+- Complex features with lots of detail
+- Specs approaching 3,500+ tokens
+- Need clear separation of concerns (design, plan, test)
+- Large teams with multiple reviewers
+
+## Philosophy
+
+Keep it lean, but organized. Use sub-specs to manage complexity without overwhelming context. Each file stays focused and under token limits.
+
+## Next Steps
+
+1. Customize AGENTS.md for your project
+2. Create your first spec: `lean-spec create my-feature`
+3. When a spec grows large, split sections into sub-spec files
+

package/templates/detailed/files/DESIGN.md

@@ -0,0 +1,43 @@
+# Design: {name}
+
+> Part of [{name}](README.md)
+
+## Architecture
+
+<!-- High-level system design, components, interactions -->
+
+## Technical Approach
+
+<!-- Specific technologies, patterns, frameworks -->
+
+## Design Decisions
+
+<!-- Key decisions and rationale -->
+
+### Decision 1
+
+**Context**: <!-- What problem does this solve? -->
+
+**Decision**: <!-- What did we choose? -->
+
+**Rationale**: <!-- Why this approach? -->
+
+**Trade-offs**: <!-- What are we giving up? -->
+
+## Dependencies
+
+<!-- What does this depend on? What depends on this? -->
+
+### System Dependencies
+- 
+
+### Team Dependencies
+- 
+
+## Security & Compliance
+
+<!-- Security implications, compliance requirements -->
+
+- [ ] Handles sensitive data (PII, credentials, etc.)
+- [ ] Security review completed
+- [ ] Compliance requirements addressed

package/templates/detailed/files/PLAN.md

@@ -0,0 +1,59 @@
+# Plan: {name}
+
+> Part of [{name}](README.md)
+
+## Implementation Phases
+
+### Phase 1: [Name]
+
+**Goal**: <!-- What does this phase achieve? -->
+
+**Tasks**:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+**Dependencies**: <!-- What must be done before this? -->
+
+**Success criteria**: <!-- How do we know this is done? -->
+
+### Phase 2: [Name]
+
+**Goal**: <!-- What does this phase achieve? -->
+
+**Tasks**:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+**Dependencies**: <!-- What must be done before this? -->
+
+**Success criteria**: <!-- How do we know this is done? -->
+
+## Rollout Strategy
+
+<!-- How will this be deployed to production? -->
+
+**Staging**:
+- 
+
+**Production**:
+- 
+
+**Monitoring**:
+- 
+
+**Rollback plan**:
+- 
+
+## Timeline
+
+| Phase | Duration | Dependencies |
+|-------|----------|--------------|
+|       |          |              |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+|      |        |            |

package/templates/detailed/files/README.md

@@ -0,0 +1,30 @@
+---
+status: planned
+created: '{date}'
+tags: []
+priority: medium
+---
+
+# {name}
+
+> **Status**: {status} · **Priority**: {priority} · **Created**: {date}
+
+## Overview
+
+<!-- What are we solving? Why now? Expected impact? -->
+
+## Sub-Specs
+
+For detailed information, see:
+
+- **[DESIGN.md](DESIGN.md)** - Technical architecture and design decisions
+- **[PLAN.md](PLAN.md)** - Implementation plan and phases
+- **[TEST.md](TEST.md)** - Testing strategy and verification
+
+## Quick Summary
+
+<!-- Brief summary of the spec (2-3 paragraphs max) -->
+
+## Notes
+
+<!-- Key decisions, constraints, open questions -->

package/templates/detailed/files/TEST.md

@@ -0,0 +1,71 @@
+# Test: {name}
+
+> Part of [{name}](README.md)
+
+## Testing Strategy
+
+<!-- Overall approach to verifying this works -->
+
+## Unit Tests
+
+<!-- Component-level testing -->
+
+**Scope**:
+- 
+
+**Key test cases**:
+- [ ] Test case 1
+- [ ] Test case 2
+- [ ] Test case 3
+
+## Integration Tests
+
+<!-- System interaction testing -->
+
+**Scope**:
+- 
+
+**Key test cases**:
+- [ ] Test case 1
+- [ ] Test case 2
+- [ ] Test case 3
+
+## Performance Tests
+
+<!-- Load, stress, and performance testing -->
+
+**Requirements**:
+- 
+
+**Test scenarios**:
+- [ ] Scenario 1
+- [ ] Scenario 2
+
+## Security Tests
+
+<!-- Security validation -->
+
+**Security checks**:
+- [ ] Authentication/authorization
+- [ ] Input validation
+- [ ] Data encryption
+- [ ] Audit logging
+
+## Acceptance Criteria
+
+<!-- What must be true for this to be considered complete? -->
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Test Data
+
+<!-- What test data is needed? -->
+
+## Manual Testing
+
+<!-- What requires human verification? -->
+
+- [ ] Manual test 1
+- [ ] Manual test 2

package/templates/examples/api-refactor/README.md

@@ -0,0 +1,81 @@
+# API Refactor Demo
+
+> **Tutorial**: [Refactoring with Specs](https://leanspec.dev/docs/tutorials/refactoring-specs)
+
+## Scenario
+
+You're maintaining a Node.js application that started simple but has grown messy. The app integrates with multiple external services (weather API, currency converter, timezone lookup), but all the HTTP logic is tangled together in the main application code.
+
+You want to extract a reusable API client module that:
+- Centralizes HTTP request handling
+- Provides a clean interface for service calls
+- Handles errors consistently
+- Makes the code easier to test and maintain
+
+## What's Here
+
+A monolithic Node.js app with:
+- Weather lookup feature (calls external API)
+- Currency conversion (calls external API)
+- Timezone lookup (calls external API)
+- All HTTP logic mixed into business logic (tight coupling)
+- No error handling abstraction
+- Hard to test individual parts
+
+**Files:**
+- `src/app.js` - Main application with all features
+- `src/services/weatherService.js` - Weather API calls (tightly coupled)
+- `src/services/currencyService.js` - Currency API calls (tightly coupled)
+- `src/services/timezoneService.js` - Timezone API calls (tightly coupled)
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Run the app
+npm start
+
+# Try the features:
+# - Weather: Get weather for a city
+# - Currency: Convert between currencies
+# - Timezone: Look up timezone info
+```
+
+## Your Mission
+
+Refactor the HTTP logic into a clean, reusable API client. Follow the tutorial and ask your AI assistant:
+
+> "Help me refactor this app using LeanSpec. I want to extract a reusable API client module that centralizes all the HTTP logic."
+
+The AI will guide you through:
+1. Creating a refactoring spec
+2. Designing the API client interface
+3. Extracting the HTTP logic step by step
+4. Updating services to use the new client
+5. Verifying everything still works
+
+## Current Problems
+
+- **Duplicated code**: Each service reimplements HTTP requests
+- **No error handling**: Errors handled inconsistently
+- **Hard to test**: Can't mock HTTP calls easily
+- **Tight coupling**: Business logic mixed with HTTP details
+- **No retry logic**: Network failures aren't handled
+
+These are perfect opportunities to practice refactoring with specs!
+
+## Expected Result
+
+After refactoring, you should have:
+```
+src/
+  app.js (unchanged interface)
+  client/
+    apiClient.js (new - centralized HTTP logic)
+  services/
+    weatherService.js (simplified - uses apiClient)
+    currencyService.js (simplified - uses apiClient)
+    timezoneService.js (simplified - uses apiClient)
+```

package/templates/examples/api-refactor/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "api-refactor-demo",
+  "version": "1.0.0",
+  "description": "Monolithic Node.js app for LeanSpec Tutorial 3",
+  "type": "module",
+  "scripts": {
+    "start": "node src/app.js",
+    "dev": "node --watch src/app.js"
+  },
+  "keywords": ["leanspec", "tutorial", "demo"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  }
+}

package/templates/examples/api-refactor/src/app.js

@@ -0,0 +1,40 @@
+import { getWeather } from './services/weatherService.js';
+import { convertCurrency } from './services/currencyService.js';
+import { getTimezone } from './services/timezoneService.js';
+
+console.log('=== Multi-Service App Demo ===\n');
+
+// Demo 1: Weather lookup
+console.log('1. Weather Lookup:');
+try {
+  const weather = await getWeather('London');
+  console.log(`   ${weather.city}: ${weather.temp}°C, ${weather.condition}`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+
+// Demo 2: Currency conversion
+console.log('2. Currency Conversion:');
+try {
+  const result = await convertCurrency(100, 'USD', 'EUR');
+  console.log(`   ${result.amount} ${result.from} = ${result.converted} ${result.to}`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+
+// Demo 3: Timezone lookup
+console.log('3. Timezone Lookup:');
+try {
+  const timezone = await getTimezone('America/New_York');
+  console.log(`   ${timezone.name}: ${timezone.offset} (${timezone.abbreviation})`);
+} catch (error) {
+  console.log(`   Error: ${error.message}`);
+}
+
+console.log('');
+console.log('Notice: All services work, but they all duplicate HTTP logic!');
+console.log('Your task: Extract a reusable API client module.');

package/templates/examples/api-refactor/src/services/currencyService.js

@@ -0,0 +1,43 @@
+import fetch from 'node-fetch';
+
+/**
+ * Convert currency
+ * 
+ * PROBLEM: Duplicates HTTP logic from weatherService
+ * - Same fetch boilerplate
+ * - Same error handling pattern
+ * - Same JSON parsing
+ * - Should be using a shared HTTP client!
+ */
+export async function convertCurrency(amount, from, to) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `https://api.exchangerate.host/convert?from=${from}&to=${to}&amount=${amount}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Currency API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      amount,
+      from,
+      to,
+      converted: data.result || (amount * 0.85).toFixed(2),
+      rate: data.info?.rate || 0.85,
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      amount,
+      from,
+      to,
+      converted: (amount * 0.85).toFixed(2),
+      rate: 0.85,
+    };
+  }
+}

package/templates/examples/api-refactor/src/services/timezoneService.js

@@ -0,0 +1,41 @@
+import fetch from 'node-fetch';
+
+/**
+ * Get timezone information
+ * 
+ * PROBLEM: Yet another copy of the same HTTP logic!
+ * - Third time we're writing fetch + error handling + JSON parsing
+ * - Violates DRY principle
+ * - Makes testing hard (need to mock fetch in 3 places)
+ * - Changes to HTTP logic need updates in 3 files
+ */
+export async function getTimezone(zone) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `http://worldtimeapi.org/api/timezone/${zone}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Timezone API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      name: data.timezone || zone,
+      offset: data.utc_offset || '-05:00',
+      abbreviation: data.abbreviation || 'EST',
+      datetime: data.datetime || new Date().toISOString(),
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      name: zone,
+      offset: '-05:00',
+      abbreviation: 'EST',
+      datetime: new Date().toISOString(),
+    };
+  }
+}