specweave 0.1.0

package/src/adapters/claude/README.md

@@ -0,0 +1,241 @@
+# 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 |
+| `/review-docs` | Review strategic documentation |
+| `/sync-github` | Sync to GitHub issues |
+| `/create-project` | 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
+│   ├── review-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**: `/review-docs`
+
+**What Happens** (Automatic):
+1. ✅ Slash command loads `.claude/commands/review-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 bidirectional sync
+
+## 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: "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:
+
+```yaml
+# .specweave/config.yaml
+hooks:
+  post_task_completion:
+    enabled: true
+    actions:
+      - update_documentation
+      - update_claude_md
+```
+
+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/src/adapters/claude/adapter.ts

@@ -0,0 +1,157 @@
+/**
+ * Claude Code Adapter
+ *
+ * Full automation adapter for Claude Code.
+ * Provides best-in-class experience with native skills, agents, hooks, and slash commands.
+ *
+ * This is the BASELINE adapter - all other adapters try to approximate this experience
+ * within their tool's capabilities.
+ */
+
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { AdapterBase } from '../adapter-base';
+import { AdapterOptions, AdapterFile } from '../adapter-interface';
+
+export class ClaudeAdapter extends AdapterBase {
+  name = 'claude';
+  description = 'Claude Code adapter - Full automation with skills, agents, hooks, and slash commands';
+  automationLevel = 'full' as const;
+
+  /**
+   * Detect if Claude Code is available
+   *
+   * Checks for:
+   * - claude command in PATH
+   * - Claude Code CLI installation
+   */
+  async detect(): Promise<boolean> {
+    // Check if claude CLI exists
+    const hasClaudeCLI = await this.commandExists('claude');
+
+    // Check if .claude directory exists (already using Claude)
+    const hasClaudeDir = await this.fileExists('.claude');
+
+    return hasClaudeCLI || hasClaudeDir;
+  }
+
+  /**
+   * Get files to install for Claude adapter
+   *
+   * Claude adapter installs:
+   * - Skills to .claude/skills/ (auto-activating capabilities)
+   * - Agents to .claude/agents/ (specialized roles)
+   * - Commands to .claude/commands/ (slash commands)
+   * - Hooks to .claude/hooks/ (auto-update mechanisms)
+   */
+  getFiles(): AdapterFile[] {
+    return [
+      {
+        sourcePath: 'README.md',
+        targetPath: '.claude/README.md',
+        description: 'Claude adapter documentation'
+      }
+      // Note: Skills, agents, commands, hooks are installed via npm scripts
+      // (install:skills, install:agents) - not copied here
+    ];
+  }
+
+  /**
+   * Install Claude adapter
+   *
+   * Since SpecWeave was originally built for Claude Code, the "installation"
+   * is actually just ensuring the existing .claude/ structure is correct.
+   *
+   * Skills, agents, commands, hooks are installed separately via:
+   * - npm run install:skills
+   * - npm run install:agents
+   */
+  async install(options: AdapterOptions): Promise<void> {
+    console.log('\n📦 Installing Claude Code Adapter (Full Automation)\n');
+
+    // Ensure .claude directory exists
+    const claudeDir = path.join(options.projectPath, '.claude');
+    await fs.ensureDir(claudeDir);
+
+    // Create subdirectories
+    await fs.ensureDir(path.join(claudeDir, 'skills'));
+    await fs.ensureDir(path.join(claudeDir, 'agents'));
+    await fs.ensureDir(path.join(claudeDir, 'commands'));
+    await fs.ensureDir(path.join(claudeDir, 'hooks'));
+
+    // Copy README
+    await super.install(options);
+
+    console.log('\n✨ Claude adapter structure created!');
+    console.log('\n📋 Next steps:');
+    console.log('   1. Install skills: npm run install:skills');
+    console.log('   2. Install agents: npm run install:agents');
+    console.log('   3. Skills will auto-activate when relevant');
+    console.log('   4. Use slash commands: /create-increment, /review-docs, etc.');
+  }
+
+  /**
+   * Post-installation instructions
+   */
+  async postInstall(options: AdapterOptions): Promise<void> {
+    console.log(this.getInstructions());
+  }
+
+  /**
+   * Get usage instructions for Claude adapter
+   */
+  getInstructions(): string {
+    return `
+
+================================================================
+      Claude Code Adapter - Full Automation
+================================================================
+
+Your project is now configured for Claude Code with FULL automation!
+
+QUICK START:
+
+1. Install components:
+   npm run install:skills    # Install all skills
+   npm run install:agents    # Install all agents
+
+2. Create your first feature:
+   Just ask Claude: "Create increment for user authentication"
+   - specweave-detector skill activates automatically
+   - skill-router routes to increment-planner
+   - PM agent creates spec.md
+   - Architect agent creates plan.md
+
+3. Use slash commands:
+   /create-increment "payment processing"
+   /review-docs
+   /sync-github
+
+WHAT THIS PROVIDES:
+
+- Skills (Auto-Activating): specweave-detector, skill-router, context-loader, increment-planner
+- Agents (Specialized Roles): PM, Architect, DevOps, QA, Security, and 14 more
+- Slash Commands: /create-increment, /review-docs, /sync-github, /create-project
+- Hooks (Auto-Update): post-task-completion, pre-implementation, docs-changed
+
+WHY CLAUDE CODE IS BEST:
+
+Anthropic Sets Standards (MCP, Skills, Agents) that provide superior results:
+- MCP Protocol: Native context management, efficient, standardized
+- Skills + Agents: Proven patterns, auto-activation, role-based, separate contexts
+- Native Tools: Direct file access, real-time execution
+- Result: Superior accuracy, speed, and developer UX
+
+DOCUMENTATION:
+
+- SPECWEAVE.md: Complete development guide
+- .specweave/docs/: Project documentation (5-pillar)
+- src/skills/: All available skills
+- src/agents/: All available agents
+
+You're ready to build with SpecWeave on Claude Code!
+
+For complete documentation, see: .claude/README.md
+    `;
+  }
+}