refactor(config): update spec template structure and improve frontmatter guidelines

Author: Marvin Zhang

.lspec/config.json

@@ -2,7 +2,8 @@
   "template": "spec-template.md",
   "specsDir": "specs",
   "structure": {
-    "pattern": "{date}/{seq}-{name}/",
+    "pattern": "flat",
+    "prefix": "",
     "dateFormat": "YYYYMMDD",
     "sequenceDigits": 3,
     "defaultFile": "README.md"

.lspec/templates/spec-template.md

@@ -1,93 +1,42 @@
 ---
 status: planned
-created: { date }
+created: '{date}'
 tags: []
 priority: medium
 ---
 
 # {name}
 
-**Status**: 📅 Planned  
-**Created**: {date}  
-**Spec**: `{spec_path}`  
-**Priority**: Medium
-
----
+> **Status**: {status} · **Priority**: {priority} · **Created**: {date}
 
 ## Overview
 
-<!-- What problem are we solving? Why is this important now? -->
-
-<!-- Example:
-Brief description of the feature/fix/improvement and its value. Keep it concise - 2-3 paragraphs max.
--->
-
-## Problem Statement / Current State
-
-<!-- What's not working? What gaps exist? What are the pain points? -->
-
-<!-- Example:
-- ❌ Issue 1: Description
-- ❌ Issue 2: Description
-- ❌ Issue 3: Description
-
-Optionally include metrics, user feedback, or concrete examples.
--->
-
-## Objectives
-
-<!-- What are the key goals? What success looks like? -->
-
-1. **Objective 1** - What we'll achieve
-2. **Objective 2** - What we'll achieve
-3. **Objective 3** - What we'll achieve
+<!-- What are we solving? Why now? -->
 
 ## Design
 
-<!-- Technical approach and architecture decisions -->
-
-<!-- Example:
-For simple specs, describe directly here.
-For complex specs, reference separate design.md:
-  See **[design.md](./design.md)** for complete technical design.
--->
-
-## Implementation Plan
-
-<!-- Phased approach or task breakdown -->
-
-<!-- Example:
-For simple specs, list tasks directly here:
-  - [ ] Task 1
-  - [ ] Task 2
-  - [ ] Task 3
-
-For complex specs, reference separate implementation.md:
-  See **[implementation.md](./implementation.md)** for detailed task breakdown.
--->
-
-## Success Criteria
+<!-- Technical approach, architecture decisions -->
 
-<!-- How will we know this is done? What metrics validate success? -->
+## Plan
 
-- [ ] Criterion 1
-- [ ] Criterion 2
-- [ ] Criterion 3
+<!-- Break down implementation into steps -->
 
-## Timeline
+<!-- 💡 TIP: If your plan has >6 phases or this spec approaches
+     400 lines, consider using sub-spec files:
+     - IMPLEMENTATION.md for detailed implementation
+     - See spec 012-sub-spec-files for guidance on splitting -->
 
-<!-- Optional: Estimated effort, phases, deadlines -->
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
 
-**Estimated Effort**: [hours/days/weeks]
+## Test
 
-<!-- Example for phased work:
-- Phase 1: Description (Week 1)
-- Phase 2: Description (Week 2)
--->
+<!-- How will we verify this works? -->
 
-## References
+- [ ] Test criteria 1
+- [ ] Test criteria 2
 
-<!-- Optional: Related specs, docs, external resources -->
+## Notes
 
-- [Related Spec](../path/to/spec)
-- [Documentation](../../../docs/something.md)
+<!-- Optional: Research findings, alternatives considered, open questions -->

AGENTS.md

@@ -53,6 +53,7 @@
 **Create specs for:**
 
 - Features requiring design/planning (>2 days work)
+- Features that affect multiple parts of the system
 - Architectural decisions affecting multiple components
 - Breaking changes or significant refactors
 - Design decisions needing team alignment
@@ -101,42 +102,42 @@ lspec search "<query>"
 lspec deps <spec>
 ```
 
+These commands help you understand what exists, what's in progress, and what depends on what.
+
 ### Spec Frontmatter
 
 Include YAML frontmatter at the top of spec markdown files:
 
 ```yaml
 ---
-status: draft|planned|in-progress|complete|blocked|cancelled
+status: planned|in-progress|complete
 created: YYYY-MM-DD
-tags: [tag1, tag2]
-priority: low|medium|high
-assignee: username
+tags: [tag1, tag2] # helps with discovery
+priority: low|medium|high # helps with planning
+assignee: username # for team coordination
 ---
 ```
 
 **Required fields**: `status`, `created`  
 **Helpful fields**: `tags` (discovery), `priority` (planning), `assignee` (coordination)
 
-### Workflow
-
-1. **Discover** - `lspec stats` or `lspec board` to see current state
-2. **Search** - `lspec search` or `lspec list` to find relevant work
-3. **Check dependencies** - `lspec deps <spec>` if working on existing spec
-4. **Create/update spec** - Add frontmatter with required fields
-5. **Implement** - Keep spec in sync as you learn
-6. **Update status** - Mark progress: `draft` → `in-progress` → `complete`
-7. **Archive** - `lspec archive <spec>` when done
-
-### Update Commands
+**Update status with:**
 
 ```bash
-# Update spec status
 lspec update <spec> --status in-progress --assignee yourname
-
-# Or edit frontmatter directly in the markdown file
+# or edit frontmatter directly
 ```
 
+### Workflow
+
+1. **Discover context** - Run `lspec stats` or `lspec board` to see current state
+2. **Search existing specs** - Use `lspec search` or `lspec list` to find relevant work
+3. **Check dependencies** - Run `lspec 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** - `lspec archive <spec>` moves to archive
+
 ### Spec Content (Recommended Structure)
 
 Not mandatory, but helpful:
@@ -153,7 +154,3 @@ Not mandatory, but helpful:
 - No unnecessary complexity
 - Documentation where needed (not everywhere)
 - Specs stay in sync with implementation
-
----
-
-**Remember**: LeanSpec is a mindset. Adapt these guidelines to what actually helps.