pan-wizard 3.36.0 → 3.37.0

package/docs/specs/industry_analysis_strategic_additions_featureai.md

@@ -0,0 +1,231 @@
+# Feature Spec: Industry Analysis & Strategic Additions
+
+**Date:** 2026-03-03
+**Mode:** --outward (Strategic & Market Analysis Focus)
+**Status:** Proposed
+
+---
+
+## Problem Statement
+
+PAN Wizard operates in a rapidly evolving AI coding tools market where competitors are converging on similar feature sets. The question: what practical additions strengthen PAN's unique position without over-engineering or feature bloat? The cost of NOT evolving is commoditization as other tools add planning, state persistence, and verification features.
+
+## Demand Evidence
+
+| Evidence Type | Source | Finding |
+|--------------|--------|---------|
+| User pain (industry-wide) | Reddit/HN/CodeRabbit report | #1 complaint: "AI amnesia" -- context loss between sessions |
+| Competitor feature parity | Cursor Plan Mode, Aider Architect | Planning-before-coding is now table-stakes (4/6 competitors) |
+| Market gap | All 6 competitors analyzed | Zero competitors have formal milestone/roadmap lifecycle |
+| Industry trend | Anthropic 2026 Agentic Report | "Context engineering" identified as strategic priority |
+
+---
+
+## Competitive Landscape (6-Tool Analysis)
+
+### Competitive Matrix
+
+| Aspect | PAN | Aider | Cursor | Continue | Cline | Windsurf | Copilot WS |
+|--------|-----|-------|--------|----------|-------|----------|-----------|
+| Session Memory | .planning/ files | None | Memories | None | Memory Bank* | Auto-memories | Server-side |
+| Planning | Full lifecycle | Architect mode | Plan Mode | None | new_task | Implicit | Structured pipeline |
+| State Persistence | Comprehensive | Git only | Memories | None | File-based* | Workspace | Server + local |
+| Verification | Standards + UAT | Auto-lint/test | BugBot | CI checks | Lint + test | Auto-iterate | Repair agent |
+| Multi-Runtime | 5 runtimes | Any API | Composer+ | Any API | Any API | Majors | Majors + Auto |
+| Customization | Commands + agents | YAML | Rules (.mdc) | config.yaml | .clinerules | Rules | instructions.md |
+| Unique Edge | Full lifecycle mgmt | Dual-model | 8 parallel agents | CI AI checks | Context handoff | Flow awareness | Issue-to-PR |
+| Open Source | Yes | Yes | No | Yes (ext) | Yes | No | No |
+
+### Key Competitor Innovations
+
+1. **Cline new_task** -- Context window degradation detection at ~50%, structured handoff
+2. **Aider Architect/Editor** -- Dual-model split (strong model plans, cheap model implements)
+3. **Continue.dev CI checks** -- Source-controlled markdown rules as GitHub status checks
+4. **Cursor parallel agents** -- Up to 8 agents via worktrees on same project
+5. **Windsurf auto-memories** -- AI proactively decides what to remember
+
+### Industry Trends (2025-2026)
+
+1. Multi-agent systems: 1,445% surge in inquiries (Gartner)
+2. Extended autonomous execution: 20+ actions before human input
+3. Context engineering as a discipline (Anthropic 2026 report)
+4. Plan-first, execute-second becoming standard
+5. AI as first-class CI pipeline participant
+6. MCP as universal tool protocol
+7. Market: $7.8B -> $52B projected by 2030
+
+### User Pain Points (Industry-Wide)
+
+1. Context loss between sessions (#1 complaint)
+2. Unpredictable token costs
+3. Code quality regression (1.75x more bugs in AI code)
+4. Large codebase understanding
+5. Looping/hallucination on complex tasks
+6. Review bottleneck (AI shifts pressure to maintainers)
+7. Security vulnerabilities (30+ CVEs in AI coding tools)
+
+---
+
+## Strategic Analysis
+
+### Blue Ocean Four Actions
+
+| Action | Decision | Rationale |
+|--------|----------|-----------|
+| ELIMINATE | IDE integration, model marketplace | CLI-first; competing on IDE is losing battle |
+| REDUCE | Manual context setup effort | Other tools auto-detect; PAN requires manual setup |
+| RAISE | Cross-session continuity, verification confidence | PAN's moats -- make them unassailable |
+| CREATE | Session learning, pre-flight checks, dependency validation | Gaps no competitor addresses |
+
+### Wardley Position
+
+PAN sits at early Product stage. Workflow orchestration will commoditize in 2-3 years. The moat shifts to quality of state management, verification depth, and cross-session intelligence.
+
+### Strategic Moat Scores
+
+| Moat Type | Current | With Features | Delta |
+|-----------|---------|--------------|-------|
+| Context Engineering | 4/5 | 5/5 | +1 (session learning) |
+| Cross-Platform | 5/5 | 5/5 | -- (already best) |
+| Developer Experience | 3/5 | 4/5 | +1 (preflight + dashboard) |
+| Zero Dependencies | 5/5 | 5/5 | -- (maintained) |
+| State Persistence | 4/5 | 5/5 | +1 (auto-learning) |
+| Verification Quality | 4/5 | 5/5 | +1 (preflight + deps) |
+| **Total** | **25/30** | **29/30** | **+4** |
+
+### Strategic Recommendation
+
+Build 3-4 practical features that deepen existing moats rather than create new surface area. PAN's unique position is structured workflow management with persistent state -- no competitor does this well. Explicitly do NOT copy: IDE integration, background agents, or auto-iteration loops. Timing is right -- competitors focus on agent parallelism while neglecting workflow quality and reliability.
+
+---
+
+## Recommended Features (4)
+
+### Feature 1: Pre-Flight Checks (`preflight`)
+
+**Priority:** HIGH | **Effort:** S-M | **Moat:** Verification Quality + DX
+
+Validates prerequisites before execution: state consistency, baseline tests pass, git clean, no unresolved blockers, no known error patterns apply to target files.
+
+**Why:** Most common execution failure is starting work on a broken baseline. Only tool that validates before spending tokens.
+
+**Output contract:**
+```json
+{
+  "ready": true,
+  "checks": [
+    { "name": "state_consistent", "passed": true },
+    { "name": "tests_baseline", "passed": true, "count": "1139/1139" },
+    { "name": "git_clean", "passed": true },
+    { "name": "no_blockers", "passed": true },
+    { "name": "no_error_patterns", "passed": true }
+  ],
+  "blockers": []
+}
+```
+
+**Feature ladder:**
+- v0 (MVP): State check + test baseline + git clean
+- v1: Dependency-aware (does phase N-1 have summary?)
+- v2: Custom preflight rules in config.json
+
+---
+
+### Feature 2: Project Dashboard (`dashboard`)
+
+**Priority:** HIGH | **Effort:** S | **Moat:** State Persistence + DX
+
+Single-command project overview: phases, milestones, test counts, blockers, recent activity.
+
+**Why:** Currently requires reading multiple files. Dashboard makes .planning/ state immediately actionable.
+
+**Output contract:**
+```json
+{
+  "project": "PAN Wizard",
+  "version": "2.2.0",
+  "milestone": { "name": "v2.3.0", "completed": 3, "total": 8 },
+  "current_phase": { "number": "04", "name": "verification", "status": "Executing" },
+  "tests": { "passing": 1139, "total": 1139 },
+  "blockers": 0,
+  "learnings": 12,
+  "last_session": "2026-03-03",
+  "next_phase": { "number": "05", "name": "documentation", "status": "Ready" }
+}
+```
+
+**Feature ladder:**
+- v0 (MVP): Phase progress + tests + blockers + last activity
+- v1: Session history + learning count + health score
+- v2: Markdown export for stakeholder reports
+
+---
+
+### Feature 3: Session Intelligence (`session-learn`)
+
+**Priority:** HIGH | **Effort:** M | **Moat:** Context Engineering + State Persistence
+
+Auto-extracts patterns from completed sessions: error resolutions, file co-change relationships, successful fix patterns. Stores in `.planning/learnings.md`.
+
+**Why:** Addresses #1 industry pain point. PAN already has `appendErrorPattern` and `appendSessionSummary` -- this formalizes into a structured learning system.
+
+**How it differs from competitors:**
+- Windsurf auto-memories: Too magic, users can't review. PAN's learnings are visible markdown.
+- Cline Memory Bank: Requires manual setup. PAN auto-generates from session data.
+
+**Feature ladder:**
+- v0 (MVP): Error patterns + file co-change patterns from sessions
+- v1: Proactive hints at session-start based on planned work
+- v2: Cross-project learnings (global patterns)
+
+---
+
+### Feature 4: Dependency Graph Validation (`deps`)
+
+**Priority:** MEDIUM | **Effort:** M | **Moat:** Verification Quality
+
+Cross-references roadmap phases vs. directories, requirements vs. summaries, phase ordering vs. dependencies. Catches drift between plan and reality.
+
+**Why:** As projects grow beyond 5-6 phases, .planning/ can develop inconsistencies. No competitor validates at the workflow level.
+
+**Feature ladder:**
+- v0 (MVP): Roadmap-vs-directory sync + orphaned requirement detection
+- v1: Cross-phase dependency ordering validation
+- v2: Visual dependency graph (Mermaid output)
+
+---
+
+## Recommended Build Order
+
+| Order | Feature | Points | Strategic Value |
+|-------|---------|--------|----------------|
+| 1 | Pre-Flight Checks | 6-8 | Immediate reliability, integrates with verify |
+| 2 | Project Dashboard | 4 | Quick win, high visibility, uses existing data |
+| 3 | Session Intelligence | 8-10 | Deepest moat, addresses #1 pain point |
+| 4 | Dependency Validation | 8 | Important for scale, builds on verify |
+
+## Explicitly NOT Building
+
+| Feature | Why Not |
+|---------|---------|
+| IDE integration | CLI-first; Cursor/Windsurf own this |
+| Parallel agent orchestration | PAN's value is execution quality, not speed |
+| Auto-iteration loops | Windsurf's approach is opaque; PAN values transparency |
+| Background agents | Requires infrastructure; zero-dep constraint |
+| Model marketplace | Runtime-agnostic; model selection is the runtime's job |
+| AI code review bot | Continue.dev/BugBot own this; PAN verifies workflows |
+
+---
+
+## Sources
+
+- [Aider Official](https://aider.chat/)
+- [Cursor Features](https://cursor.com/features)
+- [Continue.dev Docs](https://docs.continue.dev/)
+- [Cline new_task](https://cline.bot/blog/unlocking-persistent-memory-how-clines-new_task-tool-eliminates-context-window-limitations)
+- [Windsurf Cascade](https://windsurf.com/cascade)
+- [Copilot Workspace](https://githubnext.com/projects/copilot-workspace)
+- [CodeRabbit AI Code Quality Report](https://www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report)
+- [Anthropic 2026 Agentic Coding Trends](https://resources.anthropic.com/2026-agentic-coding-trends-report)
+- [Gartner Multi-Agent Surge](https://thenewstack.io/5-key-trends-shaping-agentic-development-in-2026/)
+- [AI Coding Agent Market Size](https://www.faros.ai/blog/best-ai-coding-agents-2026)