agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/planning/agents/rlm-subcore.md

@@ -0,0 +1,215 @@
+---
+name: agileflow-rlm-subcore
+description: RLM sub-agent for document search operations. Runs on Haiku for cost-effective REPL loops over virtualized documents. Search-only, no reasoning.
+tools: Bash, Read, Grep
+model: haiku
+team_role: utility
+---
+
+<!-- AGILEFLOW_META
+compact_context:
+  priority: "high"
+  preserve_rules:
+    - "SEARCH-ONLY: No reasoning, just locate and extract"
+    - "Use document-repl.js for all document operations"
+    - "Return structured results to main agent"
+    - "Respect token budget limits"
+    - "No file writes - exploration only"
+  state_fields:
+    - "document_path: Path to loaded document"
+    - "document_chars: Character count"
+    - "complexity: low | medium | high"
+    - "last_operation: info | search | slice | section | toc"
+AGILEFLOW_META -->
+
+## RLM Sub-Core Agent
+
+You are a lightweight search agent for the RLM (Recursive Language Models) document analysis system. Your job is to execute programmatic searches over virtualized documents and return structured results.
+
+**CRITICAL**: You do NOT do reasoning. You ONLY locate and extract. The main agent synthesizes.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## COMPACT SUMMARY - RLM SUB-CORE AGENT
+
+**ROLE**: Lightweight search over virtualized documents. NO reasoning - just locate and extract.
+
+### RULE #1: YOU ARE SEARCH-ONLY
+
+You do NOT:
+
+- Analyze or interpret content
+- Draw conclusions
+- Make recommendations
+- Write or modify files
+
+You ONLY:
+
+- Execute document-repl.js operations
+- Return structured search results
+- Report what was found and where
+
+### RULE #2: DOCUMENT-REPL OPERATIONS
+
+All operations use the document-repl.js script:
+
+```bash
+# Load and get info
+node packages/cli/scripts/document-repl.js --load="path/to/doc" --info
+
+# Keyword search with context
+node packages/cli/scripts/document-repl.js --load="path/to/doc" --search="keyword"
+
+# Regex search
+node packages/cli/scripts/document-repl.js --load="path/to/doc" --regex="pattern"
+
+# Get specific lines
+node packages/cli/scripts/document-repl.js --load="path/to/doc" --slice="100-200"
+
+# Find section by heading
+node packages/cli/scripts/document-repl.js --load="path/to/doc" --section="Article 7"
+
+# Get table of contents
+node packages/cli/scripts/document-repl.js --load="path/to/doc" --toc
+```
+
+### RULE #3: OPERATION SELECTION
+
+| User Intent           | Operation | Example                      |
+| --------------------- | --------- | ---------------------------- |
+| "Find X in document"  | --search  | `--search="indemnification"` |
+| "What sections exist" | --toc     | `--toc`                      |
+| "Show Article 7"      | --section | `--section="Article 7"`      |
+| "Lines 500-600"       | --slice   | `--slice="500-600"`          |
+| "Pattern like X-\d+"  | --regex   | `--regex="X-\d+"`            |
+| "How big is this"     | --info    | `--info`                     |
+
+### RULE #4: OPTIONS
+
+| Option        | Purpose                 | Default |
+| ------------- | ----------------------- | ------- |
+| `--context=N` | Lines around matches    | 2       |
+| `--budget=N`  | Max output chars        | 15000   |
+| `--json`      | Machine-readable output | false   |
+| `--verbose`   | Debug info              | false   |
+
+### RULE #5: RETURN FORMAT
+
+Always return:
+
+1. **Operation executed**: What you searched for
+2. **Results found**: Count and locations
+3. **Content**: The actual extracted text
+4. **Truncation notice**: If budget exceeded
+
+Example return:
+
+```
+Searched: "conditions precedent"
+Found: 3 matches in lines 450, 782, 1203
+Budget: 2,500 / 15,000 chars used
+
+--- Line 450 (context: 448-452) ---
+[extracted content]
+
+--- Line 782 (context: 780-784) ---
+[extracted content]
+
+--- Line 1203 (context: 1201-1205) ---
+[extracted content]
+```
+
+### Anti-Patterns (DON'T)
+
+- Analyze or interpret the results
+- Make recommendations based on content
+- Load full document into response
+- Use Read tool for document content (use document-repl.js)
+- Exceed budget without truncation notice
+
+### Correct Patterns (DO)
+
+- Execute document-repl.js commands
+- Report structured results
+- Use --json for machine parsing
+- Respect budget limits
+- Return quickly with minimal processing
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Supported Document Formats
+
+| Format  | Support      | Notes                            |
+| ------- | ------------ | -------------------------------- |
+| `.txt`  | Native       | Direct text processing           |
+| `.md`   | Native       | Markdown with heading extraction |
+| `.pdf`  | Requires npm | `npm install pdf-parse`          |
+| `.docx` | Requires npm | `npm install mammoth`            |
+
+---
+
+## When to Use This Agent
+
+**USE (via main agent delegation)**:
+
+- Long context (50k+ chars) documents
+- High complexity (cross-references, sections)
+- Multiple search operations needed
+- Budget-constrained environments
+
+**DON'T USE**:
+
+- Small documents (<10k chars) - direct read is fine
+- Simple queries - grep/read is sufficient
+- When reasoning is needed - use domain experts
+
+---
+
+## Example Session
+
+**Main agent delegates**: "Find all mentions of 'termination' in this merger agreement"
+
+**Sub-core executes**:
+
+```bash
+node packages/cli/scripts/document-repl.js \
+  --load="/path/to/merger-agreement.pdf" \
+  --search="termination" \
+  --context=3 \
+  --budget=10000
+```
+
+**Sub-core returns**:
+
+```
+Searched: "termination"
+Found: 7 matches
+
+--- Line 234 (context: 231-237) ---
+...the Purchaser may terminate this Agreement by written notice...
+
+--- Line 567 (context: 564-570) ---
+...upon termination of this Agreement, all rights shall revert...
+
+[5 more matches]
+
+Budget used: 8,234 / 10,000 chars
+```
+
+**Main agent synthesizes**: Uses these excerpts to answer the original question about termination conditions.
+
+---
+
+## Integration with /agileflow:rlm
+
+This agent is spawned by the `/agileflow:rlm` command when:
+
+1. Document complexity is HIGH
+2. Multiple search operations are needed
+3. Cost optimization is required (Haiku vs Sonnet)
+
+The main Sonnet agent orchestrates, this Haiku sub-agent searches.

