lean-spec 0.2.6-dev.20251126022840 → 0.2.6-dev.20251126030344

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/dist/{chunk-RTEGSMVL.js → chunk-IXCZPYB7.js} +483 -14
  2. package/dist/chunk-IXCZPYB7.js.map +1 -0
  3. package/dist/cli.js +1 -1
  4. package/dist/mcp-server.js +1 -1
  5. package/package.json +1 -1
  6. package/templates/detailed/AGENTS.md +100 -72
  7. package/templates/standard/AGENTS.md +100 -72
  8. package/dist/chunk-RTEGSMVL.js.map +0 -1
package/dist/cli.js CHANGED
@@ -1,4 +1,4 @@
1
- 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';
1
+ 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-IXCZPYB7.js';
2
2
  import './chunk-LVD7ZAVZ.js';
3
3
  import { Command } from 'commander';
4
4
  import { readFileSync } from 'fs';
package/dist/mcp-server.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- export { createMcpServer } from './chunk-RTEGSMVL.js';
2
+ export { createMcpServer } from './chunk-IXCZPYB7.js';
3
3
  import './chunk-LVD7ZAVZ.js';
4
4
  //# sourceMappingURL=mcp-server.js.map
5
5
  //# sourceMappingURL=mcp-server.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lean-spec",
3
- "version": "0.2.6-dev.20251126022840",
3
+ "version": "0.2.6-dev.20251126030344",
4
4
  "description": "Specification-driven development made simple",
5
5
  "type": "module",
