lean-spec 0.2.7 → 0.2.9-dev.20251205030455
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.
- package/dist/backfill-446GBTBC.js +5 -0
- package/dist/backfill-446GBTBC.js.map +1 -0
- package/dist/{chunk-Q6B3LVO7.js → chunk-BJHJ6IUO.js} +3095 -6151
- package/dist/chunk-BJHJ6IUO.js.map +1 -0
- package/dist/chunk-CJMVV46H.js +2990 -0
- package/dist/chunk-CJMVV46H.js.map +1 -0
- package/dist/chunk-H5MCUMBK.js +741 -0
- package/dist/chunk-H5MCUMBK.js.map +1 -0
- package/dist/chunk-RF5PKL6L.js +298 -0
- package/dist/chunk-RF5PKL6L.js.map +1 -0
- package/dist/{chunk-LVD7ZAVZ.js → chunk-VN5BUHTV.js} +5 -3
- package/dist/chunk-VN5BUHTV.js.map +1 -0
- package/dist/cli.js +5 -3
- package/dist/cli.js.map +1 -1
- package/dist/{frontmatter-R2DANL5X.js → frontmatter-6ZBAGOEU.js} +3 -3
- package/dist/{frontmatter-R2DANL5X.js.map → frontmatter-6ZBAGOEU.js.map} +1 -1
- package/dist/mcp-server.js +5 -2
- package/dist/validate-DIWYTDEF.js +5 -0
- package/dist/validate-DIWYTDEF.js.map +1 -0
- package/package.json +2 -2
- package/templates/detailed/AGENTS.md +54 -115
- package/templates/detailed/README.md +3 -3
- package/templates/examples/api-refactor/README.md +1 -1
- package/templates/examples/dark-theme/README.md +1 -1
- package/templates/examples/dashboard-widgets/README.md +1 -1
- package/templates/standard/AGENTS.md +54 -115
- package/templates/standard/README.md +1 -2
- package/dist/chunk-LVD7ZAVZ.js.map +0 -1
- package/dist/chunk-Q6B3LVO7.js.map +0 -1
package/dist/cli.js
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
|
-
import { agentCommand, analyzeCommand, archiveCommand,
|
|
2
|
-
import './chunk-
|
|
1
|
+
import { agentCommand, analyzeCommand, archiveCommand, boardCommand, checkCommand, compactCommand, createCommand, depsCommand, examplesCommand, filesCommand, ganttCommand, initCommand, linkCommand, listCommand, mcpCommand, migrateCommand, openCommand, searchCommand, splitCommand, statsCommand, templatesCommand, timelineCommand, tokensCommand, uiCommand, unlinkCommand, updateCommand, viewCommand } from './chunk-BJHJ6IUO.js';
|
|
2
|
+
import { backfillCommand } from './chunk-H5MCUMBK.js';
|
|
3
|
+
import { validateCommand } from './chunk-CJMVV46H.js';
|
|
4
|
+
import './chunk-RF5PKL6L.js';
|
|
5
|
+
import './chunk-VN5BUHTV.js';
|
|
3
6
|
import { Command } from 'commander';
|
|
4
7
|
import { readFileSync } from 'fs';
|
|
5
8
|
import { fileURLToPath } from 'url';
|
|
@@ -102,7 +105,6 @@ Examples:
|
|
|
102
105
|
$ lean-spec list --status in-progress
|
|
103
106
|
$ lean-spec view 042
|
|
104
107
|
$ lean-spec link 085 --depends-on 042,035
|
|
105
|
-
$ lean-spec link 085 --related 082
|
|
106
108
|
$ lean-spec unlink 085 --depends-on 042
|
|
107
109
|
$ lean-spec deps 085
|
|
108
110
|
$ lean-spec backfill --dry-run
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/commands/registry.ts","../src/cli.ts"],"names":["program"],"mappings":"
|
|
1
|
+
{"version":3,"sources":["../src/commands/registry.ts","../src/cli.ts"],"names":["program"],"mappings":";;;;;;;;;;;AAoCO,SAAS,iBAAiBA,QAAAA,EAAwB;AAEvD,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,cAAA,EAAgB,CAAA;AACnC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,cAAA,EAAgB,CAAA;AACnC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,eAAA,EAAiB,CAAA;AACpC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,cAAA,EAAgB,CAAA;AACnC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,aAAA,EAAe,CAAA;AAClC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,WAAA,EAAa,CAAA;AAChC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,eAAA,EAAiB,CAAA;AACpC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,WAAA,EAAa,CAAA;AAChC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,WAAA,EAAa,CAAA;AAChC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,WAAA,EAAa,CAAA;AAChC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,UAAA,EAAY,CAAA;AAC/B,EAAAA,QAAAA,CAAQ,UAAA,CAAW,cAAA,EAAgB,CAAA;AACnC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,WAAA,EAAa,CAAA;AAChC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,aAAA,EAAe,CAAA;AAClC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,YAAA,EAAc,CAAA;AACjC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,gBAAA,EAAkB,CAAA;AACrC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,eAAA,EAAiB,CAAA;AACpC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,aAAA,EAAe,CAAA;AAClC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,SAAA,EAAW,CAAA;AAC9B,EAAAA,QAAAA,CAAQ,UAAA,CAAW,aAAA,EAAe,CAAA;AAClC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,aAAA,EAAe,CAAA;AAClC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,eAAA,EAAiB,CAAA;AACpC,EAAAA,QAAAA,CAAQ,UAAA,CAAW,WAAA,EAAa,CAAA;AAClC;;;AC5DA,IAAM,UAAA,GAAa,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AAChD,IAAM,SAAA,GAAY,QAAQ,UAAU,CAAA;AACpC,IAAM,cAAc,IAAA,CAAK,KAAA;AAAA,EACvB,YAAA,CAAa,IAAA,CAAK,SAAA,EAAW,iBAAiB,GAAG,OAAO;AAC1D,CAAA;AAEA,IAAM,OAAA,GAAU,IAAI,OAAA,EAAQ;AAE5B,OAAA,CACG,IAAA,CAAK,WAAW,CAAA,CAChB,WAAA,CAAY,2BAA2B,CAAA,CACvC,OAAA,CAAQ,YAAY,OAAO,CAAA;AAG9B,OAAA,CAAQ,YAAY,OAAA,EAAS;AAAA;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,CAyE5B,CAAA;AAGD,gBAAA,CAAiB,OAAO,CAAA;AAGxB,OAAA,CAAQ,KAAA,EAAM","file":"cli.js","sourcesContent":["import { Command } from 'commander';\nimport {\n agentCommand,\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(agentCommand());\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 agent Dispatch specs to AI coding agents\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 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 agent list\n $ lean-spec agent run 045 --agent claude\n $ lean-spec agent run 045 047 048 --parallel\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"]}
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export { enrichWithTimestamps, getSpecFile, matchesFilter, normalizeDateFields, normalizeTagsField, parseFrontmatter, updateFrontmatter, validateCustomField, validateCustomFields } from './chunk-
|
|
2
|
-
//# sourceMappingURL=frontmatter-
|
|
3
|
-
//# sourceMappingURL=frontmatter-
|
|
1
|
+
export { enrichWithTimestamps, getSpecFile, matchesFilter, normalizeDateFields, normalizeTagsField, parseFrontmatter, updateFrontmatter, validateCustomField, validateCustomFields } from './chunk-VN5BUHTV.js';
|
|
2
|
+
//# sourceMappingURL=frontmatter-6ZBAGOEU.js.map
|
|
3
|
+
//# sourceMappingURL=frontmatter-6ZBAGOEU.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":[],"names":[],"mappings":"","file":"frontmatter-
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"frontmatter-6ZBAGOEU.js"}
|
package/dist/mcp-server.js
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
export { createMcpServer } from './chunk-
|
|
3
|
-
import './chunk-
|
|
2
|
+
export { createMcpServer } from './chunk-BJHJ6IUO.js';
|
|
3
|
+
import './chunk-H5MCUMBK.js';
|
|
4
|
+
import './chunk-CJMVV46H.js';
|
|
5
|
+
import './chunk-RF5PKL6L.js';
|
|
6
|
+
import './chunk-VN5BUHTV.js';
|
|
4
7
|
//# sourceMappingURL=mcp-server.js.map
|
|
5
8
|
//# sourceMappingURL=mcp-server.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"validate-DIWYTDEF.js"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "lean-spec",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.9-dev.20251205030455",
|
|
4
4
|
"description": "Specification-driven development made simple",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -67,7 +67,7 @@
|
|
|
67
67
|
"zod": "^3.25.76"
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
|
-
"@leanspec/core": "
|
|
70
|
+
"@leanspec/core": "workspace:*",
|
|
71
71
|
"@types/js-yaml": "^4.0.9",
|
|
72
72
|
"@types/marked-terminal": "^6.1.1",
|
|
73
73
|
"@types/node": "^20.10.0",
|
|
@@ -2,25 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
## Project: {project_name}
|
|
4
4
|
|
|
5
|
-
<!-- ═══════════════════════════════════════════════════════════════════════════
|
|
6
|
-
👇 TODO: Fill in your project context below (then delete these comments)
|
|
7
|
-
═══════════════════════════════════════════════════════════════════════════ -->
|
|
8
|
-
|
|
9
|
-
### 📋 Project Context
|
|
10
|
-
|
|
11
|
-
**What this project does:**
|
|
12
|
-
_TODO: Describe your project in 1-2 sentences_
|
|
13
|
-
|
|
14
|
-
**Tech stack:**
|
|
15
|
-
_TODO: List main technologies (e.g., Node.js, React, PostgreSQL)_
|
|
16
|
-
|
|
17
|
-
**Key objectives:**
|
|
18
|
-
_TODO: What are you building toward? (e.g., Launch MVP by Q1)_
|
|
19
|
-
|
|
20
|
-
<!-- ═══════════════════════════════════════════════════════════════════════════
|
|
21
|
-
👆 End of TODO section - Delete these comment markers when done
|
|
22
|
-
═══════════════════════════════════════════════════════════════════════════ -->
|
|
23
|
-
|
|
24
5
|
## 🚨 CRITICAL: Before ANY Task
|
|
25
6
|
|
|
26
7
|
**STOP and check these first:**
|
|
@@ -31,128 +12,86 @@ _TODO: What are you building toward? (e.g., Launch MVP by Q1)_
|
|
|
31
12
|
|
|
32
13
|
> **Why?** Skipping discovery creates duplicate work. Manual file creation breaks LeanSpec tooling.
|
|
33
14
|
|
|
34
|
-
## 🔧
|
|
35
|
-
|
|
36
|
-
### Primary Method: MCP Tools (Recommended)
|
|
37
|
-
|
|
38
|
-
If you have LeanSpec MCP tools available, **ALWAYS use them**:
|
|
39
|
-
|
|
40
|
-
| Action | MCP Tool | Description |
|
|
41
|
-
|--------|----------|-------------|
|
|
42
|
-
| See project status | `board` | Kanban view + project health metrics |
|
|
43
|
-
| List all specs | `list` | Filterable list with metadata |
|
|
44
|
-
| Search specs | `search` | Semantic search across all content |
|
|
45
|
-
| View a spec | `view` | Full content with formatting |
|
|
46
|
-
| Create new spec | `create` | Auto-sequences, proper structure |
|
|
47
|
-
| Update spec | `update` | Validates transitions, timestamps |
|
|
48
|
-
| Check dependencies | `deps` | Visual dependency graph |
|
|
49
|
-
|
|
50
|
-
**Why MCP over CLI?**
|
|
51
|
-
- ✅ Direct tool integration (no shell execution needed)
|
|
52
|
-
- ✅ Structured responses (better for AI reasoning)
|
|
53
|
-
- ✅ Real-time validation (immediate feedback)
|
|
54
|
-
- ✅ Context-aware (understands project state)
|
|
55
|
-
|
|
56
|
-
### Fallback: CLI Commands
|
|
57
|
-
|
|
58
|
-
If MCP tools are not available, use CLI commands:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
lean-spec board # Project overview
|
|
62
|
-
lean-spec list # See all specs
|
|
63
|
-
lean-spec search "query" # Find relevant specs
|
|
64
|
-
lean-spec create <name> # Create new spec
|
|
65
|
-
lean-spec update <spec> --status <status> # Update status
|
|
66
|
-
lean-spec deps <spec> # Show dependencies
|
|
67
|
-
```
|
|
15
|
+
## 🔧 Managing Specs
|
|
68
16
|
|
|
69
|
-
|
|
17
|
+
### MCP Tools (Preferred) with CLI Fallback
|
|
70
18
|
|
|
71
|
-
|
|
19
|
+
| Action | MCP Tool | CLI Fallback |
|
|
20
|
+
|--------|----------|--------------|
|
|
21
|
+
| Project status | `board` | `lean-spec board` |
|
|
22
|
+
| List specs | `list` | `lean-spec list` |
|
|
23
|
+
| Search specs | `search` | `lean-spec search "query"` |
|
|
24
|
+
| View spec | `view` | `lean-spec view <spec>` |
|
|
25
|
+
| Create spec | `create` | `lean-spec create <name>` |
|
|
26
|
+
| Update spec | `update` | `lean-spec update <spec> --status <status>` |
|
|
27
|
+
| Link specs | `link` | `lean-spec link <spec> --depends-on <other>` |
|
|
28
|
+
| Unlink specs | `unlink` | `lean-spec unlink <spec> --depends-on <other>` |
|
|
29
|
+
| Dependencies | `deps` | `lean-spec deps <spec>` |
|
|
30
|
+
| Token count | `tokens` | `lean-spec tokens <spec>` |
|
|
72
31
|
|
|
73
|
-
|
|
32
|
+
## ⚠️ Core Rules
|
|
74
33
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
34
|
+
| Rule | Details |
|
|
35
|
+
|------|---------|
|
|
36
|
+
| **NEVER edit frontmatter manually** | Use `update`, `link`, `unlink` for: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on` |
|
|
37
|
+
| **ALWAYS link spec references** | Content mentions another spec → `lean-spec link <spec> --depends-on <other>` |
|
|
38
|
+
| **Track status transitions** | `planned` → `in-progress` (before coding) → `complete` (after done) |
|
|
39
|
+
| **No nested code blocks** | Use indentation instead |
|
|
78
40
|
|
|
79
|
-
###
|
|
80
|
-
|
|
81
|
-
4. 📊 **Update status to `in-progress`** BEFORE coding
|
|
82
|
-
5. 📝 **Document decisions** in the spec as you work
|
|
83
|
-
6. 🔗 **Link related specs** if you discover connections
|
|
84
|
-
|
|
85
|
-
### After Completing Work
|
|
86
|
-
|
|
87
|
-
7. ✅ **Update status to `complete`** when done
|
|
88
|
-
8. 📄 **Document what you learned** in the spec
|
|
89
|
-
9. 🤔 **Create follow-up specs** if needed
|
|
90
|
-
|
|
91
|
-
### 🚫 Common Mistakes to Avoid
|
|
41
|
+
### 🚫 Common Mistakes
|
|
92
42
|
|
|
93
43
|
| ❌ Don't | ✅ Do Instead |
|
|
94
44
|
|----------|---------------|
|
|
95
45
|
| Create spec files manually | Use `create` tool |
|
|
96
|
-
| Skip discovery
|
|
97
|
-
| Leave status as "planned"
|
|
98
|
-
| Finish work without updating spec | Document decisions, update status |
|
|
46
|
+
| Skip discovery | Run `board` and `search` first |
|
|
47
|
+
| Leave status as "planned" | Update to `in-progress` before coding |
|
|
99
48
|
| Edit frontmatter manually | Use `update` tool |
|
|
100
|
-
| Forget about specs mid-conversation | Check spec status periodically |
|
|
101
|
-
|
|
102
|
-
## Core Rules
|
|
103
|
-
|
|
104
|
-
1. **Read README.md first** - Understand project context
|
|
105
|
-
2. **Check specs/** - Review existing specs before starting
|
|
106
|
-
3. **Use MCP tools** - Prefer MCP over CLI when available
|
|
107
|
-
4. **Follow LeanSpec principles** - Clarity over documentation
|
|
108
|
-
5. **Keep it minimal** - If it doesn't add clarity, cut it
|
|
109
|
-
6. **NEVER manually edit frontmatter** - Use `update`, `link`, `unlink` tools
|
|
110
|
-
7. **Track progress in specs** - Update status and document decisions
|
|
111
|
-
|
|
112
|
-
## When to Use Specs
|
|
113
49
|
|
|
114
|
-
|
|
115
|
-
- Features affecting multiple parts of the system
|
|
116
|
-
- Breaking changes or significant refactors
|
|
117
|
-
- Design decisions needing team alignment
|
|
50
|
+
## 📋 SDD Workflow
|
|
118
51
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
-
|
|
122
|
-
|
|
52
|
+
```
|
|
53
|
+
BEFORE: board → search → check existing specs
|
|
54
|
+
DURING: update status to in-progress → code → document decisions → link dependencies
|
|
55
|
+
AFTER: update status to complete → document learnings
|
|
56
|
+
```
|
|
123
57
|
|
|
124
|
-
|
|
58
|
+
**Status tracks implementation, NOT spec writing.**
|
|
125
59
|
|
|
126
|
-
|
|
127
|
-
Informational relationship between specs. Shown from both sides.
|
|
128
|
-
**Use when:** Related topics, coordinated but not blocking work.
|
|
60
|
+
## Spec Dependencies
|
|
129
61
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
**Use when:** True blocking dependency, work order matters.
|
|
62
|
+
Use `depends_on` to express blocking relationships between specs:
|
|
63
|
+
- **`depends_on`** = True blocker, work order matters, directional (A depends on B)
|
|
133
64
|
|
|
134
|
-
|
|
65
|
+
Link dependencies when one spec builds on another:
|
|
66
|
+
```bash
|
|
67
|
+
lean-spec link <spec> --depends-on <other-spec>
|
|
68
|
+
```
|
|
135
69
|
|
|
136
|
-
##
|
|
70
|
+
## When to Use Specs
|
|
137
71
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
- Never leave specs with stale status
|
|
72
|
+
| ✅ Write spec | ❌ Skip spec |
|
|
73
|
+
|---------------|--------------|
|
|
74
|
+
| Multi-part features | Bug fixes |
|
|
75
|
+
| Breaking changes | Trivial changes |
|
|
76
|
+
| Design decisions | Self-explanatory refactors |
|
|
144
77
|
|
|
145
|
-
##
|
|
78
|
+
## Token Thresholds
|
|
146
79
|
|
|
147
80
|
| Tokens | Status |
|
|
148
81
|
|--------|--------|
|
|
149
82
|
| <2,000 | ✅ Optimal |
|
|
150
83
|
| 2,000-3,500 | ✅ Good |
|
|
151
84
|
| 3,500-5,000 | ⚠️ Consider splitting |
|
|
152
|
-
| >5,000 | 🔴
|
|
85
|
+
| >5,000 | 🔴 Must split |
|
|
86
|
+
|
|
87
|
+
## First Principles (Priority Order)
|
|
153
88
|
|
|
154
|
-
|
|
89
|
+
1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting
|
|
90
|
+
2. **Signal-to-Noise** - Every word must inform a decision
|
|
91
|
+
3. **Intent Over Implementation** - Capture why, let how emerge
|
|
92
|
+
4. **Bridge the Gap** - Both human and AI must understand
|
|
93
|
+
5. **Progressive Disclosure** - Add complexity only when pain is felt
|
|
155
94
|
|
|
156
95
|
---
|
|
157
96
|
|
|
158
|
-
**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!
|
|
97
|
+
**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!
|
|
@@ -22,7 +22,7 @@ Keep it lean, but organized. Use sub-specs to manage complexity without overwhel
|
|
|
22
22
|
|
|
23
23
|
## Next Steps
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
25
|
+
You're ready to go! Ask your AI to create a spec for your next feature.
|
|
26
|
+
|
|
27
|
+
When a spec grows large, consider splitting sections into sub-spec files.
|
|
28
28
|
|
|
@@ -2,25 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
## Project: {project_name}
|
|
4
4
|
|
|
5
|
-
<!-- ═══════════════════════════════════════════════════════════════════════════
|
|
6
|
-
👇 TODO: Fill in your project context below (then delete these comments)
|
|
7
|
-
═══════════════════════════════════════════════════════════════════════════ -->
|
|
8
|
-
|
|
9
|
-
### 📋 Project Context
|
|
10
|
-
|
|
11
|
-
**What this project does:**
|
|
12
|
-
_TODO: Describe your project in 1-2 sentences_
|
|
13
|
-
|
|
14
|
-
**Tech stack:**
|
|
15
|
-
_TODO: List main technologies (e.g., Node.js, React, PostgreSQL)_
|
|
16
|
-
|
|
17
|
-
**Key objectives:**
|
|
18
|
-
_TODO: What are you building toward? (e.g., Launch MVP by Q1)_
|
|
19
|
-
|
|
20
|
-
<!-- ═══════════════════════════════════════════════════════════════════════════
|
|
21
|
-
👆 End of TODO section - Delete these comment markers when done
|
|
22
|
-
═══════════════════════════════════════════════════════════════════════════ -->
|
|
23
|
-
|
|
24
5
|
## 🚨 CRITICAL: Before ANY Task
|
|
25
6
|
|
|
26
7
|
**STOP and check these first:**
|
|
@@ -31,128 +12,86 @@ _TODO: What are you building toward? (e.g., Launch MVP by Q1)_
|
|
|
31
12
|
|
|
32
13
|
> **Why?** Skipping discovery creates duplicate work. Manual file creation breaks LeanSpec tooling.
|
|
33
14
|
|
|
34
|
-
## 🔧
|
|
35
|
-
|
|
36
|
-
### Primary Method: MCP Tools (Recommended)
|
|
37
|
-
|
|
38
|
-
If you have LeanSpec MCP tools available, **ALWAYS use them**:
|
|
39
|
-
|
|
40
|
-
| Action | MCP Tool | Description |
|
|
41
|
-
|--------|----------|-------------|
|
|
42
|
-
| See project status | `board` | Kanban view + project health metrics |
|
|
43
|
-
| List all specs | `list` | Filterable list with metadata |
|
|
44
|
-
| Search specs | `search` | Semantic search across all content |
|
|
45
|
-
| View a spec | `view` | Full content with formatting |
|
|
46
|
-
| Create new spec | `create` | Auto-sequences, proper structure |
|
|
47
|
-
| Update spec | `update` | Validates transitions, timestamps |
|
|
48
|
-
| Check dependencies | `deps` | Visual dependency graph |
|
|
49
|
-
|
|
50
|
-
**Why MCP over CLI?**
|
|
51
|
-
- ✅ Direct tool integration (no shell execution needed)
|
|
52
|
-
- ✅ Structured responses (better for AI reasoning)
|
|
53
|
-
- ✅ Real-time validation (immediate feedback)
|
|
54
|
-
- ✅ Context-aware (understands project state)
|
|
55
|
-
|
|
56
|
-
### Fallback: CLI Commands
|
|
57
|
-
|
|
58
|
-
If MCP tools are not available, use CLI commands:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
lean-spec board # Project overview
|
|
62
|
-
lean-spec list # See all specs
|
|
63
|
-
lean-spec search "query" # Find relevant specs
|
|
64
|
-
lean-spec create <name> # Create new spec
|
|
65
|
-
lean-spec update <spec> --status <status> # Update status
|
|
66
|
-
lean-spec deps <spec> # Show dependencies
|
|
67
|
-
```
|
|
15
|
+
## 🔧 Managing Specs
|
|
68
16
|
|
|
69
|
-
|
|
17
|
+
### MCP Tools (Preferred) with CLI Fallback
|
|
70
18
|
|
|
71
|
-
|
|
19
|
+
| Action | MCP Tool | CLI Fallback |
|
|
20
|
+
|--------|----------|--------------|
|
|
21
|
+
| Project status | `board` | `lean-spec board` |
|
|
22
|
+
| List specs | `list` | `lean-spec list` |
|
|
23
|
+
| Search specs | `search` | `lean-spec search "query"` |
|
|
24
|
+
| View spec | `view` | `lean-spec view <spec>` |
|
|
25
|
+
| Create spec | `create` | `lean-spec create <name>` |
|
|
26
|
+
| Update spec | `update` | `lean-spec update <spec> --status <status>` |
|
|
27
|
+
| Link specs | `link` | `lean-spec link <spec> --depends-on <other>` |
|
|
28
|
+
| Unlink specs | `unlink` | `lean-spec unlink <spec> --depends-on <other>` |
|
|
29
|
+
| Dependencies | `deps` | `lean-spec deps <spec>` |
|
|
30
|
+
| Token count | `tokens` | `lean-spec tokens <spec>` |
|
|
72
31
|
|
|
73
|
-
|
|
32
|
+
## ⚠️ Core Rules
|
|
74
33
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
34
|
+
| Rule | Details |
|
|
35
|
+
|------|---------|
|
|
36
|
+
| **NEVER edit frontmatter manually** | Use `update`, `link`, `unlink` for: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on` |
|
|
37
|
+
| **ALWAYS link spec references** | Content mentions another spec → `lean-spec link <spec> --depends-on <other>` |
|
|
38
|
+
| **Track status transitions** | `planned` → `in-progress` (before coding) → `complete` (after done) |
|
|
39
|
+
| **No nested code blocks** | Use indentation instead |
|
|
78
40
|
|
|
79
|
-
###
|
|
80
|
-
|
|
81
|
-
4. 📊 **Update status to `in-progress`** BEFORE coding
|
|
82
|
-
5. 📝 **Document decisions** in the spec as you work
|
|
83
|
-
6. 🔗 **Link related specs** if you discover connections
|
|
84
|
-
|
|
85
|
-
### After Completing Work
|
|
86
|
-
|
|
87
|
-
7. ✅ **Update status to `complete`** when done
|
|
88
|
-
8. 📄 **Document what you learned** in the spec
|
|
89
|
-
9. 🤔 **Create follow-up specs** if needed
|
|
90
|
-
|
|
91
|
-
### 🚫 Common Mistakes to Avoid
|
|
41
|
+
### 🚫 Common Mistakes
|
|
92
42
|
|
|
93
43
|
| ❌ Don't | ✅ Do Instead |
|
|
94
44
|
|----------|---------------|
|
|
95
45
|
| Create spec files manually | Use `create` tool |
|
|
96
|
-
| Skip discovery
|
|
97
|
-
| Leave status as "planned"
|
|
98
|
-
| Finish work without updating spec | Document decisions, update status |
|
|
46
|
+
| Skip discovery | Run `board` and `search` first |
|
|
47
|
+
| Leave status as "planned" | Update to `in-progress` before coding |
|
|
99
48
|
| Edit frontmatter manually | Use `update` tool |
|
|
100
|
-
| Forget about specs mid-conversation | Check spec status periodically |
|
|
101
|
-
|
|
102
|
-
## Core Rules
|
|
103
|
-
|
|
104
|
-
1. **Read README.md first** - Understand project context
|
|
105
|
-
2. **Check specs/** - Review existing specs before starting
|
|
106
|
-
3. **Use MCP tools** - Prefer MCP over CLI when available
|
|
107
|
-
4. **Follow LeanSpec principles** - Clarity over documentation
|
|
108
|
-
5. **Keep it minimal** - If it doesn't add clarity, cut it
|
|
109
|
-
6. **NEVER manually edit frontmatter** - Use `update`, `link`, `unlink` tools
|
|
110
|
-
7. **Track progress in specs** - Update status and document decisions
|
|
111
|
-
|
|
112
|
-
## When to Use Specs
|
|
113
49
|
|
|
114
|
-
|
|
115
|
-
- Features affecting multiple parts of the system
|
|
116
|
-
- Breaking changes or significant refactors
|
|
117
|
-
- Design decisions needing team alignment
|
|
50
|
+
## 📋 SDD Workflow
|
|
118
51
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
-
|
|
122
|
-
|
|
52
|
+
```
|
|
53
|
+
BEFORE: board → search → check existing specs
|
|
54
|
+
DURING: update status to in-progress → code → document decisions → link dependencies
|
|
55
|
+
AFTER: update status to complete → document learnings
|
|
56
|
+
```
|
|
123
57
|
|
|
124
|
-
|
|
58
|
+
**Status tracks implementation, NOT spec writing.**
|
|
125
59
|
|
|
126
|
-
|
|
127
|
-
Informational relationship between specs. Shown from both sides.
|
|
128
|
-
**Use when:** Related topics, coordinated but not blocking work.
|
|
60
|
+
## Spec Dependencies
|
|
129
61
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
**Use when:** True blocking dependency, work order matters.
|
|
62
|
+
Use `depends_on` to express blocking relationships between specs:
|
|
63
|
+
- **`depends_on`** = True blocker, work order matters, directional (A depends on B)
|
|
133
64
|
|
|
134
|
-
|
|
65
|
+
Link dependencies when one spec builds on another:
|
|
66
|
+
```bash
|
|
67
|
+
lean-spec link <spec> --depends-on <other-spec>
|
|
68
|
+
```
|
|
135
69
|
|
|
136
|
-
##
|
|
70
|
+
## When to Use Specs
|
|
137
71
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
- Never leave specs with stale status
|
|
72
|
+
| ✅ Write spec | ❌ Skip spec |
|
|
73
|
+
|---------------|--------------|
|
|
74
|
+
| Multi-part features | Bug fixes |
|
|
75
|
+
| Breaking changes | Trivial changes |
|
|
76
|
+
| Design decisions | Self-explanatory refactors |
|
|
144
77
|
|
|
145
|
-
##
|
|
78
|
+
## Token Thresholds
|
|
146
79
|
|
|
147
80
|
| Tokens | Status |
|
|
148
81
|
|--------|--------|
|
|
149
82
|
| <2,000 | ✅ Optimal |
|
|
150
83
|
| 2,000-3,500 | ✅ Good |
|
|
151
84
|
| 3,500-5,000 | ⚠️ Consider splitting |
|
|
152
|
-
| >5,000 | 🔴
|
|
85
|
+
| >5,000 | 🔴 Must split |
|
|
86
|
+
|
|
87
|
+
## First Principles (Priority Order)
|
|
153
88
|
|
|
154
|
-
|
|
89
|
+
1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting
|
|
90
|
+
2. **Signal-to-Noise** - Every word must inform a decision
|
|
91
|
+
3. **Intent Over Implementation** - Capture why, let how emerge
|
|
92
|
+
4. **Bridge the Gap** - Both human and AI must understand
|
|
93
|
+
5. **Progressive Disclosure** - Add complexity only when pain is felt
|
|
155
94
|
|
|
156
95
|
---
|
|
157
96
|
|
|
158
|
-
**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!
|
|
97
|
+
**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!
|
|
@@ -21,6 +21,5 @@ Keep it lean. Write specs for features that need clarity. Skip them for obvious
|
|
|
21
21
|
|
|
22
22
|
## Next Steps
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
2. Create your first spec: `lean-spec create my-feature`
|
|
24
|
+
You're ready to go! Ask your AI to create a spec for your next feature.
|
|
26
25
|
|