specweave 0.4.0 → 0.6.0

package/{src → plugins/specweave-core}/skills/brownfield-analyzer/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: brownfield-analyzer
-description: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/RFC/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and generates migration plan. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
+description: Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/RFC/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and creates project context map for just-in-time migration. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
 ---
 
 # Brownfield Analyzer Skill
 
-**Purpose**: Analyze existing brownfield projects and generate a migration plan to SpecWeave's PRD/HLD/RFC/Runbook pattern.
+**Purpose**: Analyze existing brownfield projects and create project context map (awareness, not prescription) for just-in-time migration to SpecWeave.
 
 **When to Use**: When onboarding an existing project to SpecWeave.
 
+**Philosophy**: Document structure migration (one-time), feature migration (just-in-time per increment). NO big-bang planning of all features upfront.
+
 ---
 
 ## Capabilities
@@ -545,7 +547,9 @@ If you prefer full upfront documentation:
 
 ---
 
-## External Tool Integration
+## External Tool Integration (Awareness Only)
+
+**NOTE**: We detect external tools for AWARENESS, not for creating increments upfront.
 
 ### Jira
 - **URL**: https://company.atlassian.net
@@ -555,16 +559,37 @@ If you prefer full upfront documentation:
   - PROJ-124: Payment Processing
   - ... (list all)
 
-**Suggested Mapping**:
-- Epic PROJ-123 → Increment 0001-user-authentication
-- Epic PROJ-124 → Increment 0002-payment-processing
-- ... (one increment per epic)
+**Context Mapping** (saved to `.specweave/brownfield-context.json`):
+```json
+{
+  "jira": {
+    "url": "https://company.atlassian.net",
+    "project": "PROJ",
+    "epics": [
+      {
+        "id": "PROJ-123",
+        "title": "User Authentication",
+        "suggestedIncrementName": "0001-user-authentication",
+        "status": "In Progress"
+      },
+      {
+        "id": "PROJ-124",
+        "title": "Payment Processing",
+        "suggestedIncrementName": "0002-payment-processing",
+        "status": "To Do"
+      }
+    ]
+  }
+}
+```
+
+**When user creates increment**: Auto-detect if description matches an Epic, offer to link.
 
 ### Azure DevOps
-- (if detected)
+- (if detected, same awareness approach)
 
 ### GitHub
-- (if detected)
+- (if detected, same awareness approach)
 
 ---
 
@@ -587,16 +612,27 @@ If you prefer full upfront documentation:
 1. Convert {count} PNG/DrawIO diagrams to Mermaid
 2. Co-locate diagrams with markdown files
 
-### Phase 4: Increment Creation ({X} hours)
-1. Create {count} increments (one per Jira Epic)
-2. Create `metadata.yaml` for each increment
-3. Link increments to related docs (PRD, HLD, ADR, RFC)
-
-### Phase 5: External Tool Sync ({X} hours)
-1. Run sync command to link Epics → Increments (credentials auto-detected or prompted)
-2. Verify all Epics are mapped
-
-### Phase 6: Verification (30 minutes)
+### Phase 4: External Tool Context ({X} hours) 🔄 CHANGED
+**NOTE**: We DON'T create increments upfront. Instead, we create awareness.
+
+1. Create `.specweave/brownfield-context.json` with:
+   - Jira Epic inventory ({count} epics detected)
+   - ADO Feature inventory (if detected)
+   - GitHub Milestone inventory (if detected)
+   - Mapping suggestions (Epic ID → suggested increment name)
+2. Document external tool configuration for future sync
+3. When user creates increment via `/specweave:inc`:
+   - Auto-detect if it matches a known Epic
+   - Offer to link and sync
+   - Include Epic context in spec
+
+**Why not create increments now?**
+- ❌ User hasn't decided what to work on yet
+- ❌ Creating 50+ placeholder increments is overwhelming
+- ❌ Violates just-in-time philosophy
+- ✅ Just-in-time: Create increment when user chooses to work on it
+
+### Phase 5: Verification (30 minutes)
 1. Run `specweave verify`
 2. Review migration report
 3. Manual review of {count} documents flagged for attention
@@ -610,11 +646,12 @@ If you prefer full upfront documentation:
 | Structure Creation | 0.25 |
 | Document Migration | {X} |
 | Diagram Conversion | {Y} |
-| Increment Creation | {Z} |
-| External Tool Sync | {A} |
+| External Tool Context (awareness only) | 0.5 |
 | Verification | 0.5 |
 | **Total** | **{Total} hours** |
 
+**Note**: Increments are created just-in-time when user works on features, not upfront.
+
 ---
 
 ## Next Steps
@@ -626,18 +663,23 @@ If you prefer full upfront documentation:
    ```bash
    specweave migrate --plan analysis-report.md --execute
    ```
-5. **Enable sync** - Run sync commands for Jira/ADO integration
+5. **Create brownfield context** - Generate `.specweave/brownfield-context.json` with Epic/Feature inventory
+6. **Start working** - Create your first increment via `/specweave:inc "feature name"`
+   - SpecWeave will auto-detect if it matches a Jira Epic
+   - Offer to link and sync
+   - Include existing code analysis in spec
 
 ---
 
 ## Questions for User
 
 - [ ] Are document classifications correct?
-- [ ] Should we sync with Jira/ADO/GitHub?
-- [ ] Are Jira Epic → Increment mappings correct?
+- [ ] Should we track external tools (Jira/ADO/GitHub) for awareness?
 - [ ] Any documents to exclude from migration?
 - [ ] Proceed with migration?
 
+**Note**: We won't create increments for all Jira Epics upfront. Instead, when you create an increment, we'll offer to link it to a matching Epic if found.
+
 ---
 
 ## Appendix: Full File List

package/{src → plugins/specweave-core}/skills/context-loader/SKILL.md

@@ -232,7 +232,7 @@ SpecWeave's **role-orchestrator** skill automatically:
 **Example:**
 
 ```
-User: "/specweave.inc 'Full-stack SaaS with Stripe payments'"
+User: "/specweave:inc 'Full-stack SaaS with Stripe payments'"
     ↓
 role-orchestrator activates
     ↓