specweave 0.30.18 → 0.32.0

package/dist/src/adapters/claude/README.md

@@ -0,0 +1,233 @@
+# Claude Code Adapter
+
+**Automation Level**: Full (Best-in-class experience)
+
+## Overview
+
+The Claude Code adapter provides **full automation** for SpecWeave, leveraging Claude Code's native capabilities for skills, agents, hooks, and slash commands.
+
+This adapter represents the **gold standard** - all other adapters attempt to approximate this experience within their tool's capabilities.
+
+## Why Claude Code Provides Superior Results
+
+**Anthropic Defines Industry Standards:**
+
+### 1. MCP (Model Context Protocol)
+- **What**: Standardized protocol for context management
+- **Why**: Efficient, tool-integrated, proven pattern
+- **Benefit**: Native context loading, 70%+ token reduction
+
+### 2. Skills + Agents Architecture
+- **What**: Proven pattern for AI capabilities and roles
+- **Skills**: Auto-activating capabilities (specweave-detector, skill-router)
+- **Agents**: Specialized roles with separate context windows (PM, Architect, DevOps)
+- **Why**: Context isolation, role-based expertise, automatic activation
+- **Benefit**: More accurate, faster, better UX
+
+### 3. Native Tool Integration
+- **What**: Direct access to Read, Write, Edit, Bash, Grep, Glob
+- **Why**: Real-time file system access, command execution
+- **Benefit**: Seamless development workflow
+
+## What This Adapter Provides
+
+### Skills (Auto-Activating)
+| Skill | Purpose | Activation |
+|-------|---------|------------|
+| `specweave-detector` | Detect SpecWeave projects | Always (proactive) |
+| `skill-router` | Route requests to appropriate skills/agents | Automatic |
+| `context-loader` | Load context manifests (70%+ token savings) | When loading context |
+| `increment-planner` | Plan features with context awareness | When creating features |
+| `role-orchestrator` | Coordinate multi-agent workflows | Complex tasks |
+| `brownfield-analyzer` | Analyze existing codebases | Brownfield projects |
+
+**Plus 18+ more skills** (see `src/skills/`)
+
+### Agents (Specialized Roles)
+| Agent | Role | When Used |
+|-------|------|-----------|
+| `pm` | Product Manager | Requirements, user stories |
+| `architect` | System Architect | Design, ADRs, architecture |
+| `devops` | DevOps Engineer | Infrastructure, deployment |
+| `qa-lead` | QA Lead | Test strategy, test cases |
+| `security` | Security Engineer | Threat modeling, audits |
+| `tech-lead` | Technical Lead | Code review, best practices |
+| `frontend` | Frontend Developer | UI implementation |
+| `python-backend` | Python Backend Dev | FastAPI, Django APIs |
+| `nodejs-backend` | Node.js Backend Dev | Express, NestJS APIs |
+| `nextjs` | Next.js Specialist | Next.js apps |
+
+**Plus 10+ more agents** (see `src/agents/`)
+
+### Slash Commands
+| Command | Purpose |
+|---------|---------|
+| `/create-increment` | Create new feature increment |
+| `/sync-docs` | Review strategic documentation |
+| `/sync-github` | Sync to GitHub issues |
+| `specweave init` | Bootstrap new project |
+
+**Plus more commands** (see `.claude/commands/`)
+
+### Hooks (Auto-Update)
+| Hook | Purpose |
+|------|---------|
+| `post-task-completion` | Auto-update docs after tasks |
+| `pre-implementation` | Check regression risk |
+| `docs-changed` | Validate documentation |
+
+## Installation
+
+```bash
+# Install SpecWeave with Claude adapter (default)
+npx specweave init my-project
+
+# Or explicitly specify Claude adapter
+npx specweave init my-project --adapter claude
+
+# Install skills and agents
+cd my-project
+npm run install:skills
+npm run install:agents
+```
+
+## Directory Structure
+
+```
+.claude/
+├── skills/                 # Auto-activating capabilities
+│   ├── specweave-detector/
+│   ├── skill-router/
+│   ├── context-loader/
+│   └── ...
+├── agents/                 # Specialized roles
+│   ├── pm/
+│   ├── architect/
+│   ├── devops/
+│   └── ...
+├── commands/               # Slash commands
+│   ├── create-increment.md
+│   ├── sync-docs.md
+│   └── ...
+└── hooks/                  # Auto-update mechanisms
+    ├── post-task-completion.sh
+    ├── pre-implementation.sh
+    └── ...
+```
+
+## Usage Examples
+
+### Example 1: Create Feature (Full Automation)
+
+**User**: "Create increment for user authentication"
+
+**What Happens** (Automatic):
+1. ✅ `specweave-detector` skill activates (detects SpecWeave project)
+2. ✅ `skill-router` routes to `increment-planner`
+3. ✅ `increment-planner` invokes `pm` agent
+4. ✅ `pm` agent creates `spec.md` (WHAT/WHY)
+5. ✅ `increment-planner` invokes `architect` agent
+6. ✅ `architect` agent creates `plan.md` (HOW)
+7. ✅ `increment-planner` creates `tasks.md` (implementation steps)
+8. ✅ `context-loader` creates `context-manifest.yaml` (70%+ token savings)
+
+**Result**: Complete increment ready for implementation!
+
+### Example 2: Review Documentation
+
+**User**: `/sync-docs`
+
+**What Happens** (Automatic):
+1. ✅ Slash command loads `.claude/commands/sync-docs.md`
+2. ✅ Reviews strategic docs (.specweave/docs/internal/strategy/)
+3. ✅ Compares against actual implementation
+4. ✅ Identifies gaps (undocumented features, outdated docs, tech debt)
+5. ✅ Generates report
+
+### Example 3: Sync to GitHub
+
+**User**: `/sync-github`
+
+**What Happens** (Automatic):
+1. ✅ Reads increment spec.md and tasks.md
+2. ✅ Creates/updates GitHub issue
+3. ✅ Adds user stories as description
+4. ✅ Adds tasks as checkable checklist
+5. ✅ Stores issue number for full sync with all permissions enabled
+
+## Comparison with Other Adapters
+
+| Feature | Claude | Cursor | Copilot | Generic |
+|---------|--------|--------|---------|---------|
+| **Automation** | Full | Semi | Basic | Manual |
+| **Skills** | Native | Simulated | N/A | N/A |
+| **Agents** | Native | Manual invoke | Manual invoke | Copy-paste |
+| **Hooks** | Native | N/A | N/A | N/A |
+| **Commands** | Slash commands | Instructions | Instructions | Copy-paste |
+| **Context Loading** | Auto | Manual ref | Manual ref | Copy-paste |
+| **File Access** | Native | Native | Native | Manual |
+
+**Claude Code = Gold Standard**
+
+## Technical Details
+
+### Skills Activation
+
+Skills activate automatically based on:
+- Description matching user's request
+- Keywords in skill YAML frontmatter
+- Context (SpecWeave project detected)
+
+**Example**:
+```yaml
+---
+name: increment-planner
+description: Plan features with context awareness. Activates for: create feature, plan increment, new feature.
+---
+```
+
+When user says "create feature", Claude Code automatically activates `increment-planner` skill.
+
+### Agents Invocation
+
+Agents are invoked explicitly via Task tool:
+
+```typescript
+await Task({
+  subagent_type: "specweave:pm:pm",
+  prompt: "Create product requirements for user authentication",
+  description: "Product requirements analysis"
+});
+```
+
+Agents have separate context windows to prevent pollution of main conversation.
+
+### Hooks Execution
+
+Hooks run automatically on events:
+
+
+
+When task completes → hook fires → docs auto-update.
+
+## Why Other Tools Can't Fully Replicate This
+
+1. **No native skills/agents support** - Must simulate via instruction files
+2. **No separate context windows** - All context shared (can cause pollution)
+3. **No hooks** - Can't auto-update on events
+4. **No native MCP** - Context loading less efficient
+
+**But they can get close!** See Cursor, Copilot, and Generic adapters for approximations.
+
+## Related Documentation
+
+- [SPECWEAVE.md](../../SPECWEAVE.md) - Complete development guide
+- [src/skills/](../../skills/) - All available skills
+- [src/agents/](../../agents/) - All available agents
+- [Adapter Architecture](../README.md) - Multi-tool design philosophy
+
+---
+
+**Status**: Active (v0.1.0-beta.1+)
+**Market Share**: ~10% (Claude Code users)
+**Priority**: P1 (baseline/reference adapter)

