Merge pull request #75 from codervisor/copilot/implement-spec-118

docs: parallel spec development workflow with git worktrees

Author: tikazyq

.gitignore

@@ -14,4 +14,5 @@ tmp/
 .playwright-mcp/
 *.tsbuildinfo
 *.tgz
-GEMINI.md
+GEMINI.md
+.worktrees/

AGENTS.md

@@ -202,6 +202,38 @@ See [docs/agents/PUBLISHING.md](docs/agents/PUBLISHING.md) for the complete rele
 
 **How to split:** Use `lean-spec analyze <spec>`, `lean-spec split`, and `lean-spec compact` commands. See [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for detailed examples.
 
+## Parallel Development
+
+Need to work on multiple specs at once? Use Git worktrees for complete code isolation:
+
+```bash
+# Create worktree for spec 045
+lean-spec update 045 --status in-progress
+git worktree add .worktrees/spec-045-dashboard -b feature/045-dashboard
+cd .worktrees/spec-045-dashboard
+# Implement spec 045...
+
+# Meanwhile, start spec 047 in a separate worktree
+cd ~/project  # Back to main
+lean-spec update 047 --status in-progress
+git worktree add .worktrees/spec-047-timestamps -b feature/047-timestamps
+```
+
+**Best Practices:**
+- **Naming**: Use `spec-<number>-<short-name>` for worktrees
+- **Branches**: Feature branch per spec (`feature/045-dashboard`)
+- **Cleanup**: `git worktree remove <path>` after merge
+- **Status**: Update spec status from main worktree
+- **Ignore**: Add `.worktrees/` to `.gitignore`
+
+**Full guide:** See [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for complete patterns.
+
+## FAQ
+
+**Q: How do I work on multiple specs at once?**
+
+Use Git worktrees. Each worktree gives you an isolated working directory with its own branch while sharing the same Git history. See [Parallel Development](#parallel-development) above and [docs/agents/WORKFLOWS.md](docs/agents/WORKFLOWS.md) for detailed patterns.
+
 ---
 
 **Remember**: LeanSpec is a mindset, not a rulebook. When in doubt, apply the first principles in order: Context Economy → Signal-to-Noise → Intent Over Implementation → Bridge the Gap → Progressive Disclosure. Use `lean-spec --help` to discover features as needed.

docs/agents/WORKFLOWS.md

@@ -259,3 +259,104 @@ lean-spec link product-launch --depends-on dark-theme-support
 # View full dependency graph
 lean-spec deps product-launch --impact
 ```
+
+## Parallel Development with Git Worktrees
+
+Need to work on multiple specs simultaneously? Use Git worktrees for complete code isolation.
+
+### Why Git Worktrees?
+
+- **Native Git feature** - No additional tools required
+- **Complete isolation** - Each worktree has independent working directory
+- **Shared history** - Efficient disk usage, all worktrees share `.git`
+- **No context switching** - Work on multiple specs without stashing/committing
+
+### Basic Setup
+
+```bash
+# Main repo structure after creating worktrees:
+~/project/                    # Primary worktree (main branch)
+~/project/.worktrees/
+  ├── spec-045-dashboard/     # Worktree for spec 045
+  ├── spec-047-timestamps/    # Worktree for spec 047
+  └── spec-048-analysis/      # Worktree for spec 048
+```
+
+### Pattern 1: Solo Developer - Parallel Features
+
+```bash
+# Start spec 045
+lean-spec update 045 --status in-progress
+git worktree add .worktrees/spec-045-dashboard -b feature/045-dashboard
+cd .worktrees/spec-045-dashboard
+# Implement spec 045...
+
+# While 045 is ongoing, start spec 047 in parallel
+cd ~/project  # Back to main worktree
+lean-spec update 047 --status in-progress
+git worktree add .worktrees/spec-047-timestamps -b feature/047-timestamps
+cd .worktrees/spec-047-timestamps
+# Implement spec 047...
+
+# Work continues independently in each worktree
+# Merge and clean up when done:
+git worktree remove .worktrees/spec-045-dashboard
+```
+
+### Pattern 2: Team - Multiple Developers
+
+```bash
+# Developer A works on spec 045
+git worktree add .worktrees/spec-045 -b feature/045-dashboard
+cd .worktrees/spec-045
+lean-spec update 045 --status in-progress --assignee "dev-a"
+
+# Developer B works on spec 047 (from their clone)
+git worktree add .worktrees/spec-047 -b feature/047-timestamps
+cd .worktrees/spec-047
+lean-spec update 047 --status in-progress --assignee "dev-b"
+
+# Each developer has isolated environment
+# Merge to main when complete
+```
+
+### Pattern 3: Experiment + Stable Work
+
+```bash
+# Keep main worktree for stable/production work
+cd ~/project  # Main worktree on main branch
+
+# Create experimental worktree for risky spec
+git worktree add .worktrees/spec-048-experiment -b experiment/048
+cd .worktrees/spec-048-experiment
+# Try experimental approach...
+
+# If experiment fails, just remove worktree
+git worktree remove .worktrees/spec-048-experiment
+# Main work remains untouched
+```
+
+### Handling Dependencies
+
+When specs have dependencies (`depends_on`):
+
+```bash
+# Spec 048 depends on 045
+# Option 1: Wait for 045 to merge to main
+git worktree add .worktrees/spec-048 -b feature/048
+# Work on 048 after 045 is merged
+
+# Option 2: Branch from 045's feature branch (when 045 not yet merged)
+cd ~/project  # Back to main worktree
+git worktree add .worktrees/spec-048-analysis feature/045-dashboard -b feature/048-from-045
+# 048 includes all changes from 045's branch
+```
+
+### Best Practices
+
+1. **Worktree naming**: Use spec number + short name (e.g., `spec-045-dashboard`)
+2. **Branch strategy**: Feature branches per spec (e.g., `feature/045-dashboard`)
+3. **Cleanup**: Remove worktrees after merge (`git worktree remove <path>`)
+4. **Status updates**: Update spec status from main worktree where `specs/` lives
+5. **Dependencies**: Branch from dependent spec's feature branch if needed
+6. **Ignore worktrees**: Add `.worktrees/` to `.gitignore`

specs/118-parallel-spec-implementation/README.md

@@ -1,18 +1,25 @@
 ---
-status: planned
+status: complete
 created: '2025-11-25'
 tags:
   - workflow
   - documentation
   - git
 priority: high
 created_at: '2025-11-25T06:46:20.670Z'
-updated_at: '2025-11-25T06:47:19.875Z'
+updated_at: '2025-11-25T06:59:12.413Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-25T06:55:08.382Z'
+  - status: complete
+    at: '2025-11-25T06:59:12.413Z'
+completed_at: '2025-11-25T06:59:12.413Z'
+completed: '2025-11-25'
 ---
 
 # Parallel Spec Implementation Workflow
 
-> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-25 · **Tags**: workflow, documentation, git
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-25 · **Tags**: workflow, documentation, git
 
 **Project**: lean-spec  
 **Team**: Core Development