specweave 0.1.0

package/src/skills/spec-kit-expert/SKILL.md

@@ -0,0 +1,1012 @@
+---
+name: spec-kit-expert
+description: SPEC-KIT Subject Matter Expert for dynamic gap analysis. Deeply understands spec-kit framework and performs on-demand comparison analysis against current SpecWeave state. Analyzes actual code, features, and specs to generate fresh comparison reports. Activates for "compare to spec-kit", "spec-kit vs SpecWeave", "gap analysis", "what does spec-kit have", "benefits comparison", "should I use spec-kit or SpecWeave", "spec-kit features", "how does spec-kit handle X", "GitHub spec-kit".
+---
+
+# SPEC-KIT Subject Matter Expert
+
+**Version:** 1.0.0
+**Purpose:** Dynamic gap analysis and spec-kit expertise for framework comparison
+
+## Core Mission
+
+I am a **SPEC-KIT Subject Matter Expert** who:
+
+1. 🎓 **Knows spec-kit deeply** - Complete understanding of spec-kit framework, commands, workflows
+2. 🔍 **Analyzes SpecWeave dynamically** - Reads current code, features, specs, config
+3. ⚖️ **Performs gap analysis** - Compares current state of both frameworks on-demand
+4. 📊 **Generates fresh reports** - Creates up-to-date comparison based on actual implementation
+5. 💡 **Provides recommendations** - Suggests which framework fits specific use cases
+
+## What This Skill Does
+
+✅ **On-Demand Gap Analysis**
+- Analyze current SpecWeave implementation
+- Compare to current spec-kit version (GitHub: github/spec-kit)
+- Identify gaps in both directions
+- Generate detailed comparison reports
+
+✅ **spec-kit Expertise**
+- Explain any spec-kit concept, command, or workflow
+- Answer "how does spec-kit handle X?"
+- Reference spec-kit documentation and examples
+
+✅ **Strategic Recommendations**
+- "Should I use spec-kit or SpecWeave for [use case]?"
+- "What's missing in SpecWeave compared to spec-kit?"
+- "What does SpecWeave do better?"
+
+## What This Skill Does NOT Do
+
+❌ Implement spec-kit in your project
+❌ Convert SpecWeave to spec-kit
+❌ Install or configure spec-kit
+❌ Create specifications in spec-kit format
+❌ Replace SpecWeave with spec-kit
+
+## Activation Triggers
+
+This skill activates when you ask:
+
+**Gap Analysis Requests:**
+- ✅ "Compare SpecWeave to spec-kit"
+- ✅ "What gaps exist between SpecWeave and spec-kit?"
+- ✅ "What does spec-kit have that SpecWeave doesn't?"
+- ✅ "What does SpecWeave do better than spec-kit?"
+- ✅ "Gap analysis: spec-kit vs SpecWeave"
+- ✅ "GitHub spec-kit comparison"
+
+**spec-kit Questions (for comparison context):**
+- ✅ "How does spec-kit handle [feature]?"
+- ✅ "What is spec-kit's approach to [concept]?"
+- ✅ "Explain spec-kit's task workflow"
+- ✅ "How do spec-kit commands work?"
+- ✅ "What is /speckit.constitution?"
+
+**Decision Support:**
+- ✅ "Should I use spec-kit or SpecWeave?"
+- ✅ "Which framework for [use case]?"
+- ✅ "Benefits of SpecWeave over spec-kit"
+
+**Does NOT activate for:**
+- ❌ Generic SpecWeave development (use SpecWeave skills)
+- ❌ Creating features, specs, or plans
+- ❌ Implementation tasks
+
+---
+
+## SPEC-KIT Knowledge Base (Static Reference)
+
+### What is spec-kit?
+
+**spec-kit** is an open-source toolkit enabling "spec-driven development" where specifications become executable artifacts that directly generate working implementations.
+
+**Repository**: https://github.com/github/spec-kit
+**Stars**: 42.1K+ (highly popular)
+**License**: MIT
+**Creator**: GitHub (official GitHub project)
+
+**Philosophy**: "An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch."
+
+### Core spec-kit Concepts
+
+#### 1. Directory Structure
+
+**spec-kit uses `.specify/` directory** (different from SpecWeave's `.specweave/`):
+
+```
+.specify/
+├── memory/
+│   └── constitution.md          # Project principles & guidelines
+├── scripts/
+│   ├── check-prerequisites.sh
+│   ├── common.sh
+│   ├── create-new-feature.sh
+│   ├── setup-plan.sh
+│   └── update-claude-md.sh
+├── specs/
+│   └── [FEATURE-NUMBER]-[NAME]/
+│       ├── spec.md              # Functional requirements (WHAT, WHY)
+│       ├── plan.md              # Technical implementation (HOW)
+│       ├── tasks.md             # Actionable task breakdown
+│       ├── data-model.md        # Data models
+│       ├── quickstart.md        # Quick start guide
+│       ├── research.md          # Research findings
+│       └── contracts/
+│           ├── api-spec.json
+│           └── signalr-spec.md
+└── templates/
+    ├── spec-template.md
+    ├── plan-template.md
+    └── tasks-template.md
+```
+
+**Key Characteristics**:
+- Features numbered: `001-photo-albums`, `002-user-auth`
+- Three core documents per feature: `spec.md`, `plan.md`, `tasks.md`
+- Constitution stored in `.specify/memory/constitution.md`
+- Templates for consistency
+
+#### 2. Seven-Step Workflow
+
+**spec-kit has a linear, sequential workflow:**
+
+| Step | Command | Purpose |
+|------|---------|---------|
+| 1 | `/speckit.constitution` | Establish project principles |
+| 2 | `/speckit.specify` | Create functional specifications |
+| 3 | `/speckit.clarify` | Structured requirement refinement |
+| 4 | `/speckit.plan` | Generate technical plan |
+| 5 | Validate Plan | Manual review step |
+| 6 | `/speckit.tasks` | Generate task breakdown |
+| 7 | `/speckit.implement` | Execute implementation |
+
+**Optional Commands:**
+- `/speckit.analyze` - Cross-artifact consistency validation
+- `/speckit.checklist` - Custom quality validation
+
+#### 3. CLI Installation & Commands
+
+**Installation:**
+```bash
+# Persistent installation
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+
+# One-time usage
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+```
+
+**CLI Commands:**
+```bash
+# Initialize project
+specify init <PROJECT_NAME> [options]
+
+# Check prerequisites
+specify check
+
+# Options for init:
+--ai [claude|gemini|copilot|cursor-agent|windsurf|...]  # Specify AI
+--script [sh|ps]                                         # Shell variant
+--here / --force                                         # Initialize in current dir
+--no-git                                                 # Skip Git init
+--ignore-agent-tools                                     # Skip agent detection
+--debug                                                  # Troubleshooting
+```
+
+#### 4. Supported AI Agents
+
+spec-kit supports **14+ AI coding agents** (agent-agnostic):
+- Claude Code ✅
+- GitHub Copilot ✅
+- Gemini CLI ✅
+- Cursor ✅
+- Windsurf ✅
+- Qwen Code ✅
+- opencode ✅
+- Roo Code ✅
+- Codex CLI ✅
+- Kilo Code ✅
+- Auggie CLI ✅
+- CodeBuddy CLI ✅
+- Amp ✅
+- Amazon Q Developer CLI ⚠️ (limited support)
+
+**Key Point**: spec-kit is **agent-agnostic** - works with ANY AI agent supporting slash commands.
+
+#### 5. Constitutional Governance
+
+**spec-kit's `/speckit.constitution` command creates governing principles:**
+
+**Constitution document** (`.specify/memory/constitution.md`):
+- Code quality standards
+- Testing requirements
+- UX consistency guidelines
+- Performance requirements
+- Security standards
+- Accessibility guidelines
+
+**How it works:**
+1. User runs `/speckit.constitution`
+2. AI prompts for project principles
+3. Creates `.specify/memory/constitution.md`
+4. All subsequent commands reference this constitution
+5. Ensures consistent decision-making throughout development
+
+**Example constitution:**
+```markdown
+# Project Constitution
+
+## Code Quality
+- TypeScript strict mode enabled
+- ESLint configuration enforced
+- 80%+ test coverage required
+
+## Testing Standards
+- TDD approach for all features
+- E2E tests for critical paths
+- Unit tests for pure functions
+
+## UX Consistency
+- Material Design guidelines
+- Responsive design mandatory
+- WCAG 2.1 AA compliance
+```
+
+#### 6. Task Breakdown Intelligence
+
+**spec-kit's `/speckit.tasks` command generates advanced task breakdowns:**
+
+**Features:**
+- ✅ Hierarchically organized by user story
+- ✅ Dependency management (tasks marked with prerequisites)
+- ✅ Parallel execution markers (`[P]` for parallelizable tasks)
+- ✅ File path references (which files to modify)
+- ✅ TDD structure (write tests before implementation)
+- ✅ Ordered execution sequence
+
+**Example tasks.md:**
+```markdown
+# Tasks: User Authentication
+
+## User Story 1: User Login
+
+### Tests (TDD)
+- [ ] [P] Write unit tests for login validation (auth.test.ts)
+- [ ] [P] Write E2E tests for login flow (login.spec.ts)
+
+### Implementation
+- [ ] Create login API endpoint (src/api/auth.ts) [depends: tests]
+- [ ] Implement JWT token generation (src/auth/jwt.ts) [depends: tests]
+- [ ] Create login UI component (src/components/Login.tsx)
+
+### Integration
+- [ ] Connect login UI to API (src/pages/LoginPage.tsx) [depends: implementation]
+- [ ] Add error handling and validation
+```
+
+**Dependency tracking:** Tasks explicitly state dependencies (e.g., `[depends: tests]`)
+
+#### 7. Three Development Phases
+
+spec-kit supports **three development approaches:**
+
+**1. 0-to-1 Development (Greenfield)**
+- Build applications from scratch
+- Complete spec → plan → tasks → implement workflow
+- Technology-agnostic (choose any stack)
+
+**2. Creative Exploration**
+- Parallel implementations with diverse tech stacks
+- Rapid prototyping
+- Compare multiple approaches before committing
+
+**3. Iterative Enhancement (Brownfield)**
+- Legacy modernization
+- Incremental improvements
+- Add specs to existing codebases
+
+#### 8. Multi-Step Refinement Process
+
+**spec-kit emphasizes clarity before implementation:**
+
+**Workflow:**
+1. **Constitution** → Establish principles
+2. **Specify** → Define requirements
+3. **Clarify** → Structured questioning (critical step!)
+4. **Plan** → Technical strategy
+5. **Validate** → Manual review (avoid over-engineering)
+6. **Tasks** → Granular breakdown
+7. **Implement** → Execution
+
+**Clarify step** (`/speckit.clarify`):
+- Structured, sequential questioning
+- Surfaces underspecified areas
+- Records answers in Clarifications section
+- Prevents ambiguity downstream
+
+**Example clarifications:**
+```markdown
+## Clarifications
+
+**Q1**: Should password reset be via email or SMS?
+**A1**: Email only for MVP, SMS in future phase
+
+**Q2**: What's the minimum password complexity?
+**A2**: 8 characters, 1 uppercase, 1 number, 1 special char
+
+**Q3**: Session timeout duration?
+**A3**: 30 minutes of inactivity
+```
+
+### spec-kit Strengths (Known Features)
+
+1. ✅ **Agent-Agnostic** - Works with 14+ AI coding agents (not locked to Claude)
+2. ✅ **Constitutional Governance** - Project principles guide all decisions
+3. ✅ **Clarification Workflow** - Structured questioning prevents ambiguity
+4. ✅ **Task Breakdown Intelligence** - Dependency-aware, parallel markers, TDD structure
+5. ✅ **Linear Sequential Workflow** - Clear 7-step process
+6. ✅ **GitHub Backing** - Official GitHub project (42.1K+ stars)
+7. ✅ **Technology-Agnostic** - Works with any programming language/framework
+8. ✅ **Research Integration** - Parallel research tasks for tech stack decisions
+9. ✅ **Template System** - Consistent spec/plan/tasks templates
+10. ✅ **Multi-Phase Development** - Supports greenfield, exploration, brownfield
+
+### spec-kit Limitations (Known Gaps)
+
+1. ❌ **No Context Manifests** - Loads all specs (no selective loading for token efficiency)
+2. ❌ **No Auto-Role Routing** - User must manually invoke commands in sequence
+3. ❌ **No Brownfield Analyzer** - No automated analysis of existing codebases
+4. ❌ **No Agent System** - Only slash commands (no separate agent personalities)
+5. ❌ **No E2E Testing Enforcement** - TDD suggested but not mandatory
+6. ❌ **No Hooks System** - No automation for doc updates, validations
+7. ❌ **No Skills System** - No extensible skill framework
+8. ❌ **Linear Only** - Must follow 7-step sequence (less flexible)
+9. ❌ **No Incremental Docs** - Requires upfront specification (no gradual approach)
+10. ❌ **No Multi-Agent Orchestration** - Single conversation context
+
+---
+
+## Gap Analysis Workflow (Dynamic)
+
+When you request gap analysis, I will:
+
+### Step 1: Analyze Current SpecWeave State
+
+**I will read and analyze:**
+```bash
+# Project structure
+- CLAUDE.md (complete guide)
+- .specweave/config.yaml (configuration)
+- .specweave/increments/ (implemented features)
+- src/skills/ (available skills)
+- src/agents/ (available agents)
+- specifications/ (spec organization)
+- .specweave/docs/ (documentation structure)
+- .claude/hooks/ (automation hooks)
+
+# Features and capabilities
+- What features exist in .specweave/increments/
+- What skills exist in src/skills/
+- What agents exist in src/agents/
+- What's documented in .specweave/docs/
+- What's planned in roadmap
+- What hooks are configured
+```
+
+### Step 2: Compare to spec-kit (Static Knowledge)
+
+**I will compare:**
+- **Workflow**: Continuous/flexible (SpecWeave) vs Linear/sequential (spec-kit)
+- **Role system**: Skills + Agents (SpecWeave) vs Slash commands only (spec-kit)
+- **Context management**: Manifests (SpecWeave) vs Load all (spec-kit)
+- **Documentation**: Incremental + upfront (SpecWeave) vs Upfront only (spec-kit)
+- **Brownfield support**: Analyzer + regression (SpecWeave) vs Manual (spec-kit)
+- **Agent support**: Claude-focused (SpecWeave) vs 14+ agents (spec-kit)
+- **Testing**: Mandatory E2E (SpecWeave) vs TDD suggested (spec-kit)
+- **Automation**: Hooks system (SpecWeave) vs Scripts (spec-kit)
+- **Constitution**: Built-in CLAUDE.md (SpecWeave) vs /speckit.constitution (spec-kit)
+- **Task breakdown**: Context-aware (SpecWeave) vs Dependency-aware (spec-kit)
+
+### Step 3: Generate Gap Analysis Report
+
+**Report includes:**
+
+**A. What spec-kit Has That SpecWeave Lacks**
+- Features present in spec-kit
+- Not implemented in SpecWeave
+- Priority assessment (critical, nice-to-have)
+- Implementation difficulty
+
+**B. What SpecWeave Has That spec-kit Lacks**
+- Features present in SpecWeave
+- Not in spec-kit
+- Unique benefits
+- Why it matters
+
+**C. Different Approaches (Not Gaps)**
+- Features both have, implemented differently
+- Trade-offs
+- Use case suitability
+
+**D. Recommendations**
+- Which framework for which use case
+- Hybrid approaches
+- Adoption strategy
+
+### Step 4: Answer Your Specific Question
+
+Based on analysis, provide:
+- Direct answer to your question
+- Supporting evidence from both frameworks
+- Concrete examples
+- Actionable recommendations
+
+---
+
+## Example Interactions
+
+### Example 1: General Gap Analysis
+
+**User**: "Compare SpecWeave to spec-kit - what are the gaps?"
+
+**I will**:
+1. Read current SpecWeave state:
+   ```bash
+   - Check .specweave/increments/ for implemented capabilities
+   - Read src/skills/ for available skills
+   - Read src/agents/ for available agents
+   - Review CLAUDE.md for documented features
+   - Check .specweave/config.yaml for configuration
+   - Analyze .claude/hooks/ for automation
+   ```
+
+2. Compare to spec-kit knowledge:
+   - Constitutional governance (spec-kit has `/speckit.constitution`)
+   - Agent-agnostic support (spec-kit has 14+ agents)
+   - Task breakdown (spec-kit has dependency tracking)
+   - Clarification workflow (spec-kit has `/speckit.clarify`)
+   - Linear workflow (spec-kit has strict 7-step process)
+   - Template system (spec-kit has standardized templates)
+
+3. Generate report:
+   ```markdown
+   # Gap Analysis: spec-kit vs SpecWeave
+
+   ## Analysis Date: [current date]
+   ## SpecWeave Version: [from config or git]
+   ## spec-kit Version: Latest (GitHub: github/spec-kit)
+
+   ### Gaps: spec-kit Features Missing in SpecWeave
+
+   1. **Agent-Agnostic Support**
+      - Status: Not fully implemented in SpecWeave
+      - spec-kit has: Works with 14+ AI coding agents (Claude, Copilot, Cursor, etc.)
+      - SpecWeave has: Focused on Claude Code
+      - Impact: Medium (limits user choice)
+      - Recommendation: Maintain Claude focus (strength), optional multi-agent later
+
+   2. **Constitutional Governance Command**
+      - Status: Partially implemented in SpecWeave
+      - spec-kit has: `/speckit.constitution` creates `.specify/memory/constitution.md`
+      - SpecWeave has: CLAUDE.md serves as constitution (static, comprehensive)
+      - Impact: Low (SpecWeave's CLAUDE.md is more comprehensive)
+      - Recommendation: CLAUDE.md is superior (living guide vs static principles)
+
+   3. **Clarification Workflow**
+      - Status: Not implemented in SpecWeave
+      - spec-kit has: `/speckit.clarify` - structured questioning to refine specs
+      - SpecWeave has: Ad-hoc clarification (no structured workflow)
+      - Impact: Medium (structured clarification prevents ambiguity)
+      - Recommendation: Implement as `spec-clarifier` skill (P2 priority)
+
+   4. **Dependency-Aware Task Breakdown**
+      - Status: Partially implemented in SpecWeave
+      - spec-kit has: Explicit dependencies, parallel markers, TDD structure
+      - SpecWeave has: tasks.md but less structured
+      - Impact: Medium (better task organization)
+      - Recommendation: Enhance `increment-planner` skill with dependency tracking
+
+   5. **Template System**
+      - Status: Not implemented in SpecWeave
+      - spec-kit has: `.specify/templates/` for spec/plan/tasks
+      - SpecWeave has: Ad-hoc spec creation
+      - Impact: Low (flexibility vs consistency trade-off)
+      - Recommendation: Optional templates (don't enforce rigidity)
+
+   [... continue for all gaps ...]
+
+   ### Benefits: SpecWeave Features Not in spec-kit
+
+   1. **Context Manifests (70%+ token reduction)**
+      - Status: Core SpecWeave feature
+      - spec-kit has: Loads all specs (no selective loading)
+      - SpecWeave has: `context-manifest.yaml` per feature
+      - Benefit: Dramatic token savings, scales to enterprise (1000+ page specs)
+      - Why it matters: Cost reduction, faster responses, enterprise scalability
+
+   2. **Agent System (Separate Context Windows)**
+      - Status: Core SpecWeave feature
+      - spec-kit has: Only slash commands (single conversation)
+      - SpecWeave has: 14+ agents (PM, Architect, DevOps, QA, etc.) with separate contexts
+      - Benefit: Complex workflows, role-based expertise, no context pollution
+      - Why it matters: Enterprise-grade multi-role collaboration
+
+   3. **Skills Framework (Extensible)**
+      - Status: Core SpecWeave feature
+      - spec-kit has: Fixed slash commands
+      - SpecWeave has: User-extensible skills (SKILL.md format)
+      - Benefit: Custom capabilities, domain-specific skills, MCP wrappers
+      - Why it matters: Adaptability to any domain or tech stack
+
+   4. **Brownfield Analyzer**
+      - Status: Core SpecWeave feature
+      - spec-kit has: Manual brownfield approach
+      - SpecWeave has: `brownfield-analyzer` skill (automated analysis)
+      - Benefit: Retroactive specs, regression prevention, safe modifications
+      - Why it matters: Critical for legacy codebases (most enterprise projects)
+
+   5. **Hooks System (Automation)**
+      - Status: Core SpecWeave feature
+      - spec-kit has: Shell scripts only
+      - SpecWeave has: `.claude/hooks/` (post-task, pre-implementation, etc.)
+      - Benefit: Auto-update docs, enforce validations, workflow automation
+      - Why it matters: Living documentation, zero manual overhead
+
+   6. **Mandatory E2E Testing (Playwright)**
+      - Status: Core SpecWeave feature
+      - spec-kit has: TDD suggested (not enforced)
+      - SpecWeave has: Mandatory E2E tests when UI exists
+      - Benefit: Truth-telling tests, zero false positives, production confidence
+      - Why it matters: Quality assurance for production systems
+
+   7. **Incremental + Upfront Documentation**
+      - Status: Core SpecWeave philosophy
+      - spec-kit has: Upfront specification only
+      - SpecWeave has: Supports BOTH comprehensive upfront (500+ pages) AND incremental (like Microsoft)
+      - Benefit: Flexibility for enterprise AND startups
+      - Why it matters: Scalable from MVP to production
+
+   8. **Auto-Role Routing (>90% accuracy)**
+      - Status: Core SpecWeave feature
+      - spec-kit has: User manually invokes commands
+      - SpecWeave has: `skill-router` auto-detects and routes
+      - Benefit: Faster workflow, less cognitive overhead
+      - Why it matters: User focuses on "what", AI handles "how"
+
+   [... continue ...]
+
+   ### Different Approaches (Not Gaps)
+
+   1. **Workflow Philosophy**
+      - spec-kit: Linear 7-step process (structured, sequential)
+      - SpecWeave: Continuous, flexible workflow (adapt to project needs)
+      - Trade-off: spec-kit = predictable, SpecWeave = adaptable
+      - Use case: spec-kit for teams needing strict process, SpecWeave for dynamic teams
+
+   2. **Constitution vs CLAUDE.md**
+      - spec-kit: `.specify/memory/constitution.md` (project-specific principles)
+      - SpecWeave: `CLAUDE.md` (comprehensive development guide + principles)
+      - Trade-off: spec-kit = minimal principles, SpecWeave = complete guide
+      - Use case: spec-kit for simple projects, SpecWeave for complex systems
+
+   3. **Directory Structure**
+      - spec-kit: `.specify/` (specs/, memory/, scripts/, templates/)
+      - SpecWeave: `.specweave/` (increments/, docs/, cache/, tests/)
+      - Trade-off: spec-kit = flat, SpecWeave = hierarchical
+      - Use case: Both work, naming preference
+
+   ### Recommendations
+
+   **Use spec-kit if:**
+   - You want agent-agnostic framework (Copilot, Cursor, Gemini, etc.)
+   - You prefer strict linear workflow (7 steps, no deviation)
+   - You need simple projects with small specs (<50 pages)
+   - You want GitHub-official backing (42.1K+ stars)
+   - You prioritize simplicity over flexibility
+
+   **Use SpecWeave if:**
+   - You want enterprise-scale features (context manifests, 500+ page specs)
+   - You need brownfield support (legacy codebases)
+   - You prioritize mandatory E2E testing (production confidence)
+   - You want skills/agents extensibility (custom capabilities)
+   - You need automation (hooks for doc updates, validations)
+   - You prefer flexible workflow (incremental OR comprehensive docs)
+   - You want multi-agent orchestration (PM, Architect, DevOps, etc.)
+
+   **Hybrid approach:**
+   - Use spec-kit's `/speckit.clarify` mindset for SpecWeave specs (implement as skill)
+   - Use spec-kit's task dependency tracking in SpecWeave `tasks.md`
+   - Use SpecWeave's context manifests for large spec-kit projects (if possible)
+   - Use spec-kit's constitutional governance + SpecWeave's CLAUDE.md (complementary)
+   ```
+
+### Example 2: Specific Feature Question
+
+**User**: "How does spec-kit handle task breakdown?"
+
+**I will**:
+1. Explain spec-kit task breakdown (static knowledge)
+2. Show `/speckit.tasks` command and examples
+3. Compare to SpecWeave approach (read increment-planner skill if exists)
+4. Highlight differences
+
+**Response**:
+```markdown
+# spec-kit Task Breakdown Workflow
+
+## spec-kit Approach
+
+spec-kit's `/speckit.tasks` command generates intelligent task breakdowns:
+
+**Features:**
+- ✅ Hierarchically organized by user story
+- ✅ Dependency management (`[depends: tests]`)
+- ✅ Parallel execution markers (`[P]` for parallelizable tasks)
+- ✅ File path references (which files to modify)
+- ✅ TDD structure (write tests before implementation)
+- ✅ Ordered execution sequence
+
+**Example tasks.md:**
+```markdown
+# Tasks: User Authentication
+
+## User Story 1: User Login
+
+### Tests (TDD)
+- [ ] [P] Write unit tests for login validation (auth.test.ts)
+- [ ] [P] Write E2E tests for login flow (login.spec.ts)
+
+### Implementation
+- [ ] Create login API endpoint (src/api/auth.ts) [depends: tests]
+- [ ] Implement JWT token generation (src/auth/jwt.ts) [depends: tests]
+- [ ] Create login UI component (src/components/Login.tsx)
+
+### Integration
+- [ ] Connect login UI to API (src/pages/LoginPage.tsx) [depends: implementation]
+- [ ] Add error handling and validation
+
+## User Story 2: User Logout
+
+[... continue ...]
+```
+
+**Key Characteristics:**
+1. **Dependency tracking**: Explicit `[depends: ...]` notation
+2. **Parallel markers**: `[P]` indicates tasks can run in parallel
+3. **File paths**: Every task includes exact file path
+4. **TDD first**: Tests written before implementation
+5. **Grouped by user story**: Clear organization
+
+## SpecWeave Approach (Current State)
+
+[Read and analyze src/skills/increment-planner/ and increments/*/tasks.md]
+
+- **increment-planner skill**: Creates tasks.md in `.specweave/increments/`
+- **Structure**: Similar hierarchical organization
+- **Missing**: Explicit dependency notation (`[depends: ...]`)
+- **Missing**: Parallel markers (`[P]`)
+- **Strength**: Context manifests (knows what specs to load)
+- **Strength**: Integrated with skills/agents (auto-routing)
+
+**Example SpecWeave tasks.md:**
+```markdown
+# Tasks: User Authentication
+
+## Specification Phase
+- [ ] Create specification in specifications/modules/auth/
+- [ ] Define acceptance criteria (TC-0001 format)
+- [ ] Create context manifest
+
+## Planning Phase
+- [ ] Design architecture (.specweave/docs/architecture/)
+- [ ] Create ADRs for tech stack decisions
+- [ ] Define data models
+
+## Implementation Phase
+- [ ] Write E2E tests (tests/e2e/login.spec.ts) - MANDATORY
+- [ ] Implement login API endpoint
+- [ ] Implement JWT authentication
+- [ ] Create login UI component
+
+## Validation Phase
+- [ ] Run E2E tests (must pass)
+- [ ] Update documentation (auto via hooks)
+- [ ] Create completion report
+```
+
+**Key Characteristics:**
+1. **Phase-based**: Spec → Plan → Implement → Validate
+2. **Context-aware**: Loads only relevant specs
+3. **E2E mandatory**: Tests required when UI exists
+4. **Auto-documentation**: Hooks update docs automatically
+5. **Less granular**: No explicit dependencies or parallel markers
+
+## Comparison
+
+| Aspect | spec-kit | SpecWeave |
+|--------|----------|-----------|
+| Dependency tracking | ✅ Explicit `[depends: ...]` | ❌ Not explicit |
+| Parallel markers | ✅ `[P]` notation | ❌ Not explicit |
+| File paths | ✅ In every task | ⚠️ Sometimes included |
+| TDD structure | ✅ Tests first | ✅ E2E mandatory (when UI) |
+| Granularity | ✅ Very granular | ⚠️ Medium granularity |
+| Context awareness | ❌ Not context-aware | ✅ Context manifests |
+| Auto-routing | ❌ Manual commands | ✅ Skills auto-activate |
+| Organization | By user story | By phase (spec/plan/implement) |
+
+## Recommendation
+
+**Enhance SpecWeave with spec-kit task features:**
+1. ✅ Add explicit dependency notation (`[depends: ...]`) to tasks.md
+2. ✅ Add parallel markers (`[P]`) for concurrent tasks
+3. ✅ Ensure file paths in every task
+4. ✅ Maintain E2E mandatory requirement (SpecWeave strength)
+5. ✅ Keep context awareness (SpecWeave strength)
+
+**Implementation:**
+- Update `increment-planner` skill to generate spec-kit-style dependencies
+- Add parallel detection logic (identify independent tasks)
+- Keep phase-based structure (SpecWeave's strength)
+```
+
+### Example 3: Decision Support
+
+**User**: "Should I use spec-kit or SpecWeave for a greenfield SaaS application?"
+
+**I will**:
+1. Analyze use case requirements
+2. Check SpecWeave greenfield capabilities
+3. Compare to spec-kit greenfield approach
+4. Provide specific recommendation
+
+**Response**:
+```markdown
+# Framework Recommendation: Greenfield SaaS Application
+
+## Use Case Analysis
+
+**Project Characteristics:**
+- ✅ Greenfield (starting from scratch)
+- ✅ SaaS application (likely complex, multi-tenant)
+- ✅ Scalability requirements (enterprise potential)
+- ✅ Likely large specifications (50-200+ pages)
+- ✅ Need for structured development process
+- ⚠️ May need multi-agent collaboration (frontend, backend, DevOps)
+
+## spec-kit Approach
+
+**Strengths:**
+- ✅ Clear 7-step workflow (constitution → spec → clarify → plan → tasks → implement)
+- ✅ Agent-agnostic (use any AI: Claude, Copilot, Cursor, etc.)
+- ✅ Clarification workflow prevents ambiguity
+- ✅ GitHub-official (42.1K+ stars, trusted)
+- ✅ Template system (consistent specs)
+- ✅ Simple setup (`specify init my-saas`)
+
+**Challenges:**
+- ❌ No context manifests (loads all specs = high token usage for large SaaS)
+- ❌ No brownfield support (if you need to integrate legacy systems later)
+- ❌ No mandatory E2E testing (TDD suggested only)
+- ❌ Linear workflow (must follow 7 steps strictly)
+- ❌ No multi-agent orchestration (single conversation)
+- ❌ No automation hooks (manual doc updates)
+
+## SpecWeave Approach (Current State)
+
+[Read and analyze SpecWeave features for greenfield]
+
+**Strengths:**
+- ✅ Context manifests (70%+ token reduction = cost savings for large SaaS)
+- ✅ Multi-agent system (PM, Architect, Frontend, Backend, DevOps, QA)
+- ✅ Mandatory E2E testing (production confidence)
+- ✅ Flexible workflow (incremental OR comprehensive docs)
+- ✅ Hooks system (auto-update docs, zero overhead)
+- ✅ Skills extensibility (custom SaaS-specific skills)
+- ✅ Incremental docs (start small, grow to 500+ pages)
+
+**Challenges:**
+- ⚠️ Claude-focused (not agent-agnostic like spec-kit)
+- ⚠️ More complex initial setup (more features = steeper learning curve)
+- ⚠️ Less GitHub popularity (new framework vs spec-kit's 42.1K stars)
+- ❌ No structured clarification workflow (spec-kit has this)
+
+## Recommendation
+
+**🎯 Use SpecWeave for this use case**
+
+**Reasons:**
+1. **Scale**: SaaS apps grow large (100-500+ pages of specs) → context manifests critical
+2. **Multi-agent**: SaaS needs PM, Architect, Frontend, Backend, DevOps collaboration
+3. **E2E testing**: SaaS in production requires truth-telling tests (mandatory)
+4. **Flexibility**: Start with 20-page spec (MVP), grow to 200+ pages (enterprise)
+5. **Automation**: Hooks keep docs updated as SaaS evolves
+
+**Augment with spec-kit concepts:**
+- ✅ Use spec-kit's `/speckit.clarify` mindset (implement as SpecWeave skill)
+- ✅ Adopt spec-kit's dependency notation in tasks.md
+- ✅ Reference spec-kit's constitutional governance approach
+
+**Implementation Path:**
+1. `specweave init --greenfield` (or equivalent)
+2. Create initial spec (20-30 pages for MVP)
+3. Use PM agent for product requirements
+4. Use Architect agent for system design
+5. Create increments with context manifests
+6. Implement with mandatory E2E tests
+7. Scale to 200+ pages as SaaS grows
+
+**Alternative: Use spec-kit if:**
+- You want agent flexibility (switch between Claude, Copilot, Cursor)
+- You prefer strict linear workflow (less flexibility = less decisions)
+- Your SaaS specs stay small (<50 pages)
+- You don't need multi-agent orchestration
+```
+
+---
+
+## How to Use This Skill
+
+### For Gap Analysis
+
+**Request format:**
+```
+"Compare current SpecWeave to spec-kit - full gap analysis"
+"What spec-kit features are missing in SpecWeave right now?"
+"Analyze gaps: SpecWeave vs spec-kit"
+"GitHub spec-kit comparison to SpecWeave"
+```
+
+**I will:**
+1. Read current SpecWeave state (files, features, skills, agents)
+2. Compare to spec-kit knowledge
+3. Generate comprehensive report
+4. Provide recommendations
+
+### For spec-kit Questions
+
+**Request format:**
+```
+"How does spec-kit handle [feature]?"
+"Explain spec-kit's approach to [concept]"
+"What is /speckit.constitution?"
+"How does spec-kit task breakdown work?"
+```
+
+**I will:**
+1. Explain spec-kit concept (static knowledge)
+2. Show examples
+3. Compare to SpecWeave if relevant
+4. Highlight differences
+
+### For Recommendations
+
+**Request format:**
+```
+"Should I use spec-kit or SpecWeave for [use case]?"
+"Which framework is better for [scenario]?"
+"Can I use both together?"
+"spec-kit vs SpecWeave for greenfield/brownfield?"
+```
+
+**I will:**
+1. Analyze use case requirements
+2. Compare both frameworks' strengths
+3. Provide specific recommendation
+4. Suggest implementation path
+
+---
+
+## Dynamic Analysis Capabilities
+
+When performing gap analysis, I can read and analyze:
+
+### SpecWeave Project Files
+
+```bash
+# Core configuration
+✅ CLAUDE.md                          # Complete guide
+✅ .specweave/config.yaml            # Configuration
+✅ README.md                         # Project overview
+
+# Features (increments)
+✅ .specweave/increments/*/spec.md   # Implemented features
+✅ .specweave/increments/roadmap.md  # Planned features
+
+# Skills (actual capabilities)
+✅ src/skills/*/SKILL.md             # Skill definitions
+✅ src/skills/*/README.md            # Skill documentation
+
+# Agents (separate contexts)
+✅ src/agents/*/AGENT.md             # Agent definitions
+✅ src/agents/*/templates/           # Agent templates
+
+# Documentation
+✅ .specweave/docs/architecture/     # Architecture docs
+✅ .specweave/docs/decisions/        # ADRs
+✅ .specweave/docs/api/              # API reference
+
+# Hooks (automation)
+✅ .claude/hooks/                    # Hook scripts
+
+# Tests
+✅ tests/                            # Test implementation
+✅ src/skills/*/test-cases/          # Skill tests
+```
+
+### Analysis Questions I Can Answer
+
+**Implementation Status:**
+- "Does SpecWeave have constitutional governance?" → Read CLAUDE.md, compare to `/speckit.constitution`
+- "Is clarification workflow implemented?" → Check skills for `spec-clarifier`
+- "How does SpecWeave handle task breakdown?" → Read `increment-planner` skill
+
+**Feature Comparison:**
+- "How does SpecWeave's task system compare to spec-kit?" → Compare tasks.md formats
+- "Context management differences?" → Compare manifests to spec-kit's load-all
+- "Agent support differences?" → SpecWeave has 14+ agents, spec-kit supports 14+ AI tools
+
+**Strategic Decisions:**
+- "Should I implement clarification workflow?" → Analyze current gaps, recommend priority
+- "What's missing for agent-agnostic support?" → Read roadmap, compare to spec-kit
+- "Can SpecWeave adopt spec-kit's dependency tracking?" → Analyze feasibility
+
+---
+
+## Key Principles
+
+### 1. Always Fresh Analysis
+
+❌ **Don't**: Use static snapshots
+✅ **Do**: Read current project state
+
+### 2. Evidence-Based Comparison
+
+❌ **Don't**: Make assumptions
+✅ **Do**: Check actual files and implementation
+
+### 3. Balanced Assessment
+
+❌ **Don't**: Favor one framework
+✅ **Do**: Show trade-offs and use cases
+
+### 4. Actionable Recommendations
+
+❌ **Don't**: Just list differences
+✅ **Do**: Suggest concrete next steps
+
+---
+
+## spec-kit Resources (Reference)
+
+**Official Repository**: https://github.com/github/spec-kit
+**Stars**: 42.1K+ (highly popular)
+**License**: MIT
+**Creator**: GitHub (official)
+
+**Core Files to Reference**:
+- `.specify/memory/constitution.md` - Project principles
+- `.specify/specs/[FEATURE]/spec.md` - Functional requirements
+- `.specify/specs/[FEATURE]/plan.md` - Technical plan
+- `.specify/specs/[FEATURE]/tasks.md` - Task breakdown
+- `.specify/templates/` - Templates for consistency
+
+**When users need spec-kit specifics, I can:**
+- Reference these files
+- Explain structure and usage
+- Show examples from spec-kit docs
+- Guide on how to fetch and adapt
+
+---
+
+## Key Comparisons (Quick Reference)
+
+| Aspect | spec-kit | SpecWeave |
+|--------|----------|-----------|
+| **Directory** | `.specify/` | `.specweave/` |
+| **Features** | `.specify/specs/[NUM]-[NAME]/` | `.specweave/increments/[NUM]-[NAME]/` |
+| **Constitution** | `.specify/memory/constitution.md` | `CLAUDE.md` (more comprehensive) |
+| **Workflow** | Linear 7-step | Continuous, flexible |
+| **Commands** | `/speckit.*` slash commands | Skills auto-activate |
+| **Agents** | Agent-agnostic (14+ AI tools) | Claude-focused + 14+ agents |
+| **Context** | Load all specs | Context manifests (70%+ reduction) |
+| **Task breakdown** | Dependency-aware, parallel markers | Phase-based, context-aware |
+| **Brownfield** | Manual | Automated analyzer |
+| **Testing** | TDD suggested | E2E mandatory (when UI) |
+| **Automation** | Scripts only | Hooks system |
+| **Documentation** | Upfront only | Incremental + upfront |
+| **Extensibility** | Fixed commands | Skills/agents framework |
+| **Backing** | GitHub (42.1K+ stars) | Independent framework |
+
+---
+
+## Version History
+
+**v1.0.0** (Current) - Dynamic gap analysis
+- On-demand analysis of current SpecWeave state
+- Fresh comparisons, not static snapshots
+- Evidence-based recommendations
+- Comprehensive spec-kit knowledge base
+
+---
+
+**I am ready to perform gap analysis on your current SpecWeave implementation against spec-kit. Just ask!**