lean-spec 0.2.1 → 0.2.3

package/templates/_shared/agents-components/essential-commands-standard-additions.md

@@ -0,0 +1,18 @@
+**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.

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

@@ -0,0 +1,33 @@
+When creating or updating specs, include YAML frontmatter with all relevant fields:
+
+```yaml
+---
+status: draft|planned|in-progress|complete|blocked|cancelled
+created: YYYY-MM-DD
+tags: [security, api, compliance]  # for discovery
+priority: low|medium|high|critical
+assignee: username
+reviewer: reviewer-username  # required for review
+issue: JIRA-123  # link to issue tracker
+epic: EPIC-456  # link to epic
+compliance: [SOC2, GDPR, HIPAA]  # applicable standards
+depends_on:
+  - path/to/other/spec
+---
+```
+
+**Required fields:**
+- `status`, `created` - basic tracking
+- `tags`, `priority` - planning and discovery
+- `assignee`, `reviewer` - accountability
+- `compliance` - regulatory requirements (if applicable)
+
+**Integration fields:**
+- `issue`, `epic` - link to external systems
+- `depends_on` - explicit dependencies
+
+**Update with:**
+```bash
+lean-spec update <spec> --status in-progress --assignee yourname
+# or edit frontmatter directly
+```

package/templates/_shared/agents-components/frontmatter-minimal.md

@@ -0,0 +1,18 @@
+When creating or updating specs, add YAML frontmatter at the top:
+
+```yaml
+---
+status: draft|planned|in-progress|complete|blocked|cancelled
+created: YYYY-MM-DD
+---
+```
+
+**Keep it simple:**
+- Just `status` and `created` fields
+- Other fields are optional - only add if helpful
+- Update `status` as work progresses
+
+**Update status with:**
+```bash
+lean-spec update <spec> --status in-progress
+```

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

@@ -0,0 +1,23 @@
+When creating or updating specs, include YAML frontmatter at the top:
+
+```yaml
+---
+status: draft|planned|in-progress|complete|blocked|cancelled
+created: YYYY-MM-DD
+tags: [tag1, tag2]  # helps with discovery
+priority: low|medium|high  # helps with planning
+assignee: username  # for team coordination
+---
+```
+
+**Core fields:**
+- `status` and `created` are required
+- `tags` help with discovery and organization
+- `priority` helps teams plan work
+- `assignee` shows who's working on what
+
+**Update status with:**
+```bash
+lean-spec update <spec> --status in-progress --assignee yourname
+# or edit frontmatter directly
+```

package/templates/_shared/agents-components/quality-standards-enterprise-additions.md

@@ -0,0 +1,4 @@
+- Security requirements verified
+- Tests include security scenarios
+- Documentation complete
+- Compliance checklist completed

package/templates/_shared/agents-components/quality-standards-minimal-additions.md

@@ -0,0 +1,3 @@
+- Tests cover critical paths
+- No unnecessary complexity
+- Documentation where needed (not everywhere)

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/when-to-use-enterprise.md

@@ -0,0 +1,11 @@
+Required for:
+- Features touching PII or sensitive data
+- Changes to authentication/authorization
+- New external integrations
+- Breaking changes to APIs
+- Infrastructure changes
+
+Optional for:
+- Internal refactors
+- Bug fixes (unless security-related)
+- Minor UI changes

package/templates/_shared/agents-components/when-to-use-minimal.md

@@ -0,0 +1,9 @@
+- Features that affect multiple parts of the system
+- Breaking changes or significant refactors
+- Design decisions that need thinking through
+- Complex features that benefit from upfront planning
+
+Skip specs for:
+- Bug fixes
+- Trivial changes
+- Self-explanatory refactors

package/templates/_shared/agents-components/when-to-use-standard.md

@@ -0,0 +1,9 @@
+- Features that affect multiple parts of the system
+- Breaking changes or significant refactors
+- Design decisions that need team alignment
+- Complex features that benefit from upfront thinking
+
+Skip specs for:
+- Bug fixes
+- Trivial changes
+- Self-explanatory refactors

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

@@ -0,0 +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 (status: `planned`)
+5. **Get reviews** - Assign reviewer, tag for security review if needed
+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

@@ -0,0 +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 (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

@@ -0,0 +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` (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

@@ -0,0 +1,43 @@
+# AI Agent Instructions
+
+## Project: {{{project_name}}}
+
+{{{description}}}
+
+## Core Rules
+
+{{{coreRules}}}
+{{#if whenToUseEarly}}
+
+## When to Use Specs
+
+{{{whenToUse}}}
+{{/if}}
+
+## Discovery Commands
+
+{{{discoveryCommands}}}
+{{#if essentialCommands}}
+
+{{{essentialCommands}}}
+{{/if}}
+
+## Spec Frontmatter
+
+{{{frontmatter}}}
+{{#each additionalSections}}
+
+{{{this}}}
+{{/each}}
+
+## Workflow
+
+{{{workflow}}}
+
+## Quality Standards
+
+{{{qualityStandards}}}
+
+---
+
+{{{closingNote}}}

package/templates/enterprise/agents-config.json

@@ -0,0 +1,16 @@
+{
+  "description": "Enterprise-grade development with security and compliance requirements.",
+  "coreRules": ["core-rules-enterprise-additions.md", "core-rules-shared.md"],
+  "whenToUseEarly": false,
+  "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", "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",
+    "enterprise-when-required.md",
+    "enterprise-approval.md"
+  ]
+}

package/templates/enterprise/files/AGENTS.md

@@ -10,19 +10,69 @@ Enterprise-grade development with security and compliance requirements.
 2. **Read specs/** - Check for compliance requirements
 3. **Follow LeanSpec** - Lean doesn't mean skipping governance
 4. **Document decisions** - Especially security and compliance choices
+5. **Never use nested code blocks** - Markdown doesn't support code blocks within code blocks. Use indentation or describe the structure instead
 
 ## 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
 
@@ -103,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
 
@@ -117,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

@@ -0,0 +1,13 @@
+{
+  "description": "Lightweight spec methodology for AI-powered development.",
+  "coreRules": ["core-rules-base-additions.md", "core-rules-shared.md"],
+  "whenToUse": "when-to-use-minimal.md",
+  "whenToUseEarly": true,
+  "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", "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

@@ -10,6 +10,7 @@ Lightweight spec methodology for AI-powered development.
 2. **Check specs/** - Review existing specs before starting
 3. **Follow LeanSpec principles** - Clarity over documentation
 4. **Keep it minimal** - If it doesn't add clarity, cut it
+5. **Never use nested code blocks** - Markdown doesn't support code blocks within code blocks. Use indentation or describe the structure instead
 
 ## When to Use Specs
 
@@ -34,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:
@@ -58,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

@@ -0,0 +1,13 @@
+{
+  "description": "Lightweight spec methodology for AI-powered development.",
+  "coreRules": ["core-rules-base-additions.md", "core-rules-shared.md"],
+  "whenToUse": "when-to-use-standard.md",
+  "whenToUseEarly": true,
+  "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", "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

@@ -10,6 +10,7 @@ Lightweight spec methodology for AI-powered development.
 2. **Check specs/** - Review existing specs before starting
 3. **Follow LeanSpec principles** - Clarity over documentation
 4. **Keep it minimal** - If it doesn't add clarity, cut it
+5. **Never use nested code blocks** - Markdown doesn't support code blocks within code blocks. Use indentation or describe the structure instead
 
 ## When to Use Specs
 
@@ -27,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
 
@@ -66,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
 
 ---