specweave 0.1.0

package/src/adapters/copilot/adapter.ts

@@ -0,0 +1,210 @@
+/**
+ * GitHub Copilot Adapter
+ *
+ * Basic automation adapter for GitHub Copilot.
+ * Provides workspace instructions that Copilot reads for context and suggestions.
+ *
+ * Since GitHub Copilot has limited configuration (workspace instructions only),
+ * this adapter focuses on clear, structured guidance that Copilot can use
+ * to provide better code suggestions and completions.
+ */
+
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { AdapterBase } from '../adapter-base';
+import { AdapterOptions, AdapterFile } from '../adapter-interface';
+
+export class CopilotAdapter extends AdapterBase {
+  name = 'copilot';
+  description = 'GitHub Copilot adapter - Basic automation with workspace instructions';
+  automationLevel = 'basic' as const;
+
+  /**
+   * Detect if GitHub Copilot is available
+   *
+   * Checks for:
+   * - .github/copilot/instructions.md exists
+   * - VS Code with Copilot extension
+   */
+  async detect(): Promise<boolean> {
+    const hasInstructions = await this.fileExists('.github/copilot/instructions.md');
+    const hasGitHubDir = await this.fileExists('.github');
+
+    // Check for VS Code Copilot extension (best effort)
+    // This is approximate - Copilot might be installed but we can't detect reliably
+    return hasInstructions || hasGitHubDir;
+  }
+
+  /**
+   * Get files to install for Copilot adapter
+   */
+  getFiles(): AdapterFile[] {
+    return [
+      {
+        sourcePath: '.github/copilot/instructions.md',
+        targetPath: '.github/copilot/instructions.md',
+        description: 'GitHub Copilot workspace instructions'
+      },
+      {
+        sourcePath: 'README.md',
+        targetPath: '.github/copilot/README.md',
+        description: 'Copilot adapter documentation'
+      }
+    ];
+  }
+
+  /**
+   * Install Copilot adapter
+   */
+  async install(options: AdapterOptions): Promise<void> {
+    console.log('\n📦 Installing GitHub Copilot Adapter (Basic Automation)\n');
+
+    // Ensure .github/copilot directory exists
+    const copilotDir = path.join(options.projectPath, '.github', 'copilot');
+    await fs.ensureDir(copilotDir);
+
+    // Copy files
+    await super.install(options);
+
+    console.log('\n✨ Copilot adapter installed!');
+    console.log('\n📋 Files created:');
+    console.log('   - .github/copilot/instructions.md (workspace guidance)');
+  }
+
+  /**
+   * Post-installation instructions
+   */
+  async postInstall(options: AdapterOptions): Promise<void> {
+    console.log(this.getInstructions());
+  }
+
+  /**
+   * Get usage instructions for Copilot adapter
+   */
+  getInstructions(): string {
+    return `
+================================================================
+      GitHub Copilot Adapter - Basic Automation
+================================================================
+
+Your project is now configured for GitHub Copilot!
+
+WHAT THIS PROVIDES:
+
+- Workspace Instructions (.github/copilot/instructions.md)
+  - Project overview (SpecWeave framework)
+  - Workflow guidance (creating increments)
+  - Context manifest explanation
+  - File structure reference
+
+- Better Code Suggestions
+  - Copilot reads workspace instructions
+  - Suggests code following SpecWeave patterns
+  - Understands project structure
+
+UNDERSTANDING THE DIFFERENCE:
+
+Claude Code (Full Automation):
+- Native skills (auto-activate)
+- Native agents (separate context windows)
+- Native hooks (auto-update docs)
+- Slash commands
+
+Cursor (Semi-Automation):
+- Simulated skills (.cursorrules)
+- Simulated agents (manual roles)
+- @ context shortcuts
+
+Copilot (Basic Automation - This Adapter):
+- Workspace instructions only
+- Better code suggestions
+- No skills, agents, hooks, or commands
+- Manual workflow with AI assistance
+
+HOW WE BRIDGE THE GAP:
+
+GitHub Copilot doesn't support custom commands or complex
+workflows. But it DOES read workspace instructions to provide
+better code suggestions.
+
+We provide clear instructions that teach Copilot about:
+- SpecWeave structure (.specweave/ folders)
+- File naming conventions (spec.md, plan.md, tasks.md)
+- Context manifests (what files to reference)
+- Best practices (technology-agnostic specs, etc.)
+
+Result: Copilot suggests code that fits SpecWeave patterns!
+
+HOW TO USE SPECWEAVE WITH COPILOT:
+
+1. Copilot reads workspace instructions automatically
+   - No action needed - just open project in VS Code
+   - Copilot will suggest code following SpecWeave patterns
+
+2. Create increments manually:
+
+   mkdir -p .specweave/increments/0001-user-auth
+
+3. Reference context manifests:
+   Open context-manifest.yaml
+   → Copilot sees which files are relevant
+   → Provides better suggestions
+
+4. Ask Copilot Chat for guidance:
+   "How do I create a spec.md following SpecWeave?"
+   "Generate plan.md for user authentication"
+   "What should go in context-manifest.yaml?"
+
+5. Use Copilot inline suggestions:
+   Start typing in spec.md → Copilot suggests content
+   Following SpecWeave patterns from instructions.md
+
+WORKFLOW EXAMPLE:
+
+Creating a Feature:
+
+1. Create increment folder:
+
+   mkdir -p .specweave/increments/0002-payments
+   cd .specweave/increments/0002-payments
+
+2. Create spec.md:
+   - Open file, start typing frontmatter
+   - Copilot suggests SpecWeave structure
+   - Fill in user stories, acceptance criteria
+
+3. Create plan.md:
+   - Reference spec.md (Copilot reads it)
+   - Start typing "# Technical Plan"
+   - Copilot suggests architecture sections
+
+4. Create context-manifest.yaml:
+   - Copilot suggests relevant files to include
+   - Lists spec sections and architecture docs
+
+LIMITATIONS (vs Claude Code & Cursor):
+
+- No auto-activation or workflows
+- No skills, agents, hooks
+- No slash commands or @ shortcuts
+- No role-based assistance (PM, Architect, etc.)
+- Completely manual workflow
+
+But Copilot still provides helpful suggestions!
+- Understands SpecWeave structure from instructions
+- Suggests code following project patterns
+
+DOCUMENTATION:
+
+- SPECWEAVE.md: Complete development guide
+- .github/copilot/instructions.md: Workspace instructions
+- .github/copilot/README.md: Copilot adapter guide
+- .specweave/docs/: Project documentation
+
+You're ready to build with SpecWeave on GitHub Copilot!
+
+Note: For better automation, consider Claude Code (full) or Cursor (semi).
+Copilot is best for simple projects or when already using VS Code + Copilot.
+    `;
+  }
+}

package/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/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/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/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."