specweave 0.1.9 → 0.3.1

package/src/skills/ado-sync/README.md

@@ -95,13 +95,7 @@ As a user, I want to subscribe to a monthly plan...
 ## Authentication
 
 **Personal Access Token (PAT)**:
-```yaml
-# .specweave/config.yaml
-ado_sync:
-  url: "https://dev.azure.com/your-org"
-  project: "YourProject"
-  pat: "${ADO_PAT}"  # From environment variable
-```
+
 
 **OAuth 2.0** (for apps):
 ```yaml
@@ -115,36 +109,7 @@ ado_sync:
 
 ## Configuration
 
-```yaml
-# .specweave/config.yaml
-ado_sync:
-  enabled: false
-
-  # ADO instance
-  url: "https://dev.azure.com/your-org"
-  project: "YourProject"
-
-  # Authentication (use environment variables!)
-  pat: "${ADO_PAT}"
 
-  # Sync settings
-  sync_direction: "bidirectional"  # export | import | bidirectional
-  sync_interval: 300  # seconds (5 minutes)
-
-  # What to sync
-  sync_status: true
-  sync_comments: true
-  sync_assignees: true
-  sync_attachments: false
-
-  # Work item mapping
-  area_path: "Platform"  # Default area path
-  iteration_path: null  # Auto-detect from current sprint
-
-  # Webhooks (for real-time sync)
-  webhook_enabled: true
-  webhook_secret: "${ADO_WEBHOOK_SECRET}"
-```
 
 ## Workflow
 

package/src/skills/bmad-method-expert/SKILL.md

@@ -219,7 +219,6 @@ When you request gap analysis, I will:
 ```bash
 # Project structure
 - CLAUDE.md (complete guide)
-- .specweave/config.yaml (configuration)
 - features/ (implemented features)
 - src/skills/ (available skills)
 - specifications/ (spec organization)
@@ -290,7 +289,7 @@ Based on analysis, provide:
    - Check features/ for implemented capabilities
    - Read src/skills/ for available skills
    - Review CLAUDE.md for documented features
-   - Check .specweave/config.yaml for configuration
+   - Settings auto-detected
    ```
 
 2. Compare to BMAD knowledge:
@@ -530,7 +529,6 @@ When performing gap analysis, I can read and analyze:
 ```bash
 # Core configuration
 ✅ CLAUDE.md                          # Complete guide
-✅ .specweave/config.yaml            # Configuration
 ✅ README.md                         # Project overview
 
 # Features

package/src/skills/brownfield-analyzer/SKILL.md

@@ -13,12 +13,61 @@ description: Analyzes existing brownfield projects to map documentation structur
 
 ## Capabilities
 
