specweave 0.1.0

package/src/templates/.env.example

@@ -0,0 +1,144 @@
+# SpecWeave - Environment Variables Template
+# Copy this file to .env and fill in your actual values
+# NEVER commit .env to git!
+
+# ===================================
+# Infrastructure & Cloud Platforms
+# ===================================
+
+# Hetzner Cloud (https://console.hetzner.cloud/)
+# Navigate to: Security → API Tokens → Generate API Token
+# Permissions: Read & Write
+HETZNER_API_TOKEN=your-hetzner-token-here-64-chars-alphanumeric
+
+# AWS (https://console.aws.amazon.com/iam/)
+# Navigate to: IAM → Users → Security Credentials
+AWS_ACCESS_KEY_ID=your-aws-access-key-20-chars
+AWS_SECRET_ACCESS_KEY=your-aws-secret-key-40-chars
+AWS_REGION=us-east-1
+
+# Azure (https://portal.azure.com/)
+# Navigate to: App Registrations → New Registration
+AZURE_CLIENT_ID=your-azure-client-id-uuid
+AZURE_CLIENT_SECRET=your-azure-client-secret
+AZURE_TENANT_ID=your-azure-tenant-id-uuid
+AZURE_SUBSCRIPTION_ID=your-azure-subscription-id-uuid
+
+# Google Cloud Platform (https://console.cloud.google.com/)
+# Navigate to: IAM → Service Accounts → Create Service Account
+# Download JSON key file and set path here
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+GCP_PROJECT_ID=your-gcp-project-id
+
+# DigitalOcean (https://cloud.digitalocean.com/account/api/tokens)
+DIGITALOCEAN_TOKEN=your-digitalocean-token-64-chars
+
+# Railway (https://railway.app/account/tokens)
+RAILWAY_TOKEN=your-railway-token-32-plus-chars
+
+# Vercel (https://vercel.com/account/tokens)
+VERCEL_TOKEN=your-vercel-token-here
+
+# ===================================
+# Integration Services
+# ===================================
+
+# GitHub (https://github.com/settings/tokens)
+# Scopes: repo, read:org, workflow
+GITHUB_TOKEN=ghp_your-github-token-40-chars
+
+# JIRA (https://id.atlassian.com/manage-profile/security/api-tokens)
+JIRA_API_TOKEN=your-jira-api-token
+JIRA_EMAIL=your-email@example.com
+JIRA_DOMAIN=your-domain.atlassian.net
+
+# Azure DevOps (https://dev.azure.com/)
+# Navigate to: User Settings → Personal Access Tokens
+# Scopes: Work Items (Read, Write), Code (Read)
+AZURE_DEVOPS_PAT=your-ado-personal-access-token-52-chars-base64
+AZURE_DEVOPS_ORG=your-organization-name
+AZURE_DEVOPS_PROJECT=your-project-name
+
+# Figma (https://www.figma.com/developers/api#authentication)
+# Navigate to: Settings → Account → Personal Access Tokens
+FIGMA_ACCESS_TOKEN=figd_your-figma-token
+
+# ===================================
+# Database Connections
+# ===================================
+
+# PostgreSQL
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# MySQL
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=your-mysql-user
+MYSQL_PASSWORD=your-mysql-password
+MYSQL_DATABASE=your-database-name
+
+# MongoDB
+MONGODB_URI=mongodb://localhost:27017/your-db-name
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# ===================================
+# API Keys & Services
+# ===================================
+
+# Stripe (https://dashboard.stripe.com/apikeys)
+STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key
+STRIPE_PUBLISHABLE_KEY=pk_test_your-stripe-publishable-key
+STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret
+
+# SendGrid (https://app.sendgrid.com/settings/api_keys)
+SENDGRID_API_KEY=SG.your-sendgrid-api-key
+
+# Twilio (https://www.twilio.com/console)
+TWILIO_ACCOUNT_SID=your-twilio-account-sid
+TWILIO_AUTH_TOKEN=your-twilio-auth-token
+TWILIO_PHONE_NUMBER=+1234567890
+
+# OpenAI (https://platform.openai.com/api-keys)
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# Anthropic Claude (https://console.anthropic.com/)
+ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
+
+# ===================================
+# Application Configuration
+# ===================================
+
+# Environment
+NODE_ENV=development
+
+# Application URL
+APP_URL=http://localhost:3000
+
+# JWT Secret (generate with: openssl rand -hex 32)
+JWT_SECRET=your-jwt-secret-at-least-32-chars-long
+
+# Session Secret
+SESSION_SECRET=your-session-secret-at-least-32-chars-long
+
+# ===================================
+# Production Secrets Manager
+# ===================================
+# For production, consider using:
+# - Doppler: https://doppler.com
+# - AWS Secrets Manager: https://aws.amazon.com/secrets-manager/
+# - 1Password: https://1password.com/
+# - HashiCorp Vault: https://www.vaultproject.io/
+#
+# DO NOT use .env files in production!
+
+# ===================================
+# Security Notes
+# ===================================
+# ✅ This file (.env.example) is committed to git
+# ❌ Your actual .env file is NEVER committed (in .gitignore)
+# 🔄 Rotate secrets every 90 days
+# 🔒 Use production secrets managers for deployment
+# 📝 Document where each secret comes from
+# 👥 Share .env.example with team, NOT .env