package/dist/src/adapters/codex/README.md

@@ -0,0 +1,105 @@
+# OpenAI Codex Adapter
+
+**Automation Level**: Semi (Good experience with GPT-5-Codex and multiple access points)
+
+## Overview
+
+The Codex adapter provides **semi-automation** for SpecWeave using OpenAI's Codex (ChatGPT Code Interpreter/Codex CLI) with **AGENTS.md** as the universal instruction file.
+
+## Key Features
+
+- **GPT-5-Codex Model**: Optimized for engineering tasks
+- **Multiple Access Points**: CLI, Web, IDE, GitHub, iOS app
+- **Task-Based Execution**: Isolated environments per task
+- **File Operations**: Read, write, execute commands
+- **Test Execution**: Run tests and validate implementations
+- **Real-Time Progress**: Monitor task execution (1-30 min/task)
+
+## Installation
+
+```bash
+# Install Codex CLI (requires ChatGPT Plus/Pro/Business/Enterprise)
+npm install -g openai-codex-cli
+
+# Initialize SpecWeave project with Codex adapter
+npx specweave init my-project --adapter codex
+```
+
+## How It Works
+
+### Option 1: Codex CLI (Fastest)
+```bash
+codex "Read AGENTS.md and create increment for user authentication"
+```
+
+### Option 2: ChatGPT Web (Most Accessible)
+1. Upload AGENTS.md file
+2. Say: "Create increment for user authentication following SpecWeave"
+3. Copy generated content to files
+
+### Option 3: IDE Integration
+Use Codex in your IDE (VS Code, JetBrains) with AGENTS.md reference
+
+## Universal AGENTS.md
+
+Instead of tool-specific files, SpecWeave uses **AGENTS.md** that works with ALL tools:
+
+- ✅ Codex (OpenAI)
+- ✅ Gemini CLI
+- ✅ Cursor
+- ✅ GitHub Copilot
+- ✅ ANY AI tool
+
+**Single source of truth** = easier maintenance!
+
+## Example Workflows
+
+### Create Feature (CLI)
+```bash
+codex "Read AGENTS.md. Create increment 0002 for payment processing with Stripe."
+```
+
+### Create Feature (Web)
+1. Upload AGENTS.md to ChatGPT
+2. Say: "Create increment for payment processing"
+3. Download generated files
+
+### Implement Task
+```bash
+codex "Read increment 0002, implement task T001"
+```
+
+### Fix Bug with Tests
+```bash
+codex "Read AGENTS.md and increment 0001. Fix auth bug. Run tests."
+```
+
+## Comparison with Claude Code
+
+| Feature | Claude Code | Codex |
+|---------|-------------|-------|
+| **Automation** | Full | Semi |
+| **Skills** | Native | Via AGENTS.md |
+| **Agents** | Native | Via AGENTS.md |
+| **Access Points** | CLI only | CLI + Web + IDE + GitHub + iOS |
+| **Model** | Sonnet 4.5 | GPT-5-Codex |
+| **Task Isolation** | No | Yes (isolated per task) |
+| **Hooks** | Yes | No |
+
+## Plans & Pricing
+
+- **ChatGPT Plus**: $20/month (Codex included)
+- **ChatGPT Pro**: $200/month (unlimited, faster)
+- **Business/Enterprise**: Custom pricing
+
+## Links
+
+- [OpenAI Codex](https://openai.com/codex/)
+- [ChatGPT Features](https://chatgpt.com/features/codex)
+- [SpecWeave Website](https://spec-weave.com)
+
+---
+
+**Status**: Active (v0.2.0+)
+**Market Share**: ~20% (OpenAI users)
+**Priority**: P1 (high impact - most accessible AI tool)

package/dist/src/adapters/cursor/.cursor/context/docs-context.md

@@ -0,0 +1,62 @@
+# @docs - Architecture Documentation Context
+
+This file is loaded when you type `@docs` in Cursor.
+
+## What This Provides
+
+Quick access to architecture documentation:
+- System design (HLD)
+- ADRs (Architecture Decision Records)
+- Component diagrams (C4 Model)
+- Data models (ER diagrams)
+
+## Usage
+
+```
+@docs show me the system architecture
+@docs what ADRs exist for authentication?
+@docs explain the data model
+```
+
+## Files Loaded
+
+When `@docs` is used, Cursor should load:
+
+```
+.specweave/docs/internal/architecture/
+├── system-design.md           # HLD
+├── adr/                       # Architecture Decision Records
+│   ├── 0001-tech-stack.md
+│   ├── 0002-database-choice.md
+│   └── ...
+├── diagrams/                  # C4 diagrams
+│   ├── system-context.mmd     # C4 Level 1
+│   ├── system-container.mmd   # C4 Level 2
+│   └── {module}/              # C4 Level 3 (component)
+└── data-models/               # ER diagrams
+    └── schema.sql
+```
+
+## Context Precision
+
+**Don't load everything!**
+
+If working on specific module (e.g., authentication):
+1. Check context-manifest.yaml
+2. Load ONLY auth-related docs:
+   ```
+   .specweave/docs/internal/architecture/auth/
+   ├── design.md
+   ├── adr/0005-auth-method.md
+   └── diagrams/auth-flow.mmd
+   ```
+
+## Example Workflow
+
+User: `@docs show authentication architecture`
+
+You:
+1. Load .specweave/docs/internal/architecture/auth/
+2. Load ADRs related to auth (ADR-0005, ADR-0012)
+3. Load auth diagrams
+4. Summarize: "Authentication uses OAuth2 (ADR-0005), JWT tokens stored in httpOnly cookies (ADR-0012). See auth-flow.mmd for sequence diagram."

package/dist/src/adapters/cursor/.cursor/context/increments-context.md

@@ -0,0 +1,71 @@
+# @increments - Current Increment Context
+
+This file is loaded when you type `@increments` in Cursor.
+
+## What This Provides
+
+Quick access to the current increment's:
+- spec.md (WHAT and WHY)
+- plan.md (HOW)
+- tasks.md (implementation steps)
+- context-manifest.yaml (what context to load)
+
+## Usage
+
+```
+@increments show me what we're working on
+@increments what's the current task?
+@increments load the spec for this feature
+```
+
+## Files Loaded
+
+When `@increments` is used, Cursor should load:
+
+1. **Current increment folder** (most recent in-progress):
+   ```
+   .specweave/increments/####-feature-name/
+   ├── spec.md
+   ├── plan.md
+   ├── tasks.md
+   └── context-manifest.yaml
+   ```
+
+2. **How to find current increment**:
+   ```bash
+   # List all increments
+   ls -la .specweave/increments/
+
+   # Find in-progress increments
+   grep -r "status: in-progress" .specweave/increments/*/spec.md
+   ```
+
+3. **Load order**:
+   - context-manifest.yaml (to know what else to load)
+   - spec.md (business requirements)
+   - plan.md (technical design)
+   - tasks.md (current task status)
+
+## Context Manifest Critical
+
+**ALWAYS read context-manifest.yaml first!**
+
+It tells you which additional files to load:
+```yaml
+spec_sections:
+  - .specweave/docs/internal/strategy/auth/spec.md
+documentation:
+  - .specweave/docs/internal/architecture/auth-design.md
+```
+
+Then load ONLY those files (70%+ token savings).
+
+## Example Workflow
+
+User: `@increments what's the current feature?`
+
+You:
+1. Find most recent in-progress increment
+2. Read spec.md → See it's user authentication
+3. Read tasks.md → See we're on T003 (OAuth2 implementation)
+4. Respond: "Working on user authentication (increment 0002). Currently on task T003: Implement OAuth2 flow."

package/dist/src/adapters/cursor/.cursor/context/strategy-context.md

@@ -0,0 +1,73 @@
+# @strategy - Business Strategy Context
+
+This file is loaded when you type `@strategy` in Cursor.
+
+## What This Provides
+
+Quick access to business strategy documentation:
+- Product vision and goals
+- Business requirements (technology-agnostic)
+- User stories and acceptance criteria
+- PRDs (Product Requirements Documents)
+
+## Usage
+
+```
+@strategy what's the product vision?
+@strategy show me authentication requirements
+@strategy what are the success criteria?
+```
+
+## Files Loaded
+
+When `@strategy` is used, Cursor should load:
+
+```
+.specweave/docs/internal/strategy/
+├── {module}/                  # Module-specific strategy
+│   ├── overview.md            # Product vision
+│   ├── requirements.md        # FR/NFR (tech-agnostic)
+│   ├── user-stories.md        # All user stories
+│   └── success-criteria.md    # KPIs, metrics
+```
+
+## Context Precision
+
+**Don't load everything!**
+
+If working on authentication module:
+1. Load ONLY auth strategy:
+   ```
+   .specweave/docs/internal/strategy/auth/
+   ├── overview.md
+   ├── requirements.md
+   ├── user-stories.md
+   └── success-criteria.md
+   ```
+
+## Technology-Agnostic Requirements
+
+**Critical**: Strategy docs are technology-agnostic (WHAT/WHY, not HOW).
+
+**Good (technology-agnostic)**:
+```markdown
+## FR-001: User Authentication
+Users must be able to securely authenticate with their email and password.
+```
+
+**Bad (too technical)**:
+```markdown
+## FR-001: User Authentication
+Users authenticate via JWT tokens stored in httpOnly cookies with bcrypt password hashing.
+```
+
+The technical details go in architecture docs (@docs), not strategy.
+
+## Example Workflow
+
+User: `@strategy what are the authentication requirements?`
+
+You:
+1. Load .specweave/docs/internal/strategy/auth/requirements.md
+2. Read functional and non-functional requirements
+3. Summarize: "FR-001: Email/password auth. FR-002: Social login (Google, GitHub). NFR-001: < 2s login response time. NFR-002: 99.9% uptime."

package/dist/src/adapters/cursor/.cursor/context/tests-context.md

@@ -0,0 +1,89 @@
+# @tests - Test Strategy Context
+
+This file is loaded when you type `@tests` in Cursor.
+
+## What This Provides
+
+Quick access to test documentation:
+- Test strategy (E2E, unit, integration)
+- Test coverage matrix (TC-0001 → test files)
+- Test cases (YAML format for skills)
+- Acceptance criteria validation
+
+## Usage
+
+```
+@tests show me test strategy
+@tests what tests exist for authentication?
+@tests map TC-0001 to test file
+```
+
+## Files Loaded
+
+When `@tests` is used, Cursor should load:
+
+```
+.specweave/increments/####-feature/tests.md    # Test strategy
+tests/                                          # Actual test code
+├── e2e/                                        # Playwright E2E tests
+│   └── auth.spec.ts
+├── unit/                                       # Unit tests
+│   └── auth-utils.test.ts
+└── integration/                                # Integration tests
+    └── auth-api.test.ts
+```
+
+## Test Coverage Matrix
+
+**tests.md contains mapping: TC-0001 → test file**
+
+Example:
+```markdown
+| TC ID   | Acceptance Criteria     | Test Type | Location               | Priority |
+|---------|-------------------------|-----------|------------------------|----------|
+| TC-0001 | Valid login redirects   | E2E       | tests/e2e/auth.spec.ts | P1       |
+| TC-0002 | Invalid password errors | E2E       | tests/e2e/auth.spec.ts | P1       |
+```
+
+## Four Levels of Test Cases
+
+### Level 1: Specification (TC-0001 in spec.md)
+```markdown
+- [ ] **TC-0001**: Valid credentials → redirect to dashboard
+```
+
+### Level 2: Feature Test Strategy (tests.md)
+Mapping TC-0001 to test implementation
+
+### Level 3: Skill Test Cases (for SpecWeave skills)
+YAML format in src/skills/{name}/test-cases/
+
+### Level 4: Code Tests (Playwright, Jest, etc.)
+```typescript
+test('TC-0001: Valid Login Flow', async ({ page }) => {
+  // Implementation
+});
+```
+
+## Context Precision
+
+**Load test strategy for current increment only**
+
+If working on auth increment:
+```
+.specweave/increments/0002-user-auth/tests.md
+tests/e2e/auth.spec.ts
+tests/unit/auth-utils.test.ts
+```
+
+Don't load ALL tests from ALL increments.
+
+## Example Workflow
+
+User: `@tests what's the test coverage for authentication?`
+
+You:
+1. Load .specweave/increments/0002-user-auth/tests.md
+2. Read test coverage matrix
+3. Load referenced test files (auth.spec.ts)
+4. Summarize: "TC-0001 to TC-0008 covered. 8/8 E2E tests in auth.spec.ts. All P1 tests passing."