6
6
  "bin": {
package/templates/detailed/AGENTS.md CHANGED
@@ -4,110 +4,138 @@
4
4
 
5
5
  Lightweight spec methodology for AI-powered development.
6
6
 
7
+ ## 🚨 CRITICAL: Before ANY Task
8
+
9
+ **STOP and check these first:**
10
+
11
+ 1. **Discover context** → Use `board` tool to see project state
12
+ 2. **Search for related work** → Use `search` tool before creating new specs
13
+ 3. **Never create files manually** → Always use `create` tool for new specs
14
+
15
+ > **Why?** Skipping discovery creates duplicate work. Manual file creation breaks LeanSpec tooling.
16
+
17
+ ## 🔧 How to Manage Specs
18
+
19
+ ### Primary Method: MCP Tools (Recommended)
20
+
21
+ If you have LeanSpec MCP tools available, **ALWAYS use them**:
22
+
23
+ | Action | MCP Tool | Description |
24
+ |--------|----------|-------------|
25
+ | See project status | `board` | Kanban view + project health metrics |
26
+ | List all specs | `list` | Filterable list with metadata |
27
+ | Search specs | `search` | Semantic search across all content |
28
+ | View a spec | `view` | Full content with formatting |
29
+ | Create new spec | `create` | Auto-sequences, proper structure |
30
+ | Update spec | `update` | Validates transitions, timestamps |
31
+ | Check dependencies | `deps` | Visual dependency graph |
32
+
33
+ **Why MCP over CLI?**
34
+ - ✅ Direct tool integration (no shell execution needed)
35
+ - ✅ Structured responses (better for AI reasoning)
36
+ - ✅ Real-time validation (immediate feedback)
37
+ - ✅ Context-aware (understands project state)
38
+
39
+ ### Fallback: CLI Commands
40
+
41
+ If MCP tools are not available, use CLI commands:
42
+
43
+ ```bash
44
+ lean-spec board # Project overview
45
+ lean-spec list # See all specs
46
+ lean-spec search "query" # Find relevant specs
47
+ lean-spec create <name> # Create new spec
48
+ lean-spec update <spec> --status <status> # Update status
49
+ lean-spec deps <spec> # Show dependencies
50
+ ```
51
+
52
+ **Tip:** Check if you have LeanSpec MCP tools available before using CLI.
53
+
54
+ ## ⚠️ SDD Workflow Checkpoints
55
+
56
+ ### Before Starting ANY Task
57
+
58
+ 1. 📋 **Run `board`** - What's the current project state?
59
+ 2. 🔍 **Run `search`** - Are there related specs already?
60
+ 3. 📝 **Check existing specs** - Is there one for this work?
61
+
62
+ ### During Implementation
63
+
64
+ 4. 📊 **Update status to `in-progress`** BEFORE coding
65
+ 5. 📝 **Document decisions** in the spec as you work
66
+ 6. 🔗 **Link related specs** if you discover connections
67
+
68
+ ### After Completing Work
69
+
70
+ 7. ✅ **Update status to `complete`** when done
71
+ 8. 📄 **Document what you learned** in the spec
72
+ 9. 🤔 **Create follow-up specs** if needed
73
+
74
+ ### 🚫 Common Mistakes to Avoid
75
+
76
+ | ❌ Don't | ✅ Do Instead |
77
+ |----------|---------------|
78
+ | Create spec files manually | Use `create` tool |
79
+ | Skip discovery before new work | Run `board` and `search` first |
80
+ | Leave status as "planned" after starting | Update to `in-progress` immediately |
81
+ | Finish work without updating spec | Document decisions, update status |
82
+ | Edit frontmatter manually | Use `update` tool |
83
+ | Forget about specs mid-conversation | Check spec status periodically |
84
+
7
85
  ## Core Rules
8
86
 
9
87
  1. **Read README.md first** - Understand project context
10
88
  2. **Check specs/** - Review existing specs before starting
11
- 3. **Use `lean-spec --help`** - When unsure about commands, check the built-in help
89
+ 3. **Use MCP tools** - Prefer MCP over CLI when available
12
90
  4. **Follow LeanSpec principles** - Clarity over documentation
13
91
  5. **Keep it minimal** - If it doesn't add clarity, cut it
14
- 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.
15
- 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.
92
+ 6. **NEVER manually edit frontmatter** - Use `update`, `link`, `unlink` tools
93
+ 7. **Track progress in specs** - Update status and document decisions
16
94
 
17
95
  ## When to Use Specs
18
96
 
19
- Write a spec for:
97
+ **Write a spec for:**
20
98
  - Features affecting multiple parts of the system
21
99
  - Breaking changes or significant refactors
22
100
  - Design decisions needing team alignment
23
101
 
24
- Skip specs for:
102
+ **Skip specs for:**
25
103
  - Bug fixes
26
104
  - Trivial changes
27
105
  - Self-explanatory refactors
28
106
 
29
- ## Essential Commands
30
-
31
- **Quick Reference** (for full details, see `lean-spec --help`):
32
-
33
- **Discovery:**
34
- - `lean-spec list` - See all specs
35
- - `lean-spec search "<query>"` - Find relevant specs
36
-
37
- **Working with specs:**
38
- - `lean-spec create <name>` - Create new spec
39
- - `lean-spec update <spec> --status <status>` - Update status (REQUIRED - never edit frontmatter manually)
40
- - `lean-spec update <spec> --priority <priority>` - Update priority
41
- - `lean-spec deps <spec>` - Show dependency graph
42
- - `lean-spec tokens <spec>` - Count tokens for context management
43
-
44
- **Project overview:**
45
- - `lean-spec board` - Kanban view with project health
46
- - `lean-spec stats` - Quick project metrics
47
-
48
- **When in doubt:** Run `lean-spec --help` or `lean-spec <command> --help` to discover commands.
49
-
50
107
  ## Spec Relationships
51
108
 
52
- LeanSpec has two types of relationships:
53
-
54
109
  ### `related` - Bidirectional Soft Reference
55
- Informational relationship between specs. Automatically shown from both sides.
56
-
57
- **Use when:** Specs cover related topics, work is coordinated but not blocking.
110
+ Informational relationship between specs. Shown from both sides.
111
+ **Use when:** Related topics, coordinated but not blocking work.
58
112
 
59
113
  ### `depends_on` - Directional Blocking Dependency
60
114
  Hard dependency - spec cannot start until dependencies complete.
115
+ **Use when:** True blocking dependency, work order matters.
61
116
 
62
- **Use when:** Spec truly cannot start until another completes, work order matters.
63
-
64
- **Best Practice:** Use `related` by default. Reserve `depends_on` for true blocking dependencies.
65
-
66
- ## SDD Workflow
67
-
68
- 1. **Discover** - Check existing specs with `lean-spec list`
69
- 2. **Plan** - Create spec with `lean-spec create <name>` (status: `planned`)
70
- 3. **Start Work** - Run `lean-spec update <spec> --status in-progress` before implementing
71
- 4. **Implement** - Write code/docs, keep spec in sync as you learn
72
- 5. **Complete** - Run `lean-spec update <spec> --status complete` after implementation done
73
- 6. **Document** - Report progress and document changes into the spec
74
-
75
- **CRITICAL - What "Work" Means:**
76
- - ❌ **NOT**: Creating/writing the spec document itself
77
- - ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
78
-
79
- **Frontmatter Editing Rules:**
80
- - **NEVER manually edit**: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on`, `related`
81
- - **Use CLI commands**: `lean-spec update`, `lean-spec link`, `lean-spec unlink`
82
-
83
- **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.
117
+ **Default:** Use `related`. Reserve `depends_on` for true blockers.
84
118
 
85
119
  ## Quality Standards
86
120
 
87
- - Code is clear and maintainable
88
- - Tests cover critical paths
89
- - Specs stay in sync with implementation
90
121
  - **Status tracking is mandatory:**
91
- - Specs start as `planned` after creation
92
- - Mark `in-progress` BEFORE starting implementation work
93
- - Mark `complete` AFTER implementation is finished
94
- - **Remember**: Status tracks implementation, not spec document completion
95
- - Never leave specs with stale status
122
+ - `planned` → after creation
123
+ - `in-progress` → BEFORE starting implementation
124
+ - `complete` → AFTER finishing implementation
125
+ - Specs stay in sync with implementation
126
+ - Never leave specs with stale status
96
127
 
97
128
  ## Spec Complexity Guidelines
98
129
 
99
- **Token Thresholds:**
100
- - **<2,000 tokens**: ✅ Optimal
101
- - **2,000-3,500 tokens**: ✅ Good
102
- - **3,500-5,000 tokens**: ⚠️ Warning - Consider splitting
103
- - **>5,000 tokens**: 🔴 Should split
104
-
105
- **Check with:** `lean-spec tokens <spec>`
106
-
107
- **When to split:** >3,500 tokens, multiple concerns, takes >10 min to read
130
+ | Tokens | Status |
131
+ |--------|--------|
132
+ | <2,000 | ✅ Optimal |
133
+ | 2,000-3,500 | ✅ Good |
134
+ | 3,500-5,000 | ⚠️ Consider splitting |
135
+ | >5,000 | 🔴 Should split |
108
136
 
109
- **How to split:** Use sub-specs or split into related specs with `lean-spec link --related`
137
+ Use `tokens` tool to check spec size.
110
138
 
111
139
  ---
112
140
 
113
- **Remember**: LeanSpec is a mindset, not a rulebook. When in doubt, keep it simple and use `lean-spec --help` to discover features as needed.
141
+ **Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!
package/templates/standard/AGENTS.md CHANGED
@@ -4,110 +4,138 @@
4
4
 
5
5
  Lightweight spec methodology for AI-powered development.
6
6
 
7
+ ## 🚨 CRITICAL: Before ANY Task
8
+
9
+ **STOP and check these first:**
10
+
11
+ 1. **Discover context** → Use `board` tool to see project state
12
+ 2. **Search for related work** → Use `search` tool before creating new specs
13
+ 3. **Never create files manually** → Always use `create` tool for new specs
14
+
15
+ > **Why?** Skipping discovery creates duplicate work. Manual file creation breaks LeanSpec tooling.
16
+
17
+ ## 🔧 How to Manage Specs
18
+
19
+ ### Primary Method: MCP Tools (Recommended)
20
+
21
+ If you have LeanSpec MCP tools available, **ALWAYS use them**:
22
+
23
+ | Action | MCP Tool | Description |
24
+ |--------|----------|-------------|
25
+ | See project status | `board` | Kanban view + project health metrics |
26
+ | List all specs | `list` | Filterable list with metadata |
27
+ | Search specs | `search` | Semantic search across all content |
28
+ | View a spec | `view` | Full content with formatting |
29
+ | Create new spec | `create` | Auto-sequences, proper structure |
30
+ | Update spec | `update` | Validates transitions, timestamps |
31
+ | Check dependencies | `deps` | Visual dependency graph |
32
+
33
+ **Why MCP over CLI?**
34
+ - ✅ Direct tool integration (no shell execution needed)
35
+ - ✅ Structured responses (better for AI reasoning)
36
+ - ✅ Real-time validation (immediate feedback)
37
+ - ✅ Context-aware (understands project state)
38
+
39
+ ### Fallback: CLI Commands
40
+
41
+ If MCP tools are not available, use CLI commands:
42
+
43
+ ```bash
44
+ lean-spec board # Project overview
45
+ lean-spec list # See all specs
46
+ lean-spec search "query" # Find relevant specs
47
+ lean-spec create <name> # Create new spec
48
+ lean-spec update <spec> --status <status> # Update status
49
+ lean-spec deps <spec> # Show dependencies
50
+ ```
51
+
52
+ **Tip:** Check if you have LeanSpec MCP tools available before using CLI.
53
+
54
+ ## ⚠️ SDD Workflow Checkpoints
55
+
56
+ ### Before Starting ANY Task
57
+
58
+ 1. 📋 **Run `board`** - What's the current project state?
59
+ 2. 🔍 **Run `search`** - Are there related specs already?
60
+ 3. 📝 **Check existing specs** - Is there one for this work?
61
+
62
+ ### During Implementation
63
+
64
+ 4. 📊 **Update status to `in-progress`** BEFORE coding
65
+ 5. 📝 **Document decisions** in the spec as you work
66
+ 6. 🔗 **Link related specs** if you discover connections
67
+
68
+ ### After Completing Work
69
+
70
+ 7. ✅ **Update status to `complete`** when done
71
+ 8. 📄 **Document what you learned** in the spec
72
+ 9. 🤔 **Create follow-up specs** if needed
73
+
74
+ ### 🚫 Common Mistakes to Avoid
75
+
76
+ | ❌ Don't | ✅ Do Instead |
77
+ |----------|---------------|
78
+ | Create spec files manually | Use `create` tool |
79
+ | Skip discovery before new work | Run `board` and `search` first |
80
+ | Leave status as "planned" after starting | Update to `in-progress` immediately |
81
+ | Finish work without updating spec | Document decisions, update status |
82
+ | Edit frontmatter manually | Use `update` tool |
83
+ | Forget about specs mid-conversation | Check spec status periodically |
84
+
7
85
  ## Core Rules
8
86
 
9
87
  1. **Read README.md first** - Understand project context
10
88
  2. **Check specs/** - Review existing specs before starting
11
- 3. **Use `lean-spec --help`** - When unsure about commands, check the built-in help
89
+ 3. **Use MCP tools** - Prefer MCP over CLI when available
12
90
  4. **Follow LeanSpec principles** - Clarity over documentation
13
91
  5. **Keep it minimal** - If it doesn't add clarity, cut it
14
- 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.
15
- 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.
92
+ 6. **NEVER manually edit frontmatter** - Use `update`, `link`, `unlink` tools
93
+ 7. **Track progress in specs** - Update status and document decisions
16
94
 
17
95
  ## When to Use Specs
18
96
 
19
- Write a spec for:
97
+ **Write a spec for:**
20
98
  - Features affecting multiple parts of the system
21
99
  - Breaking changes or significant refactors
22
100
  - Design decisions needing team alignment
23
101
 
24
- Skip specs for:
102
+ **Skip specs for:**
25
103
  - Bug fixes
26
104
  - Trivial changes
27
105
  - Self-explanatory refactors
28
106
 
29
- ## Essential Commands
30
-
31
- **Quick Reference** (for full details, see `lean-spec --help`):
32
-
33
- **Discovery:**
34
- - `lean-spec list` - See all specs
35
- - `lean-spec search "<query>"` - Find relevant specs
36
-
37
- **Working with specs:**
38
- - `lean-spec create <name>` - Create new spec
39
- - `lean-spec update <spec> --status <status>` - Update status (REQUIRED - never edit frontmatter manually)
40
- - `lean-spec update <spec> --priority <priority>` - Update priority
41
- - `lean-spec deps <spec>` - Show dependency graph
42
- - `lean-spec tokens <spec>` - Count tokens for context management
43
-
44
- **Project overview:**
45
- - `lean-spec board` - Kanban view with project health
46
- - `lean-spec stats` - Quick project metrics
47
-
48
- **When in doubt:** Run `lean-spec --help` or `lean-spec <command> --help` to discover commands.
49
-
50
107
  ## Spec Relationships
51
108
 
52
- LeanSpec has two types of relationships:
53
-
54
109
  ### `related` - Bidirectional Soft Reference
55
- Informational relationship between specs. Automatically shown from both sides.
56
-
57
- **Use when:** Specs cover related topics, work is coordinated but not blocking.
110
+ Informational relationship between specs. Shown from both sides.
111
+ **Use when:** Related topics, coordinated but not blocking work.
58
112
 
59
113
  ### `depends_on` - Directional Blocking Dependency
60
114
  Hard dependency - spec cannot start until dependencies complete.
115
+ **Use when:** True blocking dependency, work order matters.
61
116
 
62
- **Use when:** Spec truly cannot start until another completes, work order matters.
63
-
64
- **Best Practice:** Use `related` by default. Reserve `depends_on` for true blocking dependencies.
65
-
66
- ## SDD Workflow
67
-
68
- 1. **Discover** - Check existing specs with `lean-spec list`
69
- 2. **Plan** - Create spec with `lean-spec create <name>` (status: `planned`)
70
- 3. **Start Work** - Run `lean-spec update <spec> --status in-progress` before implementing
71
- 4. **Implement** - Write code/docs, keep spec in sync as you learn
72
- 5. **Complete** - Run `lean-spec update <spec> --status complete` after implementation done
73
- 6. **Document** - Report progress and document changes into the spec
74
-
75
- **CRITICAL - What "Work" Means:**
76
- - ❌ **NOT**: Creating/writing the spec document itself
77
- - ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
78
-
79
- **Frontmatter Editing Rules:**
80
- - **NEVER manually edit**: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on`, `related`
81
- - **Use CLI commands**: `lean-spec update`, `lean-spec link`, `lean-spec unlink`
82
-
83
- **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.
117
+ **Default:** Use `related`. Reserve `depends_on` for true blockers.
84
118
 
85
119
  ## Quality Standards
86
120
 
87
- - Code is clear and maintainable
88
- - Tests cover critical paths
89
- - Specs stay in sync with implementation
90
121
  - **Status tracking is mandatory:**
91
- - Specs start as `planned` after creation
92
- - Mark `in-progress` BEFORE starting implementation work
93
- - Mark `complete` AFTER implementation is finished
94
- - **Remember**: Status tracks implementation, not spec document completion
95
- - Never leave specs with stale status
122
+ - `planned` → after creation
123
+ - `in-progress` → BEFORE starting implementation
124
+ - `complete` → AFTER finishing implementation
125
+ - Specs stay in sync with implementation
126
+ - Never leave specs with stale status
96
127
 
97
128
  ## Spec Complexity Guidelines
98
129
 
99
- **Token Thresholds:**
100
- - **<2,000 tokens**: ✅ Optimal
101
- - **2,000-3,500 tokens**: ✅ Good
102
- - **3,500-5,000 tokens**: ⚠️ Warning - Consider splitting
103
- - **>5,000 tokens**: 🔴 Should split
104
-
105
- **Check with:** `lean-spec tokens <spec>`
106
-
107
- **When to split:** >3,500 tokens, multiple concerns, takes >10 min to read
130
+ | Tokens | Status |
131
+ |--------|--------|
132
+ | <2,000 | ✅ Optimal |
133
+ | 2,000-3,500 | ✅ Good |
134
+ | 3,500-5,000 | ⚠️ Consider splitting |
135
+ | >5,000 | 🔴 Should split |
108
136
 
109
- **How to split:** Use sub-specs or split into related specs with `lean-spec link --related`
137
+ Use `tokens` tool to check spec size.
110
138
 
111
139
  ---
112
140
 
113
- **Remember**: LeanSpec is a mindset, not a rulebook. When in doubt, keep it simple and use `lean-spec --help` to discover features as needed.
141
+ **Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!