lean-spec 0.2.2 → 0.2.4

package/templates/_shared/agents-components/quality-standards-shared.md

@@ -0,0 +1,6 @@
+- Code is clear and maintainable
+- Specs stay in sync with implementation
+- **Status tracking is mandatory:**
+  - Mark spec as `in-progress` BEFORE starting work
+  - Mark spec as `complete` IMMEDIATELY after finishing
+  - Never leave specs with stale status

package/templates/_shared/agents-components/status-update-triggers.md

@@ -0,0 +1,14 @@
+**CRITICAL - What "Work" Means:**
+- ❌ **NOT**: Creating/writing the spec document itself
+- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+- **Example**: Creating a spec for "API redesign" ≠ work complete
+  - Work = Actually redesigning the API as described in the spec
+  - Status `planned` until someone starts the redesign
+  - Status `in-progress` while redesigning
+  - Status `complete` after redesign is done
+
+**Status Update Triggers:**
+- ✅ **Before starting implementation** → `lean-spec update <spec> --status in-progress`
+- ✅ **After completing implementation** → `lean-spec update <spec> --status complete`
+- ✅ **If blocked or paused** → Update status and document why in spec
+- ❌ **NEVER mark spec complete just because you finished writing it**

package/templates/_shared/agents-components/workflow-enterprise.md

@@ -1,8 +1,11 @@
 1. **Discover context** - Run `lean-spec stats`, `lean-spec board`, or `lean-spec gantt`
 2. **Search existing specs** - Use `lean-spec search` or `lean-spec list --tag=<relevant>`
 3. **Check dependencies** - Run `lean-spec deps <spec>` to understand dependencies
-4. **Create or update spec** - Add complete frontmatter with compliance tags
+4. **Create or update spec** - Add complete frontmatter with compliance tags (status: `planned`)
 5. **Get reviews** - Assign reviewer, tag for security review if needed
-6. **Implement changes** - Keep spec in sync, update status appropriately
-7. **Update status** - Mark progress through workflow states
-8. **Archive when done** - `lean-spec archive <spec>` after completion
+6. **Start implementation** - Mark `in-progress` BEFORE implementing what the spec describes
+7. **Implement changes** - Keep spec in sync, update status appropriately
+8. **Complete implementation** - Mark `complete` AFTER implementing what the spec describes
+9. **Archive when done** - `lean-spec archive <spec>` after completion
+
+**Remember**: Status tracks implementation work, not spec document creation. Creating a spec = planning (stays `planned` until implementation starts).

package/templates/_shared/agents-components/workflow-standard-detailed.md

@@ -1,7 +1,10 @@
 1. **Discover context** - Run `lean-spec stats` or `lean-spec board` to see current state
 2. **Search existing specs** - Use `lean-spec search` or `lean-spec list` to find relevant work
 3. **Check dependencies** - Run `lean-spec deps <spec>` if working on existing spec
-4. **Create or update spec** - Add frontmatter with required fields and helpful metadata
-5. **Implement changes** - Keep spec in sync as you learn
-6. **Update status** - Mark progress: `draft` → `in-progress` → `complete`
-7. **Archive when done** - `lean-spec archive <spec>` moves to archive
+4. **Create or update spec** - Add frontmatter with required fields (status: `planned`)
+5. **Start implementation** - Mark `in-progress` BEFORE implementing what the spec describes
+6. **Implement changes** - Keep spec in sync as you learn
+7. **Complete implementation** - Mark `complete` AFTER implementing what the spec describes
+8. **Archive when done** - `lean-spec archive <spec>` moves to archive
+
+**Remember**: Status tracks implementation work, not spec document creation. Creating a spec = planning (stays `planned` until implementation starts).

package/templates/_shared/agents-components/workflow-standard.md

@@ -1,5 +1,8 @@
 1. **Check existing work** - Run `lean-spec board` or `lean-spec search`
-2. **Create or update spec** - Add frontmatter with `status` and `created`
-3. **Implement changes** - Keep spec in sync as you learn
-4. **Update status** - Mark progress: `draft` → `in-progress` → `complete`
-5. **Archive when done** - `lean-spec archive <spec>` moves to archive
+2. **Create or update spec** - Add frontmatter with `status` and `created` (status: `planned`)
+3. **Start implementation** - Mark `in-progress` BEFORE implementing what the spec describes
+4. **Implement changes** - Keep spec in sync as you learn
+5. **Complete implementation** - Mark `complete` AFTER implementing what the spec describes
+6. **Archive when done** - `lean-spec archive <spec>` moves to archive
+
+**Remember**: Status tracks implementation work, not spec document creation. Creating a spec = planning (stays `planned` until implementation starts).