package/content/plugins/planning/plugin.yaml

@@ -0,0 +1,19 @@
+id: planning
+name: Planning
+description: Planning and metrics skill pack.
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  skills:
+    - id: agileflow-planning
+      dir: skills/agileflow-planning
+  agents:
+    - id: analytics
+      path: agents/analytics.md
+    - id: rlm-subcore
+      path: agents/rlm-subcore.md
+  hooks: []
+  templates: []

package/content/plugins/planning/skills/agileflow-planning/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: agileflow-planning
+version: 1.0.0
+category: agileflow/planning
+description: |
+  Use when the user wants to measure, plan, or optimize their development
+  process: impact analysis, metrics dashboards, velocity tracking, RPI
+  workflow, roadmap analysis, automation setup, or feedback loops.
+triggers:
+  keywords:
+    - impact analysis
+    - what will this affect
+    - metrics
+    - velocity
+    - roadmap
+    - automate
+    - feedback
+    - measure
+    - analytics
+    - planning
+    - rpi
+    - research plan implement
+  priority: 45
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/planning.yaml
+  maxEntries: 30
+depends:
+  skills: []
+  plugins: [planning]
+---
+
+# AgileFlow Planning
+
+Development process intelligence: impact analysis before making
+changes, metrics tracking after, velocity measurement, and workflow
+automation setup.
+
+## When this skill activates
+
+- User wants to know what a change will affect before making it
+- User asks about team velocity, metrics, or process health
+- User wants to set up automation or recurring workflows
+- User is following an RPI (Research → Plan → Implement) workflow
+- User wants to analyze the roadmap or prioritize work
+
+## Capabilities
+
+| Command                      | What it does                                             |
+| ---------------------------- | -------------------------------------------------------- |
+| `/agileflow:impact`          | Analyze what files/modules a proposed change will affect |
+| `/agileflow:metrics`         | Dashboard of story velocity, completion rate, WIP        |
+| `/agileflow:velocity`        | Track and visualize team delivery speed                  |
+| `/agileflow:rpi`             | Research → Plan → Implement workflow orchestration       |
+| `/agileflow:roadmap:analyze` | Analyze roadmap priorities and dependencies              |
+| `/agileflow:automate`        | Set up recurring automation and scheduled tasks          |
+| `/agileflow:feedback`        | Capture and process user feedback                        |
+| `/agileflow:analytics`       | Event tracking and user behavior analysis                |
+| `/agileflow:diagnose`        | Diagnose process bottlenecks and blockers                |
+| `/agileflow:export`          | Export project data to external formats                  |
+| `/agileflow:rlm`             | Retrieval-augmented memory for large document sets       |
+
+## Impact analysis — always run before
+
+When a story touches 3+ existing files, run `/agileflow:impact` BEFORE
+entering plan mode. It reveals:
+
+- Which modules will be affected
+- What tests cover those modules
+- Risk level (low / medium / high)
+
+## RPI workflow
+
+For unfamiliar technical territory:
+
+1. **Research** — `/agileflow:research:ask` with full context
+2. **Plan** — EnterPlanMode with research findings
+3. **Implement** — delegate to domain experts
+
+## Integration
+
+- **agileflow-council** — convene before planning when the strategic direction is ambiguous; council resolves "what to build", planning resolves "how to sequence it"
+- **agileflow-research** — use to gather technical benchmarks, dependency risk data, or competitive context that informs the impact analysis or sprint priorities
+- **agileflow-story-writer** — planning produces a prioritised backlog; story-writer gives each item the structure and AC needed to enter that backlog
+- **agileflow-epic-planner** — when planning reveals a large theme, route to epic-planner to break it into sequenced milestones before estimating sprint capacity
+- **agileflow-status-updater** — use to reflect sprint state changes (planning → active → completed) in `status.json` as planning decisions are made
+- **agileflow-babysit-mentor** — mentor is the primary consumer of the planned work; a well-scoped sprint is the input that makes mentor-guided execution efficient
+- **agileflow-delivery** — delivery closes the planning loop; use planning to define the sprint and delivery to close it
+- **agileflow-adr** — planning often surfaces architectural decisions (scope trade-offs, dependency choices); document them as ADRs rather than leaving them implicit
+- **agileflow-retention** — use retention metrics alongside velocity data when planning engagement-focused sprints; retention informs what to prioritise, planning determines when
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                                  | When to load                                                                                                   |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `references/rpi-workflow.md`          | User is about to implement something unfamiliar — Research → Plan → Implement phases, checklists, when to skip |
+| `references/estimation-guide.md`      | Estimating story effort — story points vs time, Fibonacci scale, planning poker, velocity, cone of uncertainty |
+| `references/sprint-planning-guide.md` | Running sprint planning — capacity formula, sprint goal template, backlog ordering, INVEST checklist           |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                  | When to follow                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `workflows/impact.md` | User wants to understand what a change will affect before starting work                    |
+| `workflows/rpi.md`    | User is starting an unfamiliar implementation — guides through Research → Plan → Implement |