-1. **Scan Project Structure** - Recursively scan folders for documentation
-2. **Classify Documents** - Identify PRD, HLD, ADR, RFC, Runbook candidates
-3. **Detect External Tools** - Find Jira, ADO, GitHub project references
-4. **Analyze Diagrams** - Identify architecture diagrams (PNG, SVG, drawio)
-5. **Generate Migration Plan** - Create actionable migration plan with effort estimate
-6. **Suggest Increment Mapping** - Map Jira Epics/ADO Features to SpecWeave Increments
+1. **Assess Project Complexity** - Estimate LOC, files, modules and recommend documentation path 🆕
+2. **Scan Project Structure** - Recursively scan folders for documentation
+3. **Classify Documents** - Identify PRD, HLD, ADR, RFC, Runbook candidates
+4. **Detect External Tools** - Find Jira, ADO, GitHub project references
+5. **Analyze Diagrams** - Identify architecture diagrams (PNG, SVG, drawio)
+6. **Generate Migration Plan** - Create actionable migration plan with effort estimate
+7. **Suggest Increment Mapping** - Map Jira Epics/ADO Features to SpecWeave Increments
+8. **Support Two Paths** - Quick Start (incremental) OR Comprehensive (upfront) 🆕
+
+---
+
+## Two-Path Strategy 🆕
+
+**SpecWeave supports two brownfield approaches**:
+
+### Path 1: Quick Start (Incremental Documentation)
+**Best for**: Large projects (50k+ LOC), fast iteration, small teams
+
+**Process**:
+1. Initial scan: Document core architecture only (1-3 hours)
+2. Start working immediately
+3. Per increment: Document → Modify → Update docs
+4. Documentation grows with changes
+
+**Benefits**:
+- Start in days, not weeks
+- Focus documentation where it matters
+- No analysis paralysis
+- Always safe (document before touching code)
+
+### Path 2: Comprehensive Upfront
+**Best for**: Small/medium projects (<50k LOC), teams, regulated industries
+
+**Process**:
+1. Full codebase analysis (1-4 weeks)
+2. Document all modules, business rules
+3. Create complete baseline tests
+4. Then start increments with full context
+
+**Benefits**:
+- Complete context upfront
+- Full regression coverage
+- Easier team coordination
+- Better for compliance
+
+### Automatic Path Recommendation
+
+The analyzer **automatically recommends** a path based on:
+
+| Project Size | LOC Range | Upfront Effort | Recommended Path |
+|--------------|-----------|----------------|------------------|
+| **Small** | < 10k LOC | 4-8 hours | Comprehensive Upfront |
+| **Medium** | 10k-50k LOC | 1-2 weeks | User Choice |
+| **Large** | 50k-200k LOC | 2-4 weeks | Quick Start |
+| **Very Large** | 200k+ LOC | 1-3 months | Quick Start (Mandatory) |
 
 ---
 
@@ -37,9 +86,128 @@ description: Analyzes existing brownfield projects to map documentation structur
 
 ## Analysis Process
 
+### Step 0: Complexity Assessment 🆕
+
+**FIRST, estimate project size to recommend path**:
+
+**Metrics to collect**:
+```typescript
+interface ComplexityMetrics {
+  totalLOC: number;              // Lines of code
+  totalFiles: number;            // Number of files
+  languages: string[];           // Programming languages detected
+  modules: number;               // Estimated number of modules
+  dependencies: number;          // External dependencies
+  testCoverage: number;          // Existing test coverage (%)
+  documentationFiles: number;    // Existing docs
+  diagramsFound: number;         // Existing diagrams
+  externalTools: string[];       // Jira, ADO, GitHub detected
+}
+```
+
+**LOC Estimation Commands**:
+```bash
+# Count LOC by language (exclude vendor/node_modules/dist)
+cloc . --exclude-dir=node_modules,vendor,dist,build,.git
+
+# Or use tokei (faster)
+tokei
+
+# Or manual approach
+find . -name "*.ts" -o -name "*.js" | xargs wc -l
+```
+
+**Complexity Scoring**:
+```typescript
+function assessComplexity(metrics: ComplexityMetrics): ComplexityAssessment {
+  const score = calculateScore(metrics);
+
+  if (metrics.totalLOC < 10_000) {
+    return {
+      size: "Small",
+      effort: "4-8 hours",
+      recommendedPath: "Comprehensive Upfront",
+      confidence: "High"
+    };
+  } else if (metrics.totalLOC < 50_000) {
+    return {
+      size: "Medium",
+      effort: "1-2 weeks",
+      recommendedPath: "User Choice (Ask preference)",
+      confidence: "Medium"
+    };
+  } else if (metrics.totalLOC < 200_000) {
+    return {
+      size: "Large",
+      effort: "2-4 weeks",
+      recommendedPath: "Quick Start",
+      confidence: "High"
+    };
+  } else {
+    return {
+      size: "Very Large",
+      effort: "1-3 months",
+      recommendedPath: "Quick Start (Mandatory)",
+      confidence: "Critical"
+    };
+  }
+}
+```
+
+**Output to User**:
+```
+🔍 Analyzing project complexity...
+
+Metrics:
+  • 85,420 LOC detected
+  • 342 files analyzed
+  • Languages: TypeScript (65%), JavaScript (30%), CSS (5%)
+  • Estimated modules: 12
+  • Test coverage: 45%
+  • Existing docs: 23 files
+  • External tools: Jira (PROJ-*)
+
+Complexity Assessment: LARGE PROJECT
+  • Size: Large (85k LOC)
+  • Full analysis effort: 2-3 weeks
+  • Recommended path: Quick Start
+
+Recommendation:
+  ✓ Document core architecture only (2-3 hours)
+  ✓ Start working immediately
+  ✓ Document incrementally per feature
+  → Avoid 2-3 week upfront analysis
+
+Alternative:
+  ⚠️  Comprehensive upfront (2-3 weeks)
+  → Only if you need full context before starting
+
+Proceed with Quick Start? (y/n)
+```
+
+---
+
 ### Step 1: Initial Scan
 
