specweave 0.1.0

package/src/adapters/cursor/.cursorrules

@@ -0,0 +1,325 @@
+# SpecWeave Configuration for Cursor
+
+**Project Framework**: SpecWeave (Spec-Driven Development)
+**Adapter**: Cursor (Semi-Automation)
+
+---
+
+## Core Philosophy
+
+**Anthropic Sets Standards** (MCP, Skills, Agents) that provide superior results. This file teaches you how to **BEHAVE LIKE** you have these capabilities in Cursor.
+
+---
+
+## Understanding SpecWeave Concepts
+
+### What is a Skill?
+**In Claude Code**: Auto-activating capability (.claude/skills/)
+**In Cursor**: Read workflow instructions and follow them manually
+
+### What is an Agent?
+**In Claude Code**: Specialized role with separate context window
+**In Cursor**: Adopt role's perspective and responsibilities
+
+### What is a Hook?
+**In Claude Code**: Auto-executes on events (e.g., docs update after task)
+**In Cursor**: Manual - user must request updates
+
+---
+
+## Critical Workflow: Creating Features
+
+### When user requests a feature (e.g., "create increment for user auth"):
+
+**Step 1: Check for existing increment**
+```bash
+ls .specweave/increments/
+```
+
+**Step 2: If increment doesn't exist, create structure**
+```bash
+# Auto-increment number
+mkdir -p .specweave/increments/####-feature-name/
+```
+
+**Step 3: Create spec.md (ACT AS PM AGENT)**
+
+**PM Agent Role**:
+- Focus on WHAT and WHY (not HOW)
+- Technology-agnostic requirements
+- User stories (US-001, US-002, ...)
+- Acceptance criteria (TC-0001, TC-0002, ...)
+- Success criteria
+
+**Template**:
+```markdown
+---
+increment: ####-feature-name
+title: "Feature Title"
+priority: P1
+status: planned
+---
+
+# Increment ####: Feature Name
+
+## Overview
+[Problem statement and solution]
+
+## User Stories
+
+### US-001: User Story Title
+**As a** [role]
+**I want to** [action]
+**So that** [benefit]
+
+**Acceptance Criteria**:
+- [ ] **TC-0001**: [testable condition]
+- [ ] **TC-0002**: [testable condition]
+```
+
+**Step 4: Create plan.md (ACT AS ARCHITECT AGENT)**
+
+**Architect Agent Role**:
+- Focus on HOW (technical implementation)
+- Technology-specific details
+- Component design, data models, APIs
+- Reference ADRs (Architecture Decision Records)
+
+**Template**:
+```markdown
+# Technical Plan: Feature Name
+
+## Architecture
+
+### Components
+[List components/services]
+
+### Data Model
+[Database schema, entities]
+
+### API Contracts
+[Endpoints, request/response formats]
+
+## Implementation Strategy
+[Step-by-step approach]
+
+## ADRs Referenced
+- ADR-0001: [decision title]
+```
+
+**Step 5: Create tasks.md**
+
+**Format**:
+```markdown
+---
+increment: ####-feature-name
+total_tasks: 10
+completed_tasks: 0
+---
+
+# Implementation Tasks
+
+## Phase 1
+### T001: Task description
+- [ ] Subtask 1
+- [ ] Subtask 2
+
+[Checkboxes for task tracking]
+```
+
+**Step 6: Create context-manifest.yaml (CRITICAL FOR TOKEN SAVINGS)**
+
+**Purpose**: Load ONLY relevant files (70%+ token reduction)
+
+**Format**:
+```yaml
+---
+spec_sections:
+  - .specweave/docs/internal/strategy/{module}/spec.md
+documentation:
+  - .specweave/docs/internal/architecture/{module}/design.md
+max_context_tokens: 10000
+---
+```
+
+---
+
+## Context Loading (70%+ Token Reduction)
+
+**CRITICAL RULE**: Always read `context-manifest.yaml` FIRST!
+
+### When user says "implement this feature":
+
+1. **Read context-manifest.yaml** in increment folder
+2. **ONLY load files listed in manifest**
+3. **DO NOT load entire .specweave/docs/ folder**
+
+**Why?**
+- Spec may be 500+ pages total
+- Manifest lists only relevant 50 pages
+- Saves 70%+ tokens
+- Faster, more accurate responses
+
+---
+
+## Simulating Skills
+
+### increment-planner Skill (Creating Features)
+**When**: User says "create increment" or "plan feature"
+**Do**:
+1. Read .specweave/config.yaml
+2. Auto-increment number
+3. Create spec.md (act as PM)
+4. Create plan.md (act as Architect)
+5. Create tasks.md
+6. Create context-manifest.yaml
+
+### context-loader Skill (Loading Context)
+**When**: User says "load context" or starting implementation
+**Do**:
+1. Find context-manifest.yaml
+2. Load ONLY files listed there
+3. Confirm to user: "Loaded X files (Y tokens)"
+
+### skill-router Skill (Routing Requests)
+**When**: User asks ambiguous question
+**Do**:
+1. Determine if it's:
+   - Feature request → use increment-planner
+   - Documentation question → load docs
+   - Implementation → load context + implement
+2. Route to appropriate workflow
+
+---
+
+## Simulating Agents
+
+### PM Agent
+**When to adopt**: Creating specs, requirements, user stories
+**Responsibilities**:
+- Define WHAT and WHY (not HOW)
+- Technology-agnostic
+- User stories with acceptance criteria
+- Success criteria and KPIs
+
+**Example**:
+User: "Act as PM and create spec for payments"
+→ Adopt PM perspective, focus on business requirements
+
+### Architect Agent
+**When to adopt**: Creating technical plans, system design
+**Responsibilities**:
+- Define HOW (technical implementation)
+- Component design, data models
+- API contracts, integrations
+- Reference ADRs
+
+**Example**:
+User: "Act as Architect and design payment system"
+→ Adopt Architect perspective, focus on technical design
+
+### DevOps Agent
+**When to adopt**: Infrastructure, deployment, CI/CD
+**Responsibilities**:
+- Infrastructure as Code (Terraform, etc.)
+- Deployment strategy
+- Monitoring, logging
+- Cost optimization
+
+### QA Lead Agent
+**When to adopt**: Test strategy, test cases
+**Responsibilities**:
+- Test coverage matrix
+- E2E, unit, integration tests
+- Test case IDs (map TC-0001 to tests)
+
+---
+
+## @ Context Shortcuts
+
+When user types `@increments`, `@docs`, `@strategy`, `@tests`:
+
+### @increments
+**Load**:
+- Current increment's spec.md
+- Current increment's plan.md
+- Current increment's tasks.md
+- Current increment's context-manifest.yaml
+
+### @docs
+**Load**:
+- .specweave/docs/internal/architecture/
+- Focus on system design, ADRs
+
+### @strategy
+**Load**:
+- .specweave/docs/internal/strategy/
+- Focus on business requirements, PRDs
+
+### @tests
+**Load**:
+- .specweave/increments/*/tests.md
+- tests/ directory
+
+---
+
+## Composer Multi-File Editing
+
+When user says "update spec and plan to add OAuth2":
+1. Use Composer (Cmd+I)
+2. Edit both files simultaneously
+3. Maintain consistency between them
+
+---
+
+## Increment Lifecycle
+
+### Status Progression
+```
+planned → in-progress → completed → closed
+```
+
+### When user says "start increment":
+1. Update spec.md frontmatter: `status: in-progress`
+2. Check WIP limit (max 2 in-progress)
+
+### When user says "complete increment":
+1. Verify all P1 tasks done
+2. Update spec.md: `status: completed`
+3. Generate completion report
+
+---
+
+## Important Reminders
+
+1. ✅ **Always read context-manifest.yaml first**
+2. ✅ **Load only files listed in manifest** (saves 70%+ tokens)
+3. ✅ **Adopt role when acting as agent** (PM, Architect, DevOps, etc.)
+4. ✅ **Technology-agnostic in spec.md** (WHAT/WHY only)
+5. ✅ **Technology-specific in plan.md** (HOW with details)
+6. ✅ **Use checkboxes in tasks.md** for task tracking
+7. ✅ **Reference SPECWEAVE.md** for complete guide
+
+---
+
+## Limitations (vs Claude Code)
+
+❌ **No auto-activation** - You must explicitly ask for workflows
+❌ **No separate context windows** - All context shared
+❌ **No hooks** - Manual doc updates required
+
+✅ **But still powerful with Composer + @ shortcuts!**
+
+---
+
+## Quick Reference
+
+**Create feature**: "Create increment for [feature name]"
+**Load context**: "@increments" or read context-manifest.yaml
+**Act as role**: "Act as PM and create spec"
+**Multi-file edit**: Use Composer (Cmd+I)
+**Check structure**: "List increments" or `ls .specweave/increments/`
+
+---
+
+**For complete documentation, see SPECWEAVE.md**

package/src/adapters/cursor/README.md

@@ -0,0 +1,243 @@
+# Cursor Adapter
+
+**Automation Level**: Semi (Good experience with @ shortcuts and Composer)
+
+## Overview
+
+The Cursor adapter provides **semi-automation** for SpecWeave by teaching Cursor's AI how to **behave like** it has Claude Code's skills and agents, even without native support.
+
+## Key Insight: Simulating Anthropic's Standards
+
+**Anthropic Sets Standards** (MCP, Skills, Agents) that provide superior results. For Cursor, we provide **"implementation guides"** that teach the AI how to act like it has these capabilities.
+
+Example:
+```markdown
+# In .cursorrules:
+## What is a SpecWeave Skill?
+A skill is a specialized capability that activates automatically when relevant.
+
+**In Claude Code**: Skills are native (.claude/skills/)
+**In Cursor**: You simulate by reading relevant workflow instructions
+
+## increment-planner Skill
+When user says "create increment":
+1. Read .specweave/config.yaml
+2. Auto-increment number
+3. Create spec.md (act as PM role)
+4. Create plan.md (act as Architect role)
+5. Create tasks.md
+```
+
+This is **meta-documentation** - teaching the AI how to behave!
+
+## What This Adapter Provides
+
+### .cursorrules (Workflow Instructions)
+- **What**: Complete workflow guide for SpecWeave
+- **How**: Teaches Cursor to act like skills/agents
+- **Example**: When to adopt PM vs Architect perspective
+- **Benefit**: Semi-automated feature creation
+
+### @ Context Shortcuts
+| Shortcut | Loads | Use Case |
+|----------|-------|----------|
+| `@increments` | Current increment files | "What are we working on?" |
+| `@docs` | Architecture documentation | "Show me system design" |
+| `@strategy` | Business requirements | "What are the requirements?" |
+| `@tests` | Test strategy and cases | "What tests exist?" |
+
+**Usage**: Type `@increments show current tasks` in Cursor chat
+
+### Composer Multi-File Editing
+- Edit spec.md, plan.md, tasks.md simultaneously
+- Maintain consistency across files
+- Fast iteration on designs
+
+## How It Works
+
+### Simulating Skills
+
+**Claude Code (automatic)**:
+```typescript
+// Skills auto-activate
+User: "create increment for auth"
+→ specweave-detector activates
+→ skill-router routes to increment-planner
+→ increment-planner creates increment
+```
+
+**Cursor (manual simulation)**:
+```typescript
+// You follow .cursorrules instructions
+User: "create increment for auth"
+→ You read .cursorrules
+→ Follow workflow: check config → create folders → create files
+→ Act like increment-planner by following those steps
+```
+
+### Simulating Agents
+
+**Claude Code (automatic)**:
+```typescript
+Task({ subagent_type: "pm", prompt: "create spec" })
+→ PM agent invoked with separate context window
+```
+
+**Cursor (manual adoption)**:
+```typescript
+User: "act as PM and create spec"
+→ You adopt PM perspective:
+  - Focus on WHAT/WHY (not HOW)
+  - Technology-agnostic requirements
+  - User stories + acceptance criteria
+→ Create spec.md following PM role
+```
+
+**Pro Tip**: .cursorrules defines each role's responsibilities clearly
+
+## Installation
+
+```bash
+# Install SpecWeave with Cursor adapter
+npx specweave init my-project --adapter cursor
+
+# Files created:
+# .cursorrules                  (workflow instructions)
+# .cursor/context/*.md          (@ shortcut targets)
+```
+
+## Directory Structure
+
+```
+.cursorrules                   # Main workflow instructions
+.cursor/
+├── README.md                  # This file
+└── context/                   # @ shortcut files
+    ├── increments-context.md
+    ├── docs-context.md
+    ├── strategy-context.md
+    └── tests-context.md
+```
+
+## Usage Examples
+
+### Example 1: Create Feature
+
+**User**: "Create increment for user authentication"
+
+**Cursor** (following .cursorrules):
+1. ✅ Read .specweave/config.yaml
+2. ✅ Find next increment number (0003)
+3. ✅ Create folder: `.specweave/increments/0003-user-authentication/`
+4. ✅ Act as PM: Create spec.md (WHAT/WHY, user stories, acceptance criteria)
+5. ✅ Act as Architect: Create plan.md (HOW, technical design, components)
+6. ✅ Create tasks.md (implementation checklist)
+7. ✅ Create context-manifest.yaml (list files to load - 70%+ token savings)
+
+**Result**: Complete increment ready for implementation!
+
+### Example 2: Use @ Shortcuts
+
+**User**: "@increments what's the current task?"
+
+**Cursor**:
+1. ✅ Loads current increment's spec.md, plan.md, tasks.md
+2. ✅ Reads tasks.md → Find first unchecked task
+3. ✅ Response: "Currently on T003: Implement OAuth2 authentication flow"
+
+### Example 3: Multi-File Edit with Composer
+
+**User**: *Opens Composer (Cmd+I)*
+"Update spec.md and plan.md to add Google OAuth login"
+
+**Cursor**:
+1. ✅ Edits spec.md → Add FR-003 (Google OAuth requirement)
+2. ✅ Edits plan.md → Add OAuth implementation section
+3. ✅ Maintains consistency between both files
+
+### Example 4: Adopt Agent Role
+
+**User**: "Act as DevOps agent and create Terraform for Hetzner"
+
+**Cursor** (adopting DevOps role):
+1. ✅ Focus on infrastructure (not application code)
+2. ✅ Create Terraform files (provider.tf, main.tf, variables.tf)
+3. ✅ Add monitoring, logging, security configs
+4. ✅ Document deployment process
+
+## Context Loading (70%+ Token Savings)
+
+**.cursorrules teaches Cursor**:
+
+```markdown
+## CRITICAL: Context Manifest
+
+**Always read context-manifest.yaml first!**
+
+Example:
+```yaml
+spec_sections:
+  - .specweave/docs/internal/strategy/auth/spec.md
+documentation:
+  - .specweave/docs/internal/architecture/auth-design.md
+```
+
+**ONLY load these 2 files**, not entire .specweave/docs/ folder!
+
+**Why?**
+- Full specs: 500+ pages (50k tokens)
+- Manifest files: 50 pages (5k tokens)
+- Savings: 90% = 45k tokens saved!
+```
+
+## Comparison: Cursor vs Claude Code
+
+| Feature | Claude Code | Cursor |
+|---------|-------------|--------|
+| **Skills** | Native auto-activation | Simulated via .cursorrules |
+| **Agents** | Separate context windows | Manual role adoption |
+| **Hooks** | Auto-execute on events | Not available |
+| **Commands** | Native slash commands | Workflow instructions |
+| **Context** | MCP protocol | Manual loading via @ shortcuts |
+| **File Access** | Native tools | Native (Composer) |
+| **Automation** | Full | Semi |
+
+**Cursor = Good experience** (70-80% of Claude Code's capabilities)
+
+## Limitations
+
+❌ **No auto-activation** - Must explicitly request workflows
+❌ **No separate context windows** - All context shared
+❌ **No hooks** - Can't auto-update docs on events
+⚠️ **Manual role adoption** - Must say "act as PM"
+
+✅ **But Composer + @ shortcuts provide great UX!**
+
+## Tips & Tricks
+
+### 1. Always Mention Context-Manifest
+"Read context-manifest.yaml and load only files listed there"
+
+### 2. Be Explicit About Roles
+"Act as PM agent and create spec" (not just "create spec")
+
+### 3. Use @ Shortcuts
+Faster than typing full file paths
+
+### 4. Use Composer for Multi-File Edits
+Cmd+I → Edit multiple files at once
+
+### 5. Reference .cursorrules
+If Cursor forgets workflow: "Follow the workflow in .cursorrules"
+
+## Related Documentation
+
+- [SPECWEAVE.md](../../SPECWEAVE.md) - Complete development guide
+- [.cursorrules](.cursorrules) - Cursor workflow instructions (READ THIS!)
+- [Adapter Architecture](../README.md) - Multi-tool design philosophy
+
+---
+
+**Status**: Active (v0.2.0-beta.1+)
+**Market Share**: ~30% (Cursor users)
+**Priority**: P1 (high impact adapter)