package/content/plugins/planning/skills/agileflow-planning/references/estimation-guide.md

@@ -0,0 +1,114 @@
+# Estimation Guide
+
+**Load this when:** Estimating stories, running planning poker, calculating velocity, or explaining estimation to a team.
+
+## Story Points vs. Time
+
+| Approach                | When to use                                            | Pitfall                                               |
+| ----------------------- | ------------------------------------------------------ | ----------------------------------------------------- |
+| Story points (relative) | Stable team, ongoing product work                      | Points become proxies for hours (defeats the purpose) |
+| Time estimates (hours)  | Fixed-price projects, new teams, external stakeholders | Anchors thinking to clock time, not complexity        |
+| T-shirt sizing          | Early discovery, pre-refinement                        | Too coarse for sprint planning                        |
+
+**Recommendation:** Use story points for sprint work. Convert to time only for external commitments, using historical velocity.
+
+---
+
+## Fibonacci Scale Reference
+
+| Points | Complexity signal            | Typical scope                                 |
+| ------ | ---------------------------- | --------------------------------------------- |
+| 1      | Trivial, fully understood    | Config change, copy update, one-line fix      |
+| 2      | Simple, low uncertainty      | Small UI change, simple utility function      |
+| 3      | Moderate, some unknowns      | New component with tests, API endpoint        |
+| 5      | Complex or cross-cutting     | Feature with multiple states, auth changes    |
+| 8      | Large, significant unknowns  | New domain area, integration with third-party |
+| 13     | Very large — should be split | Multiple independent deliverables visible     |
+| 21+    | Must split before estimation | Epic-level work                               |
+
+**Rule:** If a story is 13+, split it. If team can't agree within 3 points, the story needs more refinement, not more debate.
+
+---
+
+## Planning Poker Protocol
+
+1. Product owner reads story + acceptance criteria aloud
+2. Team asks clarifying questions (2–3 minutes)
+3. Everyone picks a card privately — reveal simultaneously
+4. If consensus (within 1 Fibonacci step): accept, move on
+5. If spread >2 steps: highest and lowest estimates explain reasoning (2 min each)
+6. Re-estimate once — if still no consensus, take the average or timebox the story
+7. Log any risk flags raised during discussion
+
+**Cards:** 0, 1, 2, 3, 5, 8, 13, 20, 40, 100, ?, ∞ (I need a break)
+
+- `?` = "I don't understand enough to estimate"
+- `∞` = "This needs to be split before I can estimate"
+
+---
+
+## Velocity Calculation
+
+```
+Team velocity = average story points completed per sprint
+              (exclude incomplete stories from numerator)
+
+Recommended window: rolling last 3–5 sprints
+Exclude: sprints with >25% team absence, onboarding sprints
+```
+
+### Example
+
+| Sprint | Completed pts | Notes             |
+| ------ | ------------- | ----------------- |
+| S-14   | 34            | —                 |
+| S-15   | 29            | 1 person on leave |
+| S-16   | 38            | —                 |
+| S-17   | 36            | —                 |
+
+Rolling avg (last 3): (38 + 36 + 29) / 3 = **34 pts/sprint**
+Planning capacity: **28–34 pts** (use 80–100% of velocity for healthy sprint)
+
+---
+
+## Cone of Uncertainty
+
+Estimate confidence degrades as project size grows and time extends:
+
+| Phase                       | Accuracy range      |
+| --------------------------- | ------------------- |
+| Initial concept             | ±75% (0.25x – 4x)   |
+| Product definition complete | ±25% (0.75x – 1.5x) |
+| Requirements complete       | ±10% (0.9x – 1.1x)  |
+| Design complete             | ±5% (0.95x – 1.05x) |
+
+**Implication:** Any estimate made before requirements are complete is a rough order of magnitude, not a commitment. Plan buffers accordingly.
+
+---
+
+## Estimation Anti-Patterns
+
+| Anti-pattern                                 | Effect                               | Fix                                     |
+| -------------------------------------------- | ------------------------------------ | --------------------------------------- |
+| Estimating in hours while tracking in points | Hours anchor to time, not complexity | Commit to one unit                      |
+| Averaging without outlier discussion         | Hides risk signals                   | Discuss spread, then re-estimate        |
+| Manager adjusts estimates                    | Destroys team trust and accuracy     | Product owner clarifies, team estimates |
+| Velocity as a commitment target              | Creates velocity gaming              | Treat velocity as forecast, not quota   |
+| Estimating unrefined stories                 | High variance, misleading plans      | Refine before sprint planning           |
+| Including unfinished stories in velocity     | Inflates apparent velocity           | Count only completed stories            |
+
+---
+
+## Time-to-Point Conversion (for external forecasting only)
+
+```
+Story hours ≈ points × (team hours/day × sprint days) / velocity
+
+Example:
+  4 devs × 6 productive hours × 10 days = 240 dev-hours per sprint
+  Velocity = 34 points
+  1 point ≈ 7 dev-hours
+
+Use this for rough external estimates only — never share points-to-hours
+mapping with stakeholders as a precise conversion.
+```

package/content/plugins/planning/skills/agileflow-planning/references/rpi-workflow.md

@@ -0,0 +1,119 @@
+# RPI Workflow Reference
+
+**Load this when:** guiding a user through Research → Plan → Implement,
+or when the task involves unfamiliar territory that needs external research first.
+
+## What RPI is
+
+RPI = **Research → Plan → Implement**
+
+A structured workflow for tackling unfamiliar technical problems where diving
+straight into implementation leads to wasted effort. Particularly effective when:
+
+- Working with an unfamiliar library, API, or pattern
+- The architecture has multiple viable approaches with real tradeoffs
+- Previous attempts at similar work failed unexpectedly
+- The problem domain is complex enough that assumptions are risky
+
+## The three phases
+
+### Phase 1: Research
+
+**Goal:** Understand the problem space before writing a single line of code.
+
+Activities:
+
+- Run `/agileflow:research:ask` with a detailed prompt (200+ lines, 50+ lines of code, exact errors, 3+ specific questions)
+- Import findings via `/agileflow:research:import`
+- Check existing research notes via `/agileflow:research:list`
+- Synthesize across multiple sources via `/agileflow:research:synthesize`
+
+**Research prompt quality checklist:**
+
+```
+⬜ 50+ lines of actual relevant code included
+⬜ Exact error messages with full stack traces
+⬜ Library versions specified
+⬜ What has already been tried
+⬜ 3+ specific questions (not "how do I fix this?")
+⬜ Context: what the code is supposed to do
+```
+
+**Phase exits when:** you have enough information to write a confident plan.
+
+### Phase 2: Plan
+
+**Goal:** Design the implementation before touching production code.
+
+Activities:
+
+- Enter plan mode: `EnterPlanMode`
+- Explore 3–5 key files (understand patterns, conventions, dependencies)
+- Write the plan: steps, files to change, decisions made, testing approach
+- Include a flow verification step for user-facing features
+- Exit plan mode: `ExitPlanMode`
+
+**Plan quality checklist:**
+
+```
+⬜ Implementation steps are specific (not "update the auth module")
+⬜ Files to be changed are listed
+⬜ Key decisions are documented with rationale
+⬜ Testing approach is defined
+⬜ Flow verification step included (for user-facing work)
+⬜ Rollback approach noted for risky changes
+```
+
+**Phase exits when:** plan is approved by user.
+
+### Phase 3: Implement
+
+**Goal:** Execute the plan with high confidence, minimal surprises.
+
+Activities:
+
+- Follow the plan — don't improvise unless you find something unexpected
+- If something unexpected: pause, assess, update plan if needed
+- Delegate to domain experts via Task tool
+- Run tests after implementation
+- Run audits (logic, flow, security as relevant)
+
+## Context health and RPI
+
+RPI is especially important when context is getting long (>70% full).
+The "dumb zone" in long contexts causes planning to degrade.
+
+Signs you're in the dumb zone:
+
+- Suggestions that contradict earlier decisions
+- Forgetting what was already implemented
+- Inconsistent approach across files
+
+When in the dumb zone: `/agileflow:compress` to compact context before continuing,
+or `/agileflow:context:full` to review what's been established.
+
+## When to skip RPI
+
+RPI adds overhead — don't use it for:
+
+- Simple one-liner fixes
+- Familiar patterns you've done many times in this codebase
+- Changes with obvious, single implementation path
+- Urgent hotfixes where deliberation costs more than the risk
+
+Use RPI for:
+
+- Unfamiliar libraries or APIs (>60% of the time)
+- Architecture decisions
+- Anything that failed when tried before
+- Complex multi-file refactors
+
+## RPI and impact analysis
+
+Before Phase 2 (Planning), if the work touches existing code:
+
+1. Run `/agileflow:impact` to understand blast radius
+2. Incorporate impact findings into the plan
+3. Add tests for high-impact areas
+
+High-impact = many downstream dependencies = higher risk = more careful plan.