package/templates/_shared/agents-template.hbs

@@ -17,6 +17,10 @@
 ## Discovery Commands
 
 {{{discoveryCommands}}}
+{{#if essentialCommands}}
+
+{{{essentialCommands}}}
+{{/if}}
 
 ## Spec Frontmatter
 

package/templates/enterprise/agents-config.json

@@ -1,11 +1,12 @@
 {
   "description": "Enterprise-grade development with security and compliance requirements.",
-  "coreRules": "core-rules-enterprise.md",
+  "coreRules": ["core-rules-enterprise-additions.md", "core-rules-shared.md"],
   "whenToUseEarly": false,
-  "discoveryCommands": "discovery-commands-enterprise.md",
+  "discoveryCommands": ["discovery-commands-shared.md", "discovery-commands-enterprise-additions.md"],
+  "essentialCommands": ["essential-commands-shared.md", "essential-commands-enterprise-additions.md"],
   "frontmatter": "frontmatter-enterprise.md",
-  "workflow": "workflow-enterprise.md",
-  "qualityStandards": "quality-standards-enterprise.md",
+  "workflow": ["workflow-enterprise.md", "status-update-triggers.md"],
+  "qualityStandards": ["quality-standards-enterprise-additions.md", "quality-standards-shared.md"],
   "closingNote": "**Remember**: Enterprise doesn't mean heavy. Keep specs lean while meeting governance needs.",
   "additionalSections": [
     "enterprise-compliance.md",

package/templates/enterprise/files/AGENTS.md

@@ -14,16 +14,65 @@ Enterprise-grade development with security and compliance requirements.
 
 ## Discovery Commands
 
-Before starting work, understand project context and dependencies:
+Before starting work, understand project context:
 
-- `lean-spec stats` - See work distribution across specs
-- `lean-spec board` - View specs organized by status
+- `lean-spec stats` - See work distribution
+- `lean-spec board` - View specs by status
+- `lean-spec search "<query>"` - Find relevant work
+- `lean-spec list` - List all specs
+
+These help you understand what exists and what's in progress.
+**Additional commands:**
 - `lean-spec list --tag=<tag>` - Find specs by tag (e.g., `--tag=security`)
-- `lean-spec search "<query>"` - Full-text search across specs
 - `lean-spec deps <spec>` - Check dependencies before starting work
 - `lean-spec gantt` - View project timeline and milestones
 
-These commands help you understand what exists, what's in progress, and what depends on what.
+**Note:** For enterprise, also consider dependencies and project timelines when planning work.
+
+## Essential Commands
+
+**Discovery:**
+- `lean-spec list` - See all specs
+- `lean-spec search "<query>"` - Find relevant specs
+
+**Viewing specs:**
+- `lean-spec view <spec>` - View a spec (formatted)
+- `lean-spec open <spec>` - Open spec in editor
+
+**Working with specs:**
+- `lean-spec create <name>` - Create a new spec
+- `lean-spec update <spec> --status <status>` - Update spec status
+
+**When in doubt:** Run `lean-spec --help` to see all available commands.
+**Viewing specs (additional):**
+- `lean-spec view <spec>/DESIGN.md` - View sub-spec file (DESIGN.md, TESTING.md, etc.)
+- `lean-spec view <spec> --raw` - Get raw markdown (for parsing)
+- `lean-spec view <spec> --json` - Get structured JSON
+- `lean-spec files <spec>` - List all files in a spec (including sub-specs)
+
+**Project Overview:**
+- `lean-spec board` - Kanban view with project health summary
+- `lean-spec stats` - Quick project metrics and insights
+- `lean-spec stats --full` - Detailed analytics (all sections)
+
+**Working with specs (additional):**
+- `lean-spec update <spec> --status <status>` - Update spec status (REQUIRED - never edit frontmatter manually)
+- `lean-spec update <spec> --priority <priority>` - Update spec priority (REQUIRED - never edit frontmatter manually)
+- `lean-spec update <spec> --tags <tag1,tag2>` - Update spec tags (REQUIRED - never edit frontmatter manually)
+- `lean-spec update <spec> --assignee <name>` - Update spec assignee (REQUIRED - never edit frontmatter manually)
+- `lean-spec deps <spec>` - Show dependencies and relationships
+
+**Token Management:**
+- `lean-spec tokens <spec>` - Count tokens in a spec for LLM context management
+- `lean-spec tokens` - Show token counts for all specs (sorted by token count)
+- `lean-spec tokens <spec> --detailed` - Show content breakdown (prose vs code vs tables)
+
+**Advanced Editing (AI Agent Orchestration):**
+- `lean-spec analyze <spec>` - Analyze spec complexity and structure (returns JSON with --json flag)
+- `lean-spec split <spec> --output FILE:LINES` - Split spec into multiple files by line ranges (spec 059)
+- `lean-spec compact <spec> --remove LINES` - Remove specified line ranges from spec (spec 059)
+
+**When in doubt (extended):** Run `lean-spec <command> --help` to discover available commands and options.
 
 ## Spec Frontmatter
 
@@ -104,11 +153,28 @@ Optional for:
 1. **Discover context** - Run `lean-spec stats`, `lean-spec board`, or `lean-spec gantt`
 2. **Search existing specs** - Use `lean-spec search` or `lean-spec list --tag=<relevant>`
 3. **Check dependencies** - Run `lean-spec deps <spec>` to understand dependencies
-4. **Create or update spec** - Add complete frontmatter with compliance tags
+4. **Create or update spec** - Add complete frontmatter with compliance tags (status: `planned`)
 5. **Get reviews** - Assign reviewer, tag for security review if needed
-6. **Implement changes** - Keep spec in sync, update status appropriately
-7. **Update status** - Mark progress through workflow states
-8. **Archive when done** - `lean-spec archive <spec>` after completion
+6. **Start implementation** - Mark `in-progress` BEFORE implementing what the spec describes
+7. **Implement changes** - Keep spec in sync, update status appropriately
+8. **Complete implementation** - Mark `complete` AFTER implementing what the spec describes
+9. **Archive when done** - `lean-spec archive <spec>` after completion
+
+**Remember**: Status tracks implementation work, not spec document creation. Creating a spec = planning (stays `planned` until implementation starts).
+**CRITICAL - What "Work" Means:**
+- ❌ **NOT**: Creating/writing the spec document itself
+- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+- **Example**: Creating a spec for "API redesign" ≠ work complete
+  - Work = Actually redesigning the API as described in the spec
+  - Status `planned` until someone starts the redesign
+  - Status `in-progress` while redesigning
+  - Status `complete` after redesign is done
+
+**Status Update Triggers:**
+- ✅ **Before starting implementation** → `lean-spec update <spec> --status in-progress`
+- ✅ **After completing implementation** → `lean-spec update <spec> --status complete`
+- ✅ **If blocked or paused** → Update status and document why in spec
+- ❌ **NEVER mark spec complete just because you finished writing it**
 
 ## Quality Standards
 
@@ -118,6 +184,10 @@ Optional for:
 - Compliance checklist completed
 - Code is clear and maintainable
 - Specs stay in sync with implementation
+- **Status tracking is mandatory:**
+  - Mark spec as `in-progress` BEFORE starting work
+  - Mark spec as `complete` IMMEDIATELY after finishing
+  - Never leave specs with stale status
 
 ---
 

package/templates/minimal/agents-config.json

@@ -1,12 +1,13 @@
 {
   "description": "Lightweight spec methodology for AI-powered development.",
-  "coreRules": "core-rules-base.md",
+  "coreRules": ["core-rules-base-additions.md", "core-rules-shared.md"],
   "whenToUse": "when-to-use-minimal.md",
   "whenToUseEarly": true,
-  "discoveryCommands": "discovery-commands-minimal.md",
+  "discoveryCommands": ["discovery-commands-shared.md", "discovery-commands-minimal-additions.md"],
+  "essentialCommands": ["essential-commands-shared.md", "essential-commands-minimal-additions.md"],
   "frontmatter": "frontmatter-minimal.md",
-  "workflow": "workflow-standard.md",
-  "qualityStandards": "quality-standards-base.md",
+  "workflow": ["workflow-standard.md", "status-update-triggers.md"],
+  "qualityStandards": ["quality-standards-minimal-additions.md", "quality-standards-shared.md"],
   "closingNote": "**Remember**: LeanSpec is a mindset. Adapt these guidelines to what actually helps.",
   "additionalSections": []
 }

package/templates/minimal/files/AGENTS.md

@@ -35,6 +35,24 @@ Before starting work, understand project context:
 
 These help you understand what exists and what's in progress.
 
+
+## Essential Commands
+
+**Discovery:**
+- `lean-spec list` - See all specs
+- `lean-spec search "<query>"` - Find relevant specs
+
+**Viewing specs:**
+- `lean-spec view <spec>` - View a spec (formatted)
+- `lean-spec open <spec>` - Open spec in editor
+
+**Working with specs:**
+- `lean-spec create <name>` - Create a new spec
+- `lean-spec update <spec> --status <status>` - Update spec status
+
+**When in doubt:** Run `lean-spec --help` to see all available commands.
+
+
 ## Spec Frontmatter
 
 When creating or updating specs, add YAML frontmatter at the top:
@@ -59,18 +77,39 @@ lean-spec update <spec> --status in-progress
 ## Workflow
 
 1. **Check existing work** - Run `lean-spec board` or `lean-spec search`
-2. **Create or update spec** - Add frontmatter with `status` and `created`
-3. **Implement changes** - Keep spec in sync as you learn
-4. **Update status** - Mark progress: `draft` → `in-progress` → `complete`
-5. **Archive when done** - `lean-spec archive <spec>` moves to archive
+2. **Create or update spec** - Add frontmatter with `status` and `created` (status: `planned`)
+3. **Start implementation** - Mark `in-progress` BEFORE implementing what the spec describes
+4. **Implement changes** - Keep spec in sync as you learn
+5. **Complete implementation** - Mark `complete` AFTER implementing what the spec describes
+6. **Archive when done** - `lean-spec archive <spec>` moves to archive
+
+**Remember**: Status tracks implementation work, not spec document creation. Creating a spec = planning (stays `planned` until implementation starts).
+**CRITICAL - What "Work" Means:**
+- ❌ **NOT**: Creating/writing the spec document itself
+- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+- **Example**: Creating a spec for "API redesign" ≠ work complete
+  - Work = Actually redesigning the API as described in the spec
+  - Status `planned` until someone starts the redesign
+  - Status `in-progress` while redesigning
+  - Status `complete` after redesign is done
+
+**Status Update Triggers:**
+- ✅ **Before starting implementation** → `lean-spec update <spec> --status in-progress`
+- ✅ **After completing implementation** → `lean-spec update <spec> --status complete`
+- ✅ **If blocked or paused** → Update status and document why in spec
+- ❌ **NEVER mark spec complete just because you finished writing it**
 
 ## Quality Standards
 
-- Code is clear and maintainable
 - Tests cover critical paths
 - No unnecessary complexity
 - Documentation where needed (not everywhere)
+- Code is clear and maintainable
 - Specs stay in sync with implementation
+- **Status tracking is mandatory:**
+  - Mark spec as `in-progress` BEFORE starting work
+  - Mark spec as `complete` IMMEDIATELY after finishing
+  - Never leave specs with stale status
 
 ---
 

package/templates/standard/agents-config.json

@@ -1,12 +1,13 @@
 {
   "description": "Lightweight spec methodology for AI-powered development.",
-  "coreRules": "core-rules-base.md",
+  "coreRules": ["core-rules-base-additions.md", "core-rules-shared.md"],
   "whenToUse": "when-to-use-standard.md",
   "whenToUseEarly": true,
-  "discoveryCommands": "discovery-commands-standard.md",
+  "discoveryCommands": ["discovery-commands-shared.md", "discovery-commands-standard-additions.md"],
+  "essentialCommands": ["essential-commands-shared.md", "essential-commands-standard-additions.md"],
   "frontmatter": "frontmatter-standard.md",
-  "workflow": "workflow-standard-detailed.md",
-  "qualityStandards": "quality-standards-base.md",
+  "workflow": ["workflow-standard-detailed.md", "status-update-triggers.md"],
+  "qualityStandards": ["quality-standards-minimal-additions.md", "quality-standards-shared.md"],
   "closingNote": "**Remember**: LeanSpec is a mindset. Adapt these guidelines to what actually helps.",
   "additionalSections": []
 }

package/templates/standard/files/AGENTS.md

@@ -28,13 +28,49 @@ Skip specs for:
 
 Before starting work, understand project context:
 
-- `lean-spec stats` - See work distribution across specs
-- `lean-spec board` - View specs organized by status
+- `lean-spec stats` - See work distribution
+- `lean-spec board` - View specs by status
+- `lean-spec search "<query>"` - Find relevant work
+- `lean-spec list` - List all specs
+
+These help you understand what exists and what's in progress.
+**Additional commands:**
 - `lean-spec list --tag=<tag>` - Find specs by tag (e.g., `--tag=api`)
-- `lean-spec search "<query>"` - Full-text search across specs
 - `lean-spec deps <spec>` - Check dependencies before starting work
 
-These commands help you understand what exists, what's in progress, and what depends on what.
+## Essential Commands
+
+**Discovery:**
+- `lean-spec list` - See all specs
+- `lean-spec search "<query>"` - Find relevant specs
+
+**Viewing specs:**
+- `lean-spec view <spec>` - View a spec (formatted)
+- `lean-spec open <spec>` - Open spec in editor
+
+**Working with specs:**
+- `lean-spec create <name>` - Create a new spec
+- `lean-spec update <spec> --status <status>` - Update spec status
+
+**When in doubt:** Run `lean-spec --help` to see all available commands.
+**Viewing specs (additional):**
+- `lean-spec view <spec> --raw` - Get raw markdown
+- `lean-spec files <spec>` - List all files in a spec
+
+**Project Overview:**
+- `lean-spec board` - Kanban view with project health summary
+- `lean-spec stats` - Quick project metrics
+
+**Working with specs (additional):**
+- `lean-spec update <spec> --priority <priority>` - Update spec priority
+- `lean-spec update <spec> --tags <tag1,tag2>` - Update spec tags
+- `lean-spec deps <spec>` - Show dependencies and relationships
+
+**Token Management:**
+- `lean-spec tokens <spec>` - Count tokens in a spec
+- `lean-spec tokens` - Show token counts for all specs
+
+**When in doubt (extended):** Run `lean-spec <command> --help` to discover available commands.
 
 ## Spec Frontmatter
 
@@ -67,18 +103,39 @@ lean-spec update <spec> --status in-progress --assignee yourname
 1. **Discover context** - Run `lean-spec stats` or `lean-spec board` to see current state
 2. **Search existing specs** - Use `lean-spec search` or `lean-spec list` to find relevant work
 3. **Check dependencies** - Run `lean-spec deps <spec>` if working on existing spec
-4. **Create or update spec** - Add frontmatter with required fields and helpful metadata
-5. **Implement changes** - Keep spec in sync as you learn
-6. **Update status** - Mark progress: `draft` → `in-progress` → `complete`
-7. **Archive when done** - `lean-spec archive <spec>` moves to archive
+4. **Create or update spec** - Add frontmatter with required fields (status: `planned`)
+5. **Start implementation** - Mark `in-progress` BEFORE implementing what the spec describes
+6. **Implement changes** - Keep spec in sync as you learn
+7. **Complete implementation** - Mark `complete` AFTER implementing what the spec describes
+8. **Archive when done** - `lean-spec archive <spec>` moves to archive
+
+**Remember**: Status tracks implementation work, not spec document creation. Creating a spec = planning (stays `planned` until implementation starts).
+**CRITICAL - What "Work" Means:**
+- ❌ **NOT**: Creating/writing the spec document itself
+- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+- **Example**: Creating a spec for "API redesign" ≠ work complete
+  - Work = Actually redesigning the API as described in the spec
+  - Status `planned` until someone starts the redesign
+  - Status `in-progress` while redesigning
+  - Status `complete` after redesign is done
+
+**Status Update Triggers:**
+- ✅ **Before starting implementation** → `lean-spec update <spec> --status in-progress`
+- ✅ **After completing implementation** → `lean-spec update <spec> --status complete`
+- ✅ **If blocked or paused** → Update status and document why in spec
+- ❌ **NEVER mark spec complete just because you finished writing it**
 
 ## Quality Standards
 
-- Code is clear and maintainable
 - Tests cover critical paths
 - No unnecessary complexity
 - Documentation where needed (not everywhere)
+- Code is clear and maintainable
 - Specs stay in sync with implementation
+- **Status tracking is mandatory:**
+  - Mark spec as `in-progress` BEFORE starting work
+  - Mark spec as `complete` IMMEDIATELY after finishing
+  - Never leave specs with stale status
 
 ---