lean-spec 0.2.5-dev.20251124070920 → 0.2.5-dev.20251125010225

package/dist/cli.js

@@ -1,4 +1,4 @@
-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-LV7XEQ4D.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';

package/dist/mcp-server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export { createMcpServer } from './chunk-LV7XEQ4D.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-dev.20251124070920",
+  "version": "0.2.5-dev.20251125010225",
   "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",

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/standard/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/standard/README.md

@@ -1,16 +1,17 @@
 # Standard Template
 
-Recommended for most projects. Includes AI agent instructions and sensible defaults.
+Recommended for most projects. Single-file specs with AI agent instructions.
 
 ## What's Included
 
 - **AGENTS.md** - Instructions for AI coding assistants
-- Spec folder structure
+- **Single-file spec template** - All sections in one README.md
 - Opinionated defaults for fast iteration
 
 ## When to Use
 
 - Solo developers or small teams
+- Simple to moderate complexity specs
 - Want AI agent integration
 - Need clear but not heavy-weight process
 
@@ -22,3 +23,4 @@ Keep it lean. Write specs for features that need clarity. Skip them for obvious
 
 1. Customize AGENTS.md for your project
 2. Create your first spec: `lean-spec create my-feature`
+