specweave 0.1.0

package/src/templates/README.md.template

@@ -0,0 +1,240 @@
+# {{PROJECT_NAME}}
+
+> Created with [SpecWeave](https://github.com/specweave/specweave) - Spec-Driven Development Framework
+
+## What is this?
+
+This project uses SpecWeave for autonomous development:
+- **Framework-agnostic**: Works with ANY tech stack (TypeScript, Python, Go, Rust, Java, etc.)
+- **Intent-driven**: Describe what you want, SpecWeave builds it using YOUR stack
+- **Documentation-first**: Comprehensive docs generated before code
+- **Role-based agents**: PM, Architect, QA, DevOps agents work together
+- **Autonomous implementation**: Full features built with minimal intervention
+- **Cost-optimized**: Deploys to most cost-effective platform (Hetzner, AWS, Vercel, etc.)
+
+## Getting Started
+
+### 1. Describe What You Want to Build
+
+Simply describe your product vision (framework-agnostic):
+
+```
+"Create an event booking SaaS for barbers and sports facilities"
+"Build a task management API with real-time collaboration"
+"Create an e-commerce platform with payment processing"
+```
+
+### 2. SpecWeave Will:
+
+1. **Detect or ask for your tech stack**:
+   - Language: TypeScript, Python, Go, Rust, Java, etc.
+   - Framework: NextJS, Django, FastAPI, Spring Boot, Gin, etc.
+   - Database: PostgreSQL, MySQL, MongoDB, SQLite, etc.
+   - Platform: Hetzner ($12/mo), AWS ($25/mo), Vercel ($20/mo), etc.
+
+2. **Ask clarifying questions**:
+   - Payment processing needed?
+   - Expected users?
+   - Budget for hosting?
+
+3. **Create strategic analysis** (using YOUR detected stack):
+   - PM agent → Product strategy & user personas
+   - Architect agent → System design & ADRs (framework-specific)
+   - DevOps agent → Infrastructure plan (platform-specific)
+   - Security agent → Auth & data protection (framework-specific)
+   - QA agent → Test strategy (framework-specific tests)
+
+4. **Generate comprehensive documentation**:
+   - Product documentation in `.specweave/docs/`
+   - Architecture diagrams & decisions (using YOUR stack)
+   - All files contain WHAT + WHY + HOW
+
+5. **Create implementation tasks**:
+   - Detailed tasks with agent references (using YOUR stack)
+   - File paths and code snippets (in YOUR language)
+   - Acceptance criteria (framework-specific)
+
+6. **Build autonomously**:
+   - Implements all features using YOUR detected tech stack
+   - Asks for approval when needed
+   - Suggests doc updates during implementation
+
+### 3. Review & Approve
+
+Before implementation starts:
+
+```
+/review-docs
+```
+
+This shows:
+- Product strategy
+- System architecture
+- Infrastructure plan & costs
+- Security approach
+- Test strategy
+
+### 4. Deploy
+
+SpecWeave deploys to the most cost-effective platform for YOUR needs:
+- **Hetzner Cloud**: $11-27/month (best for cost-sensitive projects)
+- **Vercel**: $20/month (best for global edge, NextJS apps)
+- **AWS**: $25-100+/month (best for enterprise, specific services)
+- **Self-hosted**: Variable (best for full control)
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── .specweave/
+│   ├── increments/        # Product increments (user stories, tasks)
+│   ├── docs/              # Generated documentation
+│   ├── tests/             # SpecWeave-generated tests
+│   └── config.yaml        # Configuration
+├── src/
+│   ├── skills/            # AI agent skills (17+ installed)
+│   └── hooks/             # Automation hooks
+├── .claude/
+│   ├── hooks/             # Claude Code hooks
+│   ├── commands/          # Manual commands
+│   └── skills/            # Installed skills
+└── CLAUDE.md              # Instructions for Claude
+```
+
+## Commands
+
+### Claude Code Commands
+
+Use these in Claude Code CLI:
+
+- `/create-increment "Feature name"` - Create new increment
+- `/review-docs` - Review strategic documentation
+- `/sync-github` - Sync to GitHub issues
+
+### Terminal Commands
+
+```bash
+# Create new increment
+npx specweave increment create "Add payment processing"
+
+# Install a skill
+npx specweave install hetzner-provisioner
+
+# Install hooks
+npx specweave install-hooks
+```
+
+## Examples
+
+### Example 1: Event Booking SaaS (TypeScript/NextJS)
+
+**Input**:
+```
+"Create event booking SaaS for barbers and sports facilities"
+```
+
+**Detected stack**: TypeScript, NextJS, PostgreSQL, Hetzner
+
+**Output**:
+- NextJS 14 app with App Router
+- Postgres database with Prisma
+- Calendar/booking system
+- Stripe payments
+- Email/SMS notifications
+- Deployed on Hetzner for $12/month
+- Complete documentation
+
+**Time**: Autonomous (with periodic approvals)
+
+### Example 2: Task Management API (Python/FastAPI)
+
+**Input**:
+```
+"Build a task management API with real-time collaboration"
+```
+
+**Detected stack**: Python, FastAPI, PostgreSQL, AWS
+
+**Output**:
+- FastAPI backend with WebSocket support
+- PostgreSQL with SQLAlchemy
+- Real-time task updates
+- User authentication (JWT)
+- Deployed on AWS for $27/month
+- Complete documentation
+
+**Time**: Autonomous (with periodic approvals)
+
+### Example 3: E-commerce Platform (Go/Gin)
+
+**Input**:
+```
+"Create an e-commerce platform with payment processing"
+```
+
+**Detected stack**: Go, Gin, PostgreSQL, Hetzner
+
+**Output**:
+- Gin API with microservices architecture
+- PostgreSQL with GORM
+- Product catalog, cart, checkout
+- Stripe integration
+- Deployed on Hetzner for $18/month
+- Complete documentation
+
+**Time**: Autonomous (with periodic approvals)
+
+## Available Skills
+
+### Infrastructure
+- `hetzner-provisioner` - Deploy to Hetzner Cloud ($10-15/mo)
+- `cost-optimizer` - Compare platforms & recommend cheapest
+
+### Frontend
+- `nextjs-agent` - NextJS 14 with App Router, TypeScript
+- `tailwind-designer` - Tailwind CSS styling
+
+### Backend
+- `nodejs-backend` - Node.js implementation
+- `python-backend` - Python implementation
+- `prisma-schema-builder` - Database schema with Prisma
+
+### Domain-Specific
+- `stripe-integrator` - Payment processing
+- `calendar-system` - Booking/scheduling
+- `notification-system` - Email & SMS
+- `auth-implementer` - Authentication (NextAuth, Clerk)
+
+### Strategic
+- `pm-agent` - Product strategy
+- `architect-agent` - System design
+- `qa-lead-agent` - Test strategy
+- `devops-agent` - Infrastructure planning
+- `security-agent` - Security review
+
+See `src/skills/` for complete list.
+
+## Configuration
+
+Edit `.specweave/config.yaml`:
+
+```yaml
+cost:
+  max_monthly_budget: 100  # USD
+  preferred_platform: hetzner
+
+testing:
+  e2e_required: true
+  coverage_target: 80
+```
+
+## Learn More
+
+- [SpecWeave Documentation](https://github.com/specweave/specweave)
+- [Example Projects](https://github.com/specweave/examples)
+- [Community](https://github.com/specweave/specweave/discussions)
+
+## License
+
+This project: [Your License]
+SpecWeave: MIT License

package/src/templates/config.yaml

@@ -0,0 +1,333 @@
+---
+# SpecWeave Configuration
+project:
+  name: {{PROJECT_NAME}}
+  version: 0.1.0
+  created: {{DATE}}
+
+# Tech Stack (CRITICAL - detected or specified)
+tech_stack:
+  # For single-stack projects (most common)
+  detected_from: "auto"  # auto-detect from project files, or specify source
+  language: "{{DETECTED_LANGUAGE}}"        # e.g., typescript, python, go, rust, java, csharp
+  framework: "{{DETECTED_FRAMEWORK}}"      # e.g., nextjs, django, fastapi, spring-boot, gin
+  database: "{{SPECIFIED_DATABASE}}"       # e.g., postgresql, mysql, mongodb, sqlite
+  orm: "{{DETECTED_ORM}}"                  # e.g., prisma, django-orm, sqlalchemy, hibernate, gorm
+  ui_library: "{{SPECIFIED_UI}}"           # e.g., tailwind, material-ui, bootstrap (optional)
+
+  # Auto-detection rules (SpecWeave uses these to detect stack)
+  detection:
+    enabled: true
+    sources:
+      - .specweave/config.yaml  # This file (highest priority)
+      - package.json            # TypeScript/JavaScript
+      - requirements.txt        # Python
+      - pyproject.toml          # Python (Poetry, etc.)
+      - go.mod                  # Go
+      - Cargo.toml              # Rust
+      - pom.xml                 # Java (Maven)
+      - build.gradle            # Java (Gradle)
+      - "*.csproj"              # C#/.NET
+
+# Monorepo Configuration (OPTIONAL - only for multi-service projects)
+monorepo:
+  enabled: false  # Set to true for monorepo projects with multiple services
+
+  # Define each service with its own tech stack
+  services:
+    # Example: Frontend service
+    # client:
+    #   path: client/                    # Service directory
+    #   language: typescript
+    #   framework: nextjs
+    #   ui_library: tailwind
+    #   platform: vercel
+
+    # Example: Backend service
+    # server:
+    #   path: server/
+    #   language: python
+    #   framework: fastapi
+    #   database: postgresql
+    #   orm: sqlalchemy
+    #   platform: hetzner
+
+    # Example: ML/Analytics service
+    # ml:
+    #   path: ml/
+    #   language: python
+    #   framework: tensorflow
+    #   database: mongodb
+    #   platform: aws-sagemaker
+
+    # Example: Mobile service
+    # mobile:
+    #   path: mobile/
+    #   language: typescript
+    #   framework: react-native
+    #   platform: expo
+
+  # Service-aware routing (agents adapt based on file path)
+  service_routing:
+    enabled: true  # Agents automatically detect which service they're working on
+    default_service: null  # Default service if path doesn't match any (optional)
+
+# Platform Configuration
+platform:
+  provider: "auto"  # auto (cost-optimizer recommends), hetzner, aws, vercel, self-hosted
+  region: "auto"    # auto, eu-central, us-east, ap-southeast, etc.
+
+  # Cost optimization (used by cost-optimizer skill)
+  cost:
+    max_monthly_budget: 100  # USD
+    alert_threshold: 80      # Alert at 80% of budget
+    alerts_enabled: true
+
+# Hooks configuration
+hooks:
+  enabled: true
+  sounds:
+    enabled: true
+    completion: /System/Library/Sounds/Glass.aiff
+    input_required: /System/Library/Sounds/Ping.aiff
+
+  post_task_completion:
+    enabled: true
+    actions:
+      - update_documentation
+      - update_claude_md
+      - update_changelog
+
+# Documentation structure (5-pillar)
+docs:
+  structure: features  # or "modules" - adapts to your project
+  auto_update: true
+  approach: incremental  # or "comprehensive" for enterprise/production
+
+  # 5-pillar structure
+  internal:
+    strategy_enabled: true       # .specweave/docs/internal/strategy/
+    architecture_enabled: true   # .specweave/docs/internal/architecture/
+    delivery_enabled: true       # .specweave/docs/internal/delivery/
+    operations_enabled: false    # .specweave/docs/internal/operations/ (optional)
+    governance_enabled: false    # .specweave/docs/internal/governance/ (optional)
+
+  public:
+    enabled: true                # .specweave/docs/public/
+    auto_publish: false          # Auto-publish to docs site
+
+# Role-based agents (framework-agnostic)
+agents:
+  models:
+    # All agents use Claude Sonnet 4.5 (best for coding and complex agents)
+    pm: claude-sonnet-4-5-20250929
+    architect: claude-sonnet-4-5-20250929
+    security: claude-sonnet-4-5-20250929
+    qa_lead: claude-sonnet-4-5-20250929
+    devops: claude-sonnet-4-5-20250929
+    tech_lead: claude-sonnet-4-5-20250929
+    sre: claude-sonnet-4-5-20250929
+
+    # Implementation agents (use framework-specific agents based on detected stack)
+    backend: claude-sonnet-4-5-20250929      # nodejs-backend, python-backend, dotnet-backend, etc.
+    frontend: claude-sonnet-4-5-20250929     # frontend, nextjs, etc.
+
+  # Agents receive detected tech stack automatically
+  pass_tech_stack: true
+
+# Role orchestrator configuration
+role_orchestrator:
+  enabled: true
+
+  # Orchestration strategy
+  default_pattern: sequential_with_gates  # or "parallel" or "adaptive"
+
+  # Quality gates
+  require_user_approval:
+    - architecture_decisions
+    - deployment_to_production
+
+  require_automated_approval:
+    - test_coverage: ">80%"
+    - security_scan: "no_critical"
+
+  # Feedback loop configuration (auto-refinement)
+  feedback_loops:
+    enabled: true              # Enable auto-refinement
+    max_retries: 3             # Max refinement attempts per agent
+    stop_on_improvement: true  # Stop if score improves significantly
+    require_user_approval: false  # Auto-refine without asking
+
+    # Quality thresholds per agent
+    thresholds:
+      pm_agent: 0.80           # Requirements quality
+      architect_agent: 0.80    # Design quality
+      qa_lead_agent: 0.75      # Test coverage + quality
+
+    # Which agents use feedback loops
+    agents:
+      - pm_agent
+      - architect_agent
+      - qa_lead_agent
+      # Not applicable for implementation agents (code is validated by tests)
+
+    # Validation strategy
+    validation:
+      use_llm_judge: true      # Use increment-quality-judge
+      combine_with_rules: true # Combine with rule-based checks
+      judge_weight: 0.5        # 50% LLM judge, 50% rules
+
+  # Agent preferences (for tech stack selection)
+  preferred_backend: nodejs-backend   # or python-backend, dotnet-backend
+  preferred_frontend: frontend        # or nextjs
+
+  # Timeouts
+  phase_timeout_minutes: 30
+  total_timeout_hours: 8
+
+  # Monitoring
+  progress_updates_interval: 5min
+  store_metrics: true
+
+# Testing (framework-agnostic)
+testing:
+  e2e_required: true       # Mandatory E2E tests when UI exists
+  coverage_target: 80      # Target coverage percentage
+  baseline_required: false # For brownfield projects
+
+  # Framework-specific test frameworks (auto-detected)
+  frameworks:
+    typescript: ["playwright", "jest"]        # E2E + unit
+    python: ["pytest", "django-tests"]        # E2E + unit
+    go: ["go test", "testify"]                # Unit + assertions
+    java: ["junit", "spring-boot-test"]       # Unit + integration
+    rust: ["cargo test"]                      # Unit
+
+  # Test levels (4-level strategy)
+  levels:
+    spec_acceptance: true      # Level 1: TC-0001 in specs
+    feature_strategy: true     # Level 2: Test coverage matrix
+    skill_tests: true          # Level 3: Skill YAML tests
+    code_tests: true           # Level 4: Automated tests
+
+# Context loading (70%+ token reduction)
+context:
+  enabled: true
+  max_tokens: 10000           # Max tokens per context load
+  auto_refresh: false         # Auto-refresh context when specs change
+  cache_enabled: true         # Cache embeddings for faster loading
+
+# Context optimizer (second-pass optimization, 80%+ total reduction)
+context_optimizer:
+  enabled: true
+  auto_optimize: true         # Auto-run after context-loader
+  min_context_tokens: 20000   # Only optimize if context > 20k tokens
+  min_confidence: 0.75        # Skip if intent analysis confidence < 75%
+  show_removals: true         # Show what was removed
+  buffer_strategy: conservative  # conservative or aggressive
+
+  # Custom domains (project-specific)
+  custom_domains: []
+    # - "real-time-chat"
+    # - "analytics"
+    # - "reporting"
+
+  # Always keep (never remove)
+  always_keep:
+    - "architecture/README.md"
+    - "CLAUDE.md"
+
+# Validation configuration
+validation:
+  # Rule-based validation (120 rules, always enabled)
+  rule_based:
+    enabled: true
+    rules_count: 120
+
+  # LLM-as-judge quality assessment (optional, uses ~2k tokens)
+  quality_judge:
+    enabled: true             # Enable feature
+    auto_prompt: true         # Prompt user after rule-based validation
+    always_run: false         # Run automatically without prompting
+
+    # Scoring thresholds
+    thresholds:
+      excellent: 90           # ✓✓ (90-100)
+      good: 80                # ✓  (80-89)
+      acceptable: 70          # ~  (70-79)
+      needs_work: 0           # ⚠️ (0-69)
+
+    # Which dimensions to evaluate
+    dimensions:
+      clarity: true
+      testability: true
+      completeness: true
+      feasibility: true
+      maintainability: true
+      edge_cases: true
+
+    # Token budget
+    max_tokens: 2000          # Limit for quality check
+
+    # Auto-export suggestions
+    export_to_tasks: true     # Add suggestions to tasks.md
+
+    # Confidence threshold
+    min_confidence: 0.80      # Show warning if lower
+
+# Integrations (framework-agnostic)
+integrations:
+  github:
+    enabled: false
+    sync_issues: false
+    auto_create_pr: false
+
+  jira:
+    enabled: false
+    sync_issues: false
+
+  ado:
+    enabled: false
+    sync_work_items: false
+
+  slack:
+    enabled: false
+    notifications: false
+
+# Brownfield settings
+brownfield:
+  enabled: false              # Set to true if modifying existing codebase
+  require_baseline_tests: true  # Require tests before modification
+  require_documentation: true   # Require docs before modification
+  auto_analyze: true           # Auto-analyze code with brownfield-analyzer
+
+# Autonomous mode settings
+autonomous:
+  enabled: false              # Full autonomous mode
+  interruptions: minimal      # minimal, moderate, frequent
+  batch_questions: true       # Batch clarifying questions
+  auto_approve_docs: false    # Auto-approve strategic docs (risky!)
+
+# Skills configuration
+skills:
+  enabled: true
+  auto_route: true            # Auto-route to appropriate skills
+
+  # Skill priorities
+  core:
+    - specweave-detector
+    - skill-router
+    - role-orchestrator
+    - context-loader
+    - increment-planner
+
+  infrastructure:
+    - hetzner-provisioner      # If platform=hetzner
+    - cost-optimizer
+
+  integration:
+    - github-sync              # If integrations.github.enabled
+    - jira-sync                # If integrations.jira.enabled
+    - ado-sync                 # If integrations.ado.enabled
+
+---

package/src/templates/docs/README.md

@@ -0,0 +1,124 @@
+# Document Templates
+
+This directory contains templates for all standard document types in the PRD/HLD/RFC/Runbook pattern.
+
+## Available Templates
+
+### Strategy Documents
+- **`prd-template.md`** - Product Requirements Document
+  - **Purpose**: Define the "why" - problem, users, success metrics
+  - **Location**: `docs/internal/strategy/prd-{feature}.md`
+  - **Usage**: `cp templates/docs/prd-template.md docs/internal/strategy/prd-{feature}.md`
+
+### Architecture Documents
+- **`hld-template.md`** - High-Level Design
+  - **Purpose**: Define the "what" - system design, components, data model
+  - **Location**: `docs/internal/architecture/hld-{system}.md`
+  - **Usage**: `cp templates/docs/hld-template.md docs/internal/architecture/hld-{system}.md`
+
+- **`adr-template.md`** - Architecture Decision Record
+  - **Purpose**: Document architectural decisions with rationale
+  - **Location**: `docs/internal/architecture/adr/0001-decision-title.md`
+  - **Format**: Sequential numbering (0001, 0002, etc.)
+  - **Usage**:
+    ```bash
+    # Find next number
+    NEXT=$(printf "%04d" $(($(ls docs/internal/architecture/adr/ | grep -E '^[0-9]{4}' | tail -1 | cut -d'-' -f1) + 1)))
+    cp templates/docs/adr-template.md docs/internal/architecture/adr/${NEXT}-decision-title.md
+    ```
+
+- **`rfc-template.md`** - Request for Comments
+  - **Purpose**: Propose API designs, schema changes, major features
+  - **Location**: `docs/internal/architecture/rfc/0001-feature-title.md`
+  - **Format**: Sequential numbering (0001, 0002, etc.)
+  - **Usage**:
+    ```bash
+    # Find next number
+    NEXT=$(printf "%04d" $(($(ls docs/internal/architecture/rfc/ | grep -E '^[0-9]{4}' | tail -1 | cut -d'-' -f1) + 1)))
+    cp templates/docs/rfc-template.md docs/internal/architecture/rfc/${NEXT}-feature-title.md
+    ```
+
+### Operations Documents
+- **`runbook-template.md`** - Operations Runbook
+  - **Purpose**: Step-by-step procedures for running and maintaining services
+  - **Location**: `docs/internal/operations/runbook-{service}.md`
+  - **Usage**: `cp templates/docs/runbook-template.md docs/internal/operations/runbook-{service}.md`
+
+## Quick Start
+
+### Creating a New Feature (Complete Workflow)
+
+1. **Create PRD** (Strategy):
+   ```bash
+   cp templates/docs/prd-template.md docs/internal/strategy/prd-booking-system.md
+   # Fill in: Problem, Users, Success Metrics, Scope
+   ```
+
+2. **Create HLD** (Architecture):
+   ```bash
+   cp templates/docs/hld-template.md docs/internal/architecture/hld-booking-system.md
+   # Fill in: Architecture, Data Model, Integrations
+   ```
+
+3. **Create ADR** (if architectural decision needed):
+   ```bash
+   NEXT=$(printf "%04d" $(($(ls docs/internal/architecture/adr/ 2>/dev/null | grep -E '^[0-9]{4}' | tail -1 | cut -d'-' -f1 | sed 's/^0*//' || echo 0) + 1)))
+   cp templates/docs/adr-template.md docs/internal/architecture/adr/${NEXT}-use-postgresql.md
+   ```
+
+4. **Create RFC** (for API design):
+   ```bash
+   NEXT=$(printf "%04d" $(($(ls docs/internal/architecture/rfc/ 2>/dev/null | grep -E '^[0-9]{4}' | tail -1 | cut -d'-' -f1 | sed 's/^0*//' || echo 0) + 1)))
+   cp templates/docs/rfc-template.md docs/internal/architecture/rfc/${NEXT}-booking-api.md
+   ```
+
+5. **Create Runbook** (Operations):
+   ```bash
+   cp templates/docs/runbook-template.md docs/internal/operations/runbook-booking-service.md
+   # Fill in: SLOs, Procedures, Escalation
+   ```
+
+## Template Usage Guidelines
+
+### Fill in ALL Sections
+- Do not leave template placeholders (e.g., `[Feature Name]`, `YYYY-MM-DD`)
+- Replace all `@name`, `@team` with actual names
+- Fill in all checklists
+
+### Update Status
+- Start with `status: draft`
+- Move to `status: review` when ready for PR
+- Change to `status: approved` when merged
+- Use `status: deprecated` when superseded
+
+### Cross-Link Documents
+- PRD → HLD (link from PRD to HLD)
+- HLD → ADR (link to all relevant ADRs)
+- RFC → HLD (link from RFC to HLD)
+- Runbook → HLD (link from runbook to architecture)
+
+### Use Diagrams
+- Use Mermaid for diagrams (supported in Markdown)
+- Export to PNG for presentations if needed
+- Keep diagrams simple and clear
+
+### Review and Approval
+- Create PR for all new documents
+- Tag appropriate reviewers (see CODEOWNERS)
+- Address feedback before merging
+- Update status after approval
+
+## Customizing Templates
+
+You can customize these templates for your project:
+
+1. **Add sections** relevant to your domain
+2. **Remove sections** not applicable
+3. **Adjust approval process** to match your workflow
+4. **Update cross-links** to match your structure
+
+## Related Documentation
+
+- [docs/README.md](../../docs/README.md) - Documentation structure
+- [docs/internal/README.md](../../docs/internal/README.md) - Internal documentation guide
+- [CLAUDE.md](../../CLAUDE.md) - Complete development guide