-**Scan these patterns**:
+**Scan depth depends on chosen path**:
+
+#### Quick Start Path:
+**Scan ONLY for**:
+- Core architecture files (`architecture/**/*.md`)
+- Main README files
+- Tech stack indicators (`package.json`, `requirements.txt`, `.csproj`)
+- High-level business domains (folder structure)
+- Critical patterns (auth, payment, security)
+
+**Skip detailed**:
+- Individual module documentation
+- Detailed business rules
+- Code-level documentation
+
+**Result**: High-level understanding (1-3 hours)
+
+#### Comprehensive Path:
+**Scan ALL patterns**:
 ```
 docs/**/*.md
 documentation/**/*.md
@@ -184,17 +352,140 @@ build/**
 
 ## Output: Analysis Report
 
-**Generate markdown report**:
+**Generate markdown report** (path-specific):
+
+### Quick Start Report
 
 ```markdown
-# Brownfield Analysis Report
+# Brownfield Analysis Report - Quick Start Mode
 
 **Project**: {project-name}
 **Analyzed**: {date}
+**Mode**: Quick Start (Incremental Documentation)
+
+---
+
+## Complexity Assessment 🆕
+
+**Project Size**: {size} ({LOC} LOC)
+**Files Analyzed**: {count}
+**Languages**: {languages}
+**Modules Detected**: {count}
+**Test Coverage**: {percentage}%
+
+**Upfront Effort Estimate**:
+- Quick Start: **2-3 hours** (Core concepts only)
+- Comprehensive: ~{weeks} weeks (Full documentation)
+
+**Recommended Path**: Quick Start
+
+**Why Quick Start?**
+- Large codebase would take {weeks} to fully document
+- Start delivering value in days, not weeks
+- Document as you modify code (safer, focused)
+
+---
+
+## Core Architecture Extracted
+
+**High-Level Components**:
+- {Component 1}: {Brief description}
+- {Component 2}: {Brief description}
+- {Component 3}: {Brief description}
+
+**Critical Patterns Identified**:
+- Authentication: {pattern}
+- Authorization: {pattern}
+- Data Flow: {pattern}
+- Error Handling: {pattern}
+
+**Tech Stack**:
+- Frontend: {frameworks}
+- Backend: {frameworks}
+- Database: {databases}
+- Infrastructure: {platform}
+
+**Business Domains** (detected from folder structure):
+- `src/{domain1}/` - {estimated purpose}
+- `src/{domain2}/` - {estimated purpose}
+- `src/{domain3}/` - {estimated purpose}
+
+---
+
+## External Tools Detected
+
+- **Jira**: {url} ({count} active epics)
+- **GitHub**: {repo} ({count} open issues)
+
+---
+
+## Recommended Next Steps (Quick Start)
+
+1. ✅ **Review this report** (5 minutes)
+2. ✅ **Create `.specweave/` structure** (5 minutes)
+3. ✅ **Document core architecture** (1-2 hours)
+   - Create `.specweave/docs/internal/architecture/core-architecture.md`
+   - Document high-level components from above
+4. ✅ **Start first increment** (immediate)
+   - Choose feature to implement/modify
+   - Document affected code BEFORE modifying
+   - Implement with regression tests
+   - Update docs AFTER change
+
+**Total Time to Start**: 2-3 hours
+
+**Per-Increment Pattern**:
+```
+1. Document affected code (30 min)
+2. Add regression tests (30 min)
+3. Implement change (varies)
+4. Update docs (20 min)
+```
+
+---
+
+## Skipped in Quick Start Mode
+
+The following will be documented **per increment** as needed:
+- Detailed module documentation
+- Complete business rules catalog
+- Full API documentation
+- Comprehensive test coverage
+
+**This is intentional** - focuses effort where it matters.
+
+---
+
+## Alternative: Switch to Comprehensive
+
+If you prefer full upfront documentation:
+- Run: `brownfield-analyzer --comprehensive`
+- Effort: ~{weeks} weeks
+- Result: Complete specs before any code changes
+
+---
+```
+
+### Comprehensive Report
+
+```markdown
+# Brownfield Analysis Report - Comprehensive Mode
+
+**Project**: {project-name}
+**Analyzed**: {date}
+**Mode**: Comprehensive (Upfront Documentation)
 **Total Files Scanned**: {count}
 
 ---
 