package/src/templates/.gitignore.template

@@ -0,0 +1,81 @@
+# SpecWeave
+.specweave/cache/
+.specweave/increments/*/logs/       # Gitignored, but structure preserved
+.specweave/increments/*/test-results/
+
+# Dependencies (framework-agnostic)
+node_modules/          # JavaScript/TypeScript
+.pnpm-store/
+.yarn/
+.npm/
+__pycache__/           # Python
+*.pyc
+*.pyo
+*.pyd
+.Python
+venv/
+env/
+ENV/
+target/                # Rust
+Cargo.lock
+vendor/                # Go
+go.sum
+
+# Build outputs (framework-agnostic)
+.next/                 # NextJS
+dist/                  # Generic
+build/                 # Generic
+out/                   # Generic
+.output/               # Nuxt
+*.egg-info/            # Python
+__pypackages__/        # Python
+*.class                # Java
+*.jar                  # Java
+bin/                   # Go, Java
+
+# Environment
+.env
+.env.local
+.env.*.local
+*.env
+
+# Database (framework-agnostic)
+*.db
+*.sqlite
+*.sqlite3
+*.db-shm
+*.db-wal
+prisma/migrations/*/migration.sql   # Prisma (TypeScript)
+*/migrations/__pycache__/           # Django (Python)
+
+# Testing (framework-agnostic)
+coverage/              # Generic
+.nyc_output/           # JavaScript
+.coverage              # Python
+htmlcov/               # Python
+*.cover                # Python
+.pytest_cache/         # Python
+test-results/          # Playwright
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Temporary files
+*.tmp
+.temp/
+tmp/

package/src/templates/CLAUDE.md.template

@@ -0,0 +1,383 @@
+# {PROJECT_NAME} - Development Guide
+
+**THIS FILE IS YOUR QUICK REFERENCE FOR WORKING WITH THIS PROJECT**
+
+This project uses **SpecWeave** - a specification-first AI development framework where specifications and documentation are the SOURCE OF TRUTH.
+
+---
+
+## 🔷 SpecWeave Auto-Routing
+
+**MANDATORY**: This project has SpecWeave installed (`.specweave/` directory exists).
+
+**Behavior**:
+1. ✅ All development requests route through `specweave-detector` skill
+2. ✅ Agents activate automatically based on task (PM, Architect, DevOps, etc.)
+3. ✅ Context loaded selectively via manifests (70%+ token reduction)
+4. ✅ Tech stack detected automatically
+
+**Rule**: When in doubt, route through SpecWeave.
+
+---
+
+## Tech Stack
+
+**Project Type**: {MONOREPO_OR_SINGLE}
+
+{#IF_SINGLE_STACK}
+**Detected Stack**:
+- **Language**: {DETECTED_LANGUAGE} (e.g., TypeScript, Python, Go)
+- **Framework**: {DETECTED_FRAMEWORK} (e.g., Next.js, FastAPI, Django)
+- **Database**: {SPECIFIED_DATABASE} (e.g., PostgreSQL, MongoDB)
+- **Platform**: {SPECIFIED_PLATFORM} (e.g., Hetzner, AWS, Vercel)
+{#ENDIF}
+
+{#IF_MONOREPO}
+**Services**:
+- **{SERVICE_1_NAME}**: {SERVICE_1_LANGUAGE} + {SERVICE_1_FRAMEWORK} ({SERVICE_1_PATH}/)
+- **{SERVICE_2_NAME}**: {SERVICE_2_LANGUAGE} + {SERVICE_2_FRAMEWORK} ({SERVICE_2_PATH}/)
+{#ENDIF}
+
+**Config**: See `.specweave/config.yaml` for complete configuration
+
+---
+
+## 🚨 CRITICAL: File Organization Rules
+
+**MANDATORY**: Keep project root CLEAN. ALL AI-generated supporting files MUST go into increment folders.
+
+### What Goes Where
+
+**✅ ALLOWED in Project Root**:
+- `CLAUDE.md` (this file - ONLY file we add)
+- User's existing files (package.json, src/, etc. - unchanged)
+- Standard config files (.env, .gitignore, tsconfig.json, etc.)
+
+**❌ NEVER Create in Root** (use increment folders instead):
+- Logs → `.specweave/increments/{increment-id}/logs/`
+- Scripts → `.specweave/increments/{increment-id}/scripts/`
+- Reports → `.specweave/increments/{increment-id}/reports/`
+- Analysis files → `.specweave/increments/{increment-id}/reports/`
+- Temporary files → `.specweave/increments/{increment-id}/logs/`
+
+### Increment-Centric Organization
+
+**ALL work belongs to an INCREMENT**:
+
+```
+.specweave/increments/0001-user-auth/
+├── spec.md                      # WHAT & WHY
+├── plan.md                      # HOW
+├── tasks.md                     # Implementation steps
+├── tests.md                     # Test strategy
+├── context-manifest.yaml        # Selective loading
+├── logs/                        # ✅ Execution logs, errors, AI sessions
+│   ├── execution.log
+│   ├── errors.log
+│   └── ai-session.log
+├── scripts/                     # ✅ Helper scripts (migration, setup, validation)
+│   ├── migration.sql
+│   ├── setup.sh
+│   └── validation.py
+└── reports/                     # ✅ Analysis, completion, performance reports
+    ├── completion.md
+    ├── test-results.md
+    └── performance.md
+```
+
+**Benefits**:
+- ✅ Complete traceability (know which increment created which files)
+- ✅ Easy cleanup (delete increment folder = delete all related files)
+- ✅ Clear context (all files for a feature in one place)
+- ✅ No root clutter (project root stays clean)
+
+### Enforcement
+
+**When AI generates files**:
+
+1. **Identify current increment**: Which feature are you working on?
+2. **Create in increment folder**: `.specweave/increments/{id}/{type}/`
+3. **Never in root**: NEVER create supporting files in project root
+
+**Example**:
+```
+❌ WRONG:
+project-root/
+├── analysis-report.md          # NO! Pollutes root
+├── migration-script.py         # NO! Pollutes root
+└── execution.log               # NO! Pollutes root
+
+✅ CORRECT:
+.specweave/increments/0001-user-auth/
+├── reports/analysis-report.md  # YES! Organized
+├── scripts/migration-script.py # YES! Organized
+└── logs/execution.log          # YES! Organized
+```
+
+---
+
+## Project Structure
+
+```
+{PROJECT_NAME}/
+├── .specweave/                  # SpecWeave framework
+│   ├── config.yaml              # Project configuration
+│   ├── docs/                    # 5-pillar documentation
+│   │   ├── internal/
+│   │   │   ├── strategy/        # Business specs (WHAT, WHY)
+│   │   │   ├── architecture/    # Technical design (HOW)
+│   │   │   ├── delivery/        # Guides, roadmap, CI/CD
+│   │   │   ├── operations/      # Runbooks, monitoring
+│   │   │   └── governance/      # Security, compliance
+│   │   └── public/              # Published docs
+│   ├── increments/              # Features (auto-numbered)
+│   │   └── 0001-feature-name/
+│   │       ├── spec.md          # WHAT & WHY
+│   │       ├── plan.md          # HOW
+│   │       ├── tasks.md         # Implementation steps
+│   │       ├── tests.md         # Test strategy
+│   │       ├── context-manifest.yaml  # Selective loading
+│   │       ├── logs/            # ✅ Execution logs, errors
+│   │       ├── scripts/         # ✅ Helper scripts
+│   │       └── reports/         # ✅ Analysis, reports
+│   └── tests/                   # Centralized test repository
+│
+├── .claude/                     # Installed agents/skills
+│   ├── agents/                  # Selective installation
+│   ├── skills/                  # Selective installation
+│   └── commands/                # Slash commands
+│
+├── CLAUDE.md                    # This file (ONLY file we add)
+└── src/                         # Your source code (unchanged)
+```
+
+---
+
+## Quick Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `/create-increment` | Create new feature | `/create-increment "user auth"` |
+| `/review-docs` | Review docs vs code | `/review-docs --increment=003` |
+| `/sync-github` | Sync to GitHub issues | `/sync-github` |
+
+**All commands adapt to your tech stack automatically**
+
+---
+
+## Working with Increments
+
+### Create New Feature
+
+```bash
+/create-increment "feature description"
+```
+
+**This creates**:
+- Auto-numbered folder (`.specweave/increments/000X-name/`)
+- spec.md (WHAT & WHY - PM agent)
+- plan.md (HOW - Architect agent)
+- tasks.md (Implementation steps)
+- tests.md (Test strategy - QA Lead agent)
+- context-manifest.yaml (Selective loading)
+
+### Status Progression
+
+```
+backlog → planned → in-progress → completed → closed
+```
+
+### WIP Limits
+
+- **Solo developer**: 1-2 increments in progress
+- **Small team (2-5)**: 2-3 increments in progress
+- **Large team (10+)**: 3-5 increments in progress
+
+---
+
+## Agents (Activate Automatically)
+
+**Strategic Agents** (installed for all projects):
+
+| Agent | Purpose | Activates When |
+|-------|---------|----------------|
+| `pm` | Requirements, user stories | Planning features |
+| `architect` | System design, ADRs | Technical design |
+| `security` | Threat modeling | Security review |
+| `qa-lead` | Test strategy | Testing |
+| `devops` | Infrastructure, deployment | Deployment needed |
+
+**Implementation Agents** (installed based on your tech stack):
+
+{#IF_PYTHON}
+- `python-backend` - Python APIs (FastAPI, Django)
+{#ENDIF}
+{#IF_NODEJS}
+- `nodejs-backend` - Node.js APIs (Express, NestJS)
+{#ENDIF}
+{#IF_NEXTJS}
+- `nextjs` - Next.js applications
+{#ENDIF}
+{#IF_FRONTEND}
+- `frontend` - React/Vue/Angular frontend
+{#ENDIF}
+
+**See**: `.claude/agents/` for all installed agents
+
+---
+
+## Skills (Activate Automatically)
+
+**Framework Skills** (always available):
+
+| Skill | Purpose | Activates When |
+|-------|---------|----------------|
+| `specweave-detector` | Auto-detect SpecWeave | Any request |
+| `increment-planner` | Plan increments/features | Creating increments/features |
+| `context-loader` | Load context selectively | Working on increments |
+| `skill-router` | Route to appropriate skill | Ambiguous requests |
+
+**Integration Skills** (optional, install when needed):
+
+| Skill | Purpose | Install Command |
+|-------|---------|-----------------|
+| `jira-sync` | Sync with JIRA | `npx specweave install jira-sync` |
+| `github-sync` | Sync with GitHub | `npx specweave install github-sync` |
+| `hetzner-provisioner` | Deploy to Hetzner | `npx specweave install hetzner-provisioner` |
+
+---
+
+## Documentation Philosophy
+
+**You chose**: {DOCUMENTATION_APPROACH}
+
+{#IF_COMPREHENSIVE}
+### Comprehensive Upfront Approach
+- Create complete specifications before coding (500-600+ pages)
+- All ADRs documented in advance
+- Full architecture and API contracts upfront
+- Best for: Enterprise, regulated industries, large teams
+{#ENDIF}
+
+{#IF_INCREMENTAL}
+### Incremental/Evolutionary Approach
+- Start with overview (10-20 pages)
+- Build documentation as you go (like Microsoft)
+- Add modules/specs as features are planned
+- Best for: Startups, MVPs, small teams, evolving requirements
+{#ENDIF}
+
+**Both approaches use the same framework and 5-pillar structure.**
+
+---
+
+## Testing
+
+**Four Levels of Test Cases**:
+
+1. **Specification** (`.specweave/docs/internal/strategy/`) - TC-0001 acceptance criteria
+2. **Feature** (`.specweave/increments/####/tests.md`) - Test coverage matrix
+3. **Skill** (`src/skills/{name}/test-cases/`) - 3+ YAML test cases
+4. **Code** (`tests/`) - Automated tests (Unit, Integration, E2E)
+
+**Requirements**:
+- ✅ E2E tests (Playwright/Cypress/etc.) when UI exists
+- ✅ >80% coverage for critical paths
+- ✅ Tests MUST tell the truth (no false positives)
+
+**See**: [Testing Strategy Guide](.specweave/docs/internal/delivery/guides/testing-strategy.md)
+
+---
+
+## Deployment
+
+**Deployment Target**: {DEPLOYMENT_TARGET}
+
+{#IF_HETZNER}
+**Platform**: Hetzner Cloud (cheapest option)
+**Configuration**: See `.specweave/config.yaml`
+**Secrets**: `.env` (gitignored)
+{#ENDIF}
+
+{#IF_AWS}
+**Platform**: AWS (enterprise)
+**Configuration**: See `.specweave/config.yaml`
+**Secrets**: AWS IAM credentials in `.env` (gitignored)
+{#ENDIF}
+
+{#IF_VERCEL}
+**Platform**: Vercel (best for Next.js)
+**Configuration**: See `.specweave/config.yaml`
+**Secrets**: Vercel token in `.env` (gitignored)
+{#ENDIF}
+
+{#IF_LOCAL}
+**Platform**: Local development (Docker Compose)
+**Configuration**: See `docker-compose.yml`
+{#ENDIF}
+
+**See**: [Deployment Guide](.specweave/docs/internal/delivery/guides/deployment-intelligence.md)
+
+---
+
+## Detailed Guides
+
+**For complete workflows, agents load guides from** `.specweave/docs/internal/delivery/guides/`:
+
+| Guide | Purpose |
+|-------|---------|
+| [increment-lifecycle.md](.specweave/docs/internal/delivery/guides/increment-lifecycle.md) | Complete increment management |
+| [development-workflow.md](.specweave/docs/internal/delivery/guides/development-workflow.md) | Greenfield and brownfield workflows |
+| [testing-strategy.md](.specweave/docs/internal/delivery/guides/testing-strategy.md) | Testing philosophy (4 levels) |
+| [deployment-intelligence.md](.specweave/docs/internal/delivery/guides/deployment-intelligence.md) | Deployment target detection |
+| [diagram-conventions.md](.specweave/docs/internal/delivery/guides/diagram-conventions.md) | C4 diagrams and Mermaid |
+
+**Agents automatically load relevant guides when needed** - you don't manage this manually.
+
+---
+
+## Context Precision (70%+ Token Reduction)
+
+**How it works**: Each increment has a `context-manifest.yaml` that specifies ONLY the specs/docs needed for that feature.
+
+**Example**:
+```yaml
+spec_sections:
+  - .specweave/docs/internal/strategy/auth/spec.md
+documentation:
+  - .specweave/docs/internal/architecture/auth-design.md
+  - .specweave/docs/internal/architecture/adr/0003-auth-method.md
+max_context_tokens: 10000
+```
+
+**Benefits**:
+- Load exactly what's needed (not everything)
+- 70%+ token reduction vs loading full specs
+- Scales to enterprise (500+ page specs)
+
+**Loaded by**: `context-loader` skill when working on increment
+
+---
+
+## Project-Specific Notes
+
+{#CUSTOM_NOTES}
+<!-- Add project-specific conventions, team workflows, deployment notes here -->
+{#ENDCUSTOM}
+
+---
+
+## Quick Start
+
+**Create your first feature**:
+```bash
+/create-increment "your feature description"
+```
+
+**Need help?**: Ask Claude to load the relevant guide, or ask about specific workflows.
+
+**SpecWeave Documentation**: https://specweave.dev
+
+---
+
+**Last Updated**: Auto-updated via SpecWeave hooks