agileflow 2.91.0 → 2.92.1

package/src/core/commands/roadmap/analyze.md

@@ -0,0 +1,400 @@
+---
+description: Automated competitor analysis with feature gap identification
+argument-hint: "[COMPETITORS=<keywords>] [FOCUS=all|features|security|perf|ux] [OUTPUT=matrix|report|stories]"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:roadmap:analyze - Competitor analysis orchestrator"
+    - "CRITICAL: Use WebSearch for each competitor (max 5 competitors)"
+    - "CRITICAL: Compare against current project capabilities from codebase"
+    - "MUST categorize features: must-have (2+ competitors) vs nice-to-have (1 competitor)"
+    - "MUST include confidence levels: HIGH (verified), MEDIUM (inferred), LOW (uncertain)"
+    - "Show preview BEFORE saving (diff-first pattern)"
+    - "Output to docs/08-project/roadmap-{YYYYMMDD}.md"
+  state_fields:
+    - competitors_list
+    - focus_area
+    - output_mode
+    - features_found
+    - gaps_identified
+---
+
+# /agileflow:roadmap:analyze
+
+Automated competitor analysis that uses WebSearch to find competitors, analyzes their features, compares against your current project capabilities, and generates a prioritized roadmap with must-have vs nice-to-have recommendations.
+
+**Inspired by**: AutoClaude's roadmap feature (see ADR-0010)
+
+---
+
+## STEP 0: Gather Context (MANDATORY)
+
+```bash
+node .agileflow/scripts/obtain-context.js roadmap
+```
+
+This provides: project overview, tech stack, current features from README/CLAUDE.md.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary - /agileflow:roadmap:analyze IS ACTIVE
+
+**Command**: `/agileflow:roadmap:analyze` - Automated competitor analysis
+
+**Quick Usage**:
+```
+/agileflow:roadmap:analyze COMPETITORS=cursor,windsurf,aider FOCUS=features OUTPUT=report
+```
+
+**What It Does**:
+1. Analyze current project capabilities
+2. WebSearch for each competitor
+3. Extract features from search results
+4. Generate comparison matrix
+5. Categorize: must-have vs nice-to-have
+6. Output roadmap report
+
+**Arguments**:
+- `COMPETITORS=<keywords>` - Comma-separated competitor names (default: auto-detect from project type)
+- `FOCUS=all|features|security|perf|ux` - Analysis focus (default: all)
+- `OUTPUT=matrix|report|stories` - Output format (default: report)
+
+### Tool Usage Examples
+
+**WebSearch** (research competitor):
+```xml
+<invoke name="WebSearch">
+<parameter name="query">{competitor} features pricing 2026</parameter>
+</invoke>
+```
+
+**Write** (save roadmap):
+```xml
+<invoke name="Write">
+<parameter name="file_path">/path/to/docs/08-project/roadmap-YYYYMMDD.md</parameter>
+<parameter name="content"># Competitive Roadmap Analysis...</parameter>
+</invoke>
+```
+
+**AskUserQuestion** (next steps):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "What would you like to do with this roadmap?", "header": "Next Steps", "multiSelect": false, "options": [{"label": "Create epic for must-have features", "description": "Generate epic + stories in status.json"}, {"label": "Research specific feature", "description": "Deep-dive into one gap"}, {"label": "Save and done", "description": "Keep the report"}]}]</parameter>
+</invoke>
+```
+
+**Output**: `docs/08-project/roadmap-{YYYYMMDD}.md`
+**Categories**: Must-have (2+ competitors), Nice-to-have (1 competitor), Competitive Advantage (we have, they don't)
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│            USER: /agileflow:roadmap:analyze                 │
+│            COMPETITORS=X,Y,Z FOCUS=features                 │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  ROADMAP ANALYST                            │
+│  1. Parse arguments (COMPETITORS, FOCUS, OUTPUT)            │
+│  2. Analyze current project from CLAUDE.md/README           │
+│  3. WebSearch each competitor (max 5)                       │
+│  4. Extract features from search results                    │
+│  5. Build comparison matrix                                 │
+│  6. Categorize gaps by priority                             │
+│  7. Generate roadmap report                                 │
+└─────────────────────────────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        ▼                   ▼                   ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│ WebSearch     │   │ WebSearch     │   │ WebSearch     │
+│ Competitor 1  │   │ Competitor 2  │   │ Competitor 3  │
+│               │   │               │   │               │
+│ Features,     │   │ Features,     │   │ Features,     │
+│ pricing,      │   │ pricing,      │   │ pricing,      │
+│ strengths     │   │ strengths     │   │ strengths     │
+└───────────────┘   └───────────────┘   └───────────────┘
+        │                   │                   │
+        └───────────────────┼───────────────────┘
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   COMPARISON ENGINE                         │
+│  • Map features across competitors                          │
+│  • Identify gaps (they have, we don't)                      │
+│  • Identify advantages (we have, they don't)                │
+│  • Must-have: 2+ competitors have it                        │
+│  • Nice-to-have: 1 competitor has it                        │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   ROADMAP REPORT                            │
+│  📊 Competitors Analyzed: 3                                 │
+│  🎯 Must-Have Gaps: 4 features                              │
+│  💡 Nice-to-Have: 6 features                                │
+│  🏆 Competitive Advantages: 2 features                      │
+│  📋 Feature Matrix with checkmarks                          │
+│  🚀 Recommended Next Steps                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Prompt
+
+**ROLE**: Roadmap Analyst
+
+You analyze competitor products via WebSearch and compare them against the current project to identify feature gaps and competitive advantages. Your output is an actionable roadmap prioritizing must-have features.
+
+---
+
+## Workflow Phases
+
+### Phase 1: Parse Arguments & Validate
+
+1. Extract COMPETITORS, FOCUS, OUTPUT from arguments
+2. If COMPETITORS not provided:
+   - Read CLAUDE.md/README.md to understand project type
+   - Suggest 3-5 likely competitors based on project category
+   - Ask user to confirm or provide alternatives
+
+**Auto-detection heuristics:**
+| Project Type | Likely Competitors |
+|--------------|-------------------|
+| CLI tool for AI coding | cursor, windsurf, aider, copilot |
+| React component library | shadcn, radix, chakra, mantine |
+| API framework | fastapi, express, hono, elysia |
+| Documentation site | docusaurus, nextra, fumadocs, gitbook |
+
+### Phase 2: Analyze Current Project
+
+1. Read CLAUDE.md and README.md
+2. Extract:
+   - Project name and description
+   - Key features (look for feature lists, bullet points)
+   - Tech stack
+   - Target audience
+3. Create internal feature list for comparison
+
+### Phase 3: Competitor Research (WebSearch)
+
+For each competitor (max 5):
+
+```xml
+<invoke name="WebSearch">
+<parameter name="query">{competitor} features pricing comparison 2026</parameter>
+</invoke>
+```
+
+Extract from results:
+- Feature list
+- Pricing model (free/paid/freemium)
+- Key strengths mentioned
+- Target audience
+- Notable limitations
+
+**Important**: Include sources with URLs in final report.
+
+### Phase 4: Feature Matrix Generation
+
+Build comparison table:
+
+| Feature Category | Feature | Our Project | Comp 1 | Comp 2 | Comp 3 |
+|------------------|---------|-------------|--------|--------|--------|
+| Core | Feature A | Y | Y | Y | Y |
+| Core | Feature B | N | Y | Y | N |
+| Advanced | Feature C | Y | N | N | N |
+
+Legend:
+- Y = Has feature
+- N = Doesn't have feature
+- ? = Unknown/unclear
+
+### Phase 5: Gap Analysis & Prioritization
+
+**Must-Have (Priority 1)**:
+- Features that 2+ competitors have
+- We don't have
+- High impact for users
+
+**Nice-to-Have (Priority 2)**:
+- Features only 1 competitor has
+- OR features that are niche/specialized
+- Lower impact but differentiating
+
+**Competitive Advantages**:
+- Features WE have that competitors lack
+- Highlight these as strengths
+
+### Phase 6: Output Generation
+
+**Show preview BEFORE saving (diff-first).**
+
+Generate report following the Output Template below.
+
+Ask for confirmation:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Save this roadmap analysis?", "header": "Confirm", "multiSelect": false, "options": [{"label": "Yes, save to docs/08-project/", "description": "Write roadmap-YYYYMMDD.md"}, {"label": "Modify first", "description": "I want to adjust something"}, {"label": "Cancel", "description": "Don't save"}]}]</parameter>
+</invoke>
+```
+
+### Phase 7: Optional Artifact Creation (if OUTPUT=stories)
+
+If user selected OUTPUT=stories:
+1. Create epic for "Competitive Feature Parity"
+2. Generate stories for each must-have feature
+3. Add to status.json
+
+---
+
+## Output Template
+
+```markdown
+# Competitive Roadmap Analysis
+
+**Generated**: {YYYY-MM-DD}
+**Project**: {project name}
+**Competitors Analyzed**: {competitor1}, {competitor2}, {competitor3}
+**Focus Area**: {focus}
+
+---
+
+## Executive Summary
+
+{2-3 paragraph overview of findings}
+
+Key findings:
+- {X} features where we lag behind competitors (must-have gaps)
+- {Y} features unique to single competitors (nice-to-have)
+- {Z} features where we have competitive advantage
+
+---
+
+## Current Project Capabilities
+
+**Project**: {name}
+**Description**: {from README/CLAUDE.md}
+
+**Current Features**:
+- {Feature 1}
+- {Feature 2}
+- {Feature 3}
+
+---
+
+## Competitor Analysis
+
+### {Competitor 1}
+
+**Search Query**: "{query used}"
+**Key Features**:
+- {Feature A}
+- {Feature B}
+- {Feature C}
+
+**Strengths**: {what they do well}
+**Weaknesses**: {gaps or limitations}
+**Pricing**: {model if found}
+
+### {Competitor 2}
+
+[Same structure]
+
+### {Competitor 3}
+
+[Same structure]
+
+---
+
+## Feature Comparison Matrix
+
+| Category | Feature | {Project} | {Comp1} | {Comp2} | {Comp3} | Gap Type |
+|----------|---------|-----------|---------|---------|---------|----------|
+| Core | Feature A | Y | Y | Y | Y | None |
+| Core | Feature B | N | Y | Y | N | Must-Have |
+| Core | Feature C | N | Y | N | N | Nice-to-Have |
+| Advanced | Feature D | Y | N | N | N | Advantage |
+
+---
+
+## Recommendations
+
+### Must-Have Features (High Priority)
+
+Features that 2+ competitors have that we lack:
+
+1. **{Feature Name}**
+   - Found in: {Competitor1}, {Competitor2}
+   - Impact: {why users need this}
+   - Effort estimate: {Low/Medium/High}
+
+2. **{Feature Name}**
+   - Found in: {Competitor1}, {Competitor3}
+   - Impact: {why users need this}
+   - Effort estimate: {Low/Medium/High}
+
+### Nice-to-Have Features (Medium Priority)
+
+Unique features from single competitors worth considering:
+
+1. **{Feature Name}**
+   - Found in: {Competitor only}
+   - Impact: {potential value}
+   - Effort estimate: {Low/Medium/High}
+
+### Competitive Advantages (Maintain & Promote)
+
+Features we have that competitors lack:
+
+1. **{Feature Name}**
+   - Our advantage over: {all/specific competitors}
+   - Why it matters: {user value}
+
+---
+
+## Suggested Next Steps
+
+- [ ] Prioritize must-have features for next quarter
+- [ ] Create epic for competitive feature parity
+- [ ] Research implementation approaches for top 3 gaps
+- [ ] Document competitive advantages in marketing materials
+
+---
+
+## Sources
+
+- [{Competitor 1} - {page title}]({url})
+- [{Competitor 2} - {page title}]({url})
+- [{Competitor 3} - {page title}]({url})
+
+---
+
+*Generated by /agileflow:roadmap:analyze on {date}*
+```
+
+---
+
+## Anti-Patterns
+
+- Search too many competitors (>5 = slow, unfocused)
+- Skip project analysis (can't compare without baseline)
+- Save without preview (diff-first is mandatory)
+- Vague feature descriptions ("better UX" vs "keyboard shortcuts for all actions")
+- Missing sources (always include WebSearch URLs)
+
+---
+
+## Related Commands
+
+- `/agileflow:ideate` - Generate improvement ideas from internal analysis
+- `/agileflow:research:ask` - Generate detailed research prompts
+- `/agileflow:epic` - Create epic for implementing roadmap items

package/src/core/commands/session/new.md

@@ -43,7 +43,23 @@ git rev-parse --is-inside-work-tree
 
 If not in a git repo, display error and exit.
 
-### Step 2: Run Session Manager to Get Current State
+### Step 1.5: Check if Inside Tmux Session
+
+```bash
+# Check if $TMUX environment variable is set
+echo $TMUX
+```
+
+**If INSIDE tmux** (TMUX is not empty):
+- Use the simplified tmux add-window flow (see Step 2B below)
+- This adds a new window to the CURRENT tmux session instead of creating external worktree
+
+**If NOT inside tmux**:
+- Continue with the standard flow (Step 2A below)
+
+### Step 2A: Standard Flow (NOT in tmux)
+
+Run Session Manager to Get Current State:
 
 ```bash
 node .agileflow/scripts/session-manager.js status
@@ -51,7 +67,48 @@ node .agileflow/scripts/session-manager.js status
 
 Parse the JSON output to understand current sessions.
 
-### Step 3: Present Options with AskUserQuestion
+### Step 2B: Tmux Flow (INSIDE tmux)
+
+When inside tmux, use the simplified add-window flow:
+
+```
+AskUserQuestion:
+  question: "Name for the new session window?"
+  header: "New window"
+  multiSelect: false
+  options:
+    - label: "Auto-generate name"
+      description: "Creates parallel-{timestamp} automatically"
+    - label: "auth"
+      description: "Authentication work"
+    - label: "feature"
+      description: "New feature development"
+    - label: "bugfix"
+      description: "Bug fixing"
+```
+
+Then run:
+
+```bash
+# If auto-generate selected:
+node .agileflow/scripts/spawn-parallel.js add-window
+
+# If named option selected:
+node .agileflow/scripts/spawn-parallel.js add-window --name {selected_name}
+
+# If "Other" with custom input:
+node .agileflow/scripts/spawn-parallel.js add-window --name {custom_name}
+```
+
+The script will:
+1. Create a new git worktree
+2. Add a new tmux window to the current session
+3. Start Claude in that window
+4. Output the Alt+N shortcut to switch to it
+
+Display success and exit - skip remaining steps.
+
+### Step 3: Present Options with AskUserQuestion (Standard flow only)
 
 Use AskUserQuestion to let user choose how to create the session:
 
@@ -169,11 +226,30 @@ To switch to this session, run:
 - One short command to type
 - Immediately enables file access to the new session directory
 
+## Worktree Creation Timeout
+
+By default, worktree creation has a 2-minute (120000ms) timeout. For large repositories with many files, you can increase this:
+
+```bash
+# Increase timeout to 5 minutes (300000ms)
+node .agileflow/scripts/session-manager.js create --timeout 300000
+```
+
+During worktree creation, progress feedback is displayed:
+- **TTY (terminal)**: Animated spinner
+- **Non-TTY (Claude Code)**: Periodic "still working" messages every 10 seconds
+
+If worktree creation times out or fails, the script automatically cleans up:
+- Removes any partial worktree directory
+- Prunes git worktree registry
+- Removes the branch if we just created it
+
 ## Error Handling
 
 - **Directory exists**: Suggest different name or manual cleanup
 - **Branch conflict**: Offer to use existing branch or create new one
 - **Git errors**: Display error message and suggest manual resolution
+- **Timeout**: Suggest increasing timeout for large repos
 
 ## Related Commands
 
@@ -187,11 +263,58 @@ To switch to this session, run:
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:session:new IS ACTIVE
 
-**CRITICAL**: This command creates new parallel sessions with git worktrees. Three-step process: validate → present options → create.
+**CRITICAL**: This command creates new parallel sessions with git worktrees.
+
+**TWO MODES:**
+1. **In tmux**: Adds a new window to current session (fast, Alt+N to switch)
+2. **Not in tmux**: Creates worktree with /add-dir navigation
+
+---
+
+### 🚨 RULE #0: CHECK IF IN TMUX FIRST
+
+```bash
+echo $TMUX
+```
+
+**If TMUX is NOT empty** → Use TMUX FLOW (Rule #1B)
+**If TMUX is empty** → Use STANDARD FLOW (Rule #1A onwards)
+
+---
+
+### 🚨 RULE #1B: TMUX FLOW (when in tmux)
+
+Ask for session name:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Name for the new session window?",
+  "header": "New window",
+  "multiSelect": false,
+  "options": [
+    {"label": "Auto-generate name", "description": "Creates parallel-{timestamp} automatically"},
+    {"label": "auth", "description": "Authentication work"},
+    {"label": "feature", "description": "New feature development"},
+    {"label": "bugfix", "description": "Bug fixing"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Then run:
+```bash
+# Auto-generate:
+node .agileflow/scripts/spawn-parallel.js add-window
+
+# Named:
+node .agileflow/scripts/spawn-parallel.js add-window --name {name}
+```
+
+The script outputs the Alt+N shortcut. **DONE - skip remaining rules.**
 
 ---
 
-### 🚨 RULE #1: VALIDATE PREREQUISITES
+### 🚨 RULE #1A: VALIDATE PREREQUISITES (standard flow)
 
 Before doing anything, check:
 ```bash
@@ -475,8 +598,11 @@ To switch to this session, run:
 ### REMEMBER AFTER COMPACTION
 
 - `/agileflow:session:new` IS ACTIVE
-- ALWAYS validate git repo first
-- Present 3 options: auto-create / named / existing branch
+- **CHECK $TMUX FIRST** - determines which flow to use
+- **In tmux**: Use `spawn-parallel.js add-window` → fast, Alt+N to switch
+- **Not in tmux**: Standard worktree flow → /add-dir to switch
+- ALWAYS validate git repo first (for standard flow)
+- Present 3 options: auto-create / named / existing branch (standard flow)
 - Each option leads to different flow
 - Use AskUserQuestion for user selections
 - Handle all error cases (directory, branch, git)