+## Complexity Assessment 🆕
+
+**Project Size**: {size} ({LOC} LOC)
+**Recommended**: {path}
+**Estimated Effort**: {weeks}
+
+---
+
 ## Executive Summary
 
 - **Documentation Files**: {count} markdown files found
@@ -302,9 +593,8 @@ build/**
 3. Link increments to related docs (PRD, HLD, ADR, RFC)
 
 ### Phase 5: External Tool Sync ({X} hours)
-1. Configure `.specweave/config.yaml` with Jira/ADO credentials
-2. Run initial sync to link Epics → Increments
-3. Verify all Epics are mapped
+1. Run sync command to link Epics → Increments (credentials auto-detected or prompted)
+2. Verify all Epics are mapped
 
 ### Phase 6: Verification (30 minutes)
 1. Run `specweave verify`
@@ -336,7 +626,7 @@ build/**
    ```bash
    specweave migrate --plan analysis-report.md --execute
    ```
-5. **Enable sync** - Configure Jira/ADO sync in `.specweave/config.yaml`
+5. **Enable sync** - Run sync commands for Jira/ADO integration
 
 ---
 
@@ -378,24 +668,138 @@ build/**
 ### Initial Request
 **User**: "Analyze my existing project at /path/to/project"
 
-### Your Response
+### Your Response (Step 1: Complexity Assessment) 🆕
+
 ```
-I'll analyze your existing project structure and generate a migration plan.
+I'll analyze your existing project to determine the best onboarding approach.
+
+Step 1: Assessing project complexity...
+
+Running: cloc . --exclude-dir=node_modules,vendor,dist
+
+🔍 Complexity Analysis:
+
+Metrics:
+  • 85,420 LOC detected
+  • 342 files analyzed
+  • Languages: TypeScript (55,273), JavaScript (25,147), CSS (5,000)
+  • Estimated modules: 12
+  • Test coverage: 45% (from coverage reports)
+  • Existing docs: 23 markdown files
+  • External tools: Jira (PROJ-*), GitHub
+
+Complexity Assessment: LARGE PROJECT
+  • Size: Large (85k LOC)
+  • Full analysis effort: 2-3 weeks
+  • Recommended path: Quick Start
+
+---
+
+Recommendation: QUICK START PATH
+
+Why?
+  ✓ Large codebase (85k LOC)
+  ✓ Full documentation would take 2-3 weeks
+  ✓ Start delivering value in 2-3 hours instead
+  ✓ Document incrementally as you modify code
+
+Quick Start Process:
+  1. Document core architecture only (2-3 hours)
+  2. Start first increment immediately
+  3. Per increment: Document → Modify → Update
+  4. Documentation grows with changes
+
+Alternative: Comprehensive Upfront
+  ⚠️  Full documentation (2-3 weeks)
+  → Only if you need complete context before starting
+
+---
+
+Which path do you prefer?
+1. Quick Start (recommended) - Start in 2-3 hours
+2. Comprehensive - Full analysis (2-3 weeks)
+3. Let me decide based on your recommendation
+
+```
+
+### User Chooses Quick Start
+
+```
+Great! I'll perform a Quick Start analysis focusing on core concepts.
+
+Step 2: Scanning for core architecture...
+
+Found:
+- 12 high-level modules
+- 4 critical patterns (auth, payment, data flow, error handling)
+- 23 existing markdown files
+- 8 diagrams
+- Jira project detected (PROJ) with 12 active epics
+
+Extracting core architecture... ✅
+
+I've generated a Quick Start analysis report. Here's the summary:
+
+**Core Architecture Extracted**:
+- API Gateway (routing, auth)
+- User Service (user management, profiles)
+- Payment Service (Stripe integration)
+- Notification Service (email/SMS)
+- Database Layer (PostgreSQL)
+
+**Critical Patterns**:
+- Auth: JWT tokens, refresh mechanism
+- Payment: Stripe webhooks, idempotency
+- Data Flow: Event-driven (Redis pub/sub)
+- Errors: Centralized error handler
+
+**Tech Stack**:
+- Frontend: Next.js 14, React, Tailwind
+- Backend: Node.js 20, Express, TypeScript
+- Database: PostgreSQL 16, Prisma ORM
+- Infrastructure: Docker, Hetzner Cloud
+
+**External Tools**: Jira (12 active epics) → Can map to increments
+
+**Estimated Time to Start**: 2-3 hours (document core architecture)
+
+---
+
+Next Steps:
+1. ✅ Create `.specweave/` structure (5 min)
+2. ✅ Document core architecture (2 hours) - I can help
+3. ✅ Start first increment (immediate)
+
+Should I:
+1. Create the SpecWeave structure and document core architecture?
+2. Show the full Quick Start report first?
+3. Map Jira epics to increments?
+```
+
+### User Chooses Comprehensive
+
+```
+Understood! I'll perform a comprehensive analysis of the entire codebase.
+
+⚠️  This will take some time for a project of this size.
+
+Step 2: Comprehensive scan...
 
 Scanning: /path/to/project
 
 Found:
-- 45 markdown files
+- 342 source files
+- 23 markdown files
 - 8 diagrams
 - Jira project detected (PROJ)
 
-Analyzing... (this may take a moment)
+Analyzing... (this may take a few minutes)
 
 ✅ Analysis complete!
 
 I've generated a comprehensive analysis report. Here's the summary:
 
-**Documentation**: 45 files classified
+**Documentation**: 23 files classified
 - PRD candidates: 3
 - HLD candidates: 2
 - ADR candidates: 8
@@ -405,15 +809,17 @@ I've generated a comprehensive analysis report. Here's the summary:
 
 **Diagrams**: 8 diagrams (6 need Mermaid conversion)
 
+**Modules Analyzed**: 12 major modules documented
+
 **External Tools**: Jira project PROJ with 12 active epics
 
 **Suggested**: Create 12 increments (one per Jira epic)
 
-**Estimated Effort**: 3.5 hours
+**Estimated Migration Effort**: 2-3 weeks (full documentation)
 
 Would you like me to:
-1. Show the full analysis report?
-2. Proceed with migration?
+1. Show the full comprehensive report?
+2. Start migration (Phase 1: Structure creation)?
 3. Adjust any classifications?
 ```
 
@@ -456,7 +862,7 @@ Your project is now using SpecWeave's PRD/HLD/RFC/Runbook pattern.
 
 Next steps:
 1. Review migrated documents
-2. Run: mkdocs serve (to view documentation)
+2. Run: npm run docs:dev (to view documentation)
 3. Configure ongoing sync: specweave sync --daemon
 ```
 
@@ -485,7 +891,7 @@ for (file of files) {
 
 ## Configuration
 
-**User can configure** scan patterns in `.specweave/config.yaml`:
+**Default scan patterns** are built-in. Advanced users can customize by creating `.specweave/brownfield-config.yaml`:
 
 ```yaml
 brownfield: