agileflow 3.4.0 → 3.4.1

package/src/core/commands/migrate/plan.md

@@ -0,0 +1,131 @@
+---
+description: Generate step-by-step migration roadmap with risk assessment, rollback strategy, and execution order from scan results
+argument-hint: "[scan-report|package-name] [SCOPE=full|incremental]"
+---
+
+# /agileflow:migrate:plan
+
+Generate a detailed migration plan with step-by-step execution order, risk assessment, rollback strategies, and dependency mapping from scan results or specific upgrade targets.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:migrate:plan                                    # Plan from latest scan report
+/agileflow:migrate:plan react                              # Plan React upgrade specifically
+/agileflow:migrate:plan next@15                            # Plan Next.js 15 migration
+/agileflow:migrate:plan . SCOPE=incremental                # Incremental migration (phase by phase)
+/agileflow:migrate:plan typescript@5.5                     # Plan TypeScript upgrade
+```
+
+---
+
+## How It Works
+
+1. **Read scan results** or analyze specific upgrade target
+2. **Map dependencies** between migration steps
+3. **Assess risk** for each step (data loss, downtime, breaking changes)
+4. **Design rollback** strategy for each step
+5. **Order execution** by dependency and risk (safest first)
+6. **Estimate effort** per step
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = scan report path, package name, or package@version
+SCOPE = full (all at once) or incremental (phased)
+```
+
+### STEP 2: Research Migration Path
+
+Delegate to `agileflow-research` agent:
+- Read official migration guides for the target upgrade
+- Find known issues and workarounds
+- Check community experience (GitHub issues, blog posts)
+- Identify breaking changes between current and target versions
+
+### STEP 3: Map Dependencies
+
+Build a dependency graph of migration steps:
+- Which steps must happen before others
+- Which steps can run in parallel
+- Which steps affect shared code
+
+### STEP 4: Assess Risk
+
+For each migration step:
+
+| Risk Level | Criteria |
+|------------|----------|
+| **High** | Data migration, schema changes, auth changes |
+| **Medium** | API changes, dependency swaps, config changes |
+| **Low** | Syntax updates, import changes, type updates |
+
+### STEP 5: Generate Migration Plan
+
+```markdown
+# Migration Plan: {Target}
+
+**Generated**: {date}
+**Current State**: {current versions/patterns}
+**Target State**: {target versions/patterns}
+**Estimated Effort**: {total estimate}
+**Risk Level**: {overall risk}
+
+## Pre-Migration Checklist
+- [ ] Full test suite passing
+- [ ] Database backup created
+- [ ] Feature flags for gradual rollout
+- [ ] Rollback procedure documented
+
+## Phase 1: {Name} (Risk: Low)
+### Step 1.1: {Action}
+- **What**: {specific change}
+- **Files affected**: {list}
+- **Risk**: {description}
+- **Rollback**: {how to undo}
+- **Verification**: {how to confirm success}
+
+### Step 1.2: {Action}
+...
+
+## Phase 2: {Name} (Risk: Medium)
+...
+
+## Phase 3: {Name} (Risk: High)
+...
+
+## Post-Migration Verification
+- [ ] All tests passing
+- [ ] No deprecated API warnings
+- [ ] Performance benchmarks stable
+- [ ] Monitoring shows no regressions
+```
+
+Save to `docs/08-project/migrations/plan-{target}-{YYYYMMDD}.md`
+
+### STEP 6: Offer Next Steps
+
+```
+Migration plan generated: [N] phases, [M] steps. Estimated effort: [estimate].
+
+Options:
+- Generate codemods for Phase 1 (Recommended)
+- Create stories from migration steps
+- Review plan in detail
+- Save plan and done
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:migrate:scan` - Detect migration opportunities
+- `/agileflow:migrate:codemods` - Generate AST-based codemods
+- `/agileflow:migrate:validate` - Post-migration verification
+- `/agileflow:research:ask` - Deep research on specific migration topics

package/src/core/commands/migrate/scan.md

@@ -0,0 +1,114 @@
+---
+description: Detect deprecated APIs, outdated patterns, breaking dependency changes, and migration opportunities in your codebase
+argument-hint: "[file|directory] [FOCUS=deps|patterns|apis|all]"
+---
+
+# /agileflow:migrate:scan
+
+Scan the codebase for migration opportunities - deprecated APIs, outdated patterns, breaking dependency changes, and version-specific issues that need attention.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:migrate:scan                        # Scan entire project
+/agileflow:migrate:scan src/                   # Scan specific directory
+/agileflow:migrate:scan . FOCUS=deps           # Focus on dependency changes only
+/agileflow:migrate:scan . FOCUS=patterns       # Focus on outdated code patterns
+/agileflow:migrate:scan . FOCUS=apis           # Focus on deprecated API usage
+```
+
+---
+
+## How It Works
+
+1. **Dependency analysis**: Check package.json for outdated deps, breaking version jumps, deprecated packages
+2. **Pattern detection**: Find outdated coding patterns (old React class components, CommonJS in ESM projects, etc.)
+3. **API deprecation**: Find usage of deprecated APIs (Node.js, browser, framework-specific)
+4. **Version incompatibility**: Detect code that won't work with newer versions of dependencies
+5. **Migration urgency**: Score each finding by urgency (security fix, breaking change, deprecation timeline)
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = first argument or current directory
+FOCUS = all (default) or deps|patterns|apis
+```
+
+### STEP 2: Analyze Dependencies
+
+Use the `agileflow-devops` agent to:
+- Run `npm outdated` or equivalent
+- Check for deprecated packages (`npm info <pkg> deprecated`)
+- Identify major version jumps with breaking changes
+- Check for known vulnerabilities (`npm audit`)
+
+### STEP 3: Scan for Outdated Patterns
+
+Use the `agileflow-refactor` agent to find:
+- Deprecated framework patterns (React class components, Vue Options API in Vue 3+, etc.)
+- Old module systems (CommonJS `require()` in ESM projects)
+- Deprecated Node.js APIs (`fs.exists`, `url.parse`, `new Buffer()`)
+- Old test patterns (enzyme vs testing-library)
+- Legacy build tool configurations
+
+### STEP 4: Detect Deprecated API Usage
+
+Use the `agileflow-research` agent to:
+- Check framework changelogs for deprecated features
+- Find deprecated browser APIs (e.g., `document.write`, synchronous XHR)
+- Identify Node.js deprecated APIs by version
+
+### STEP 5: Generate Scan Report
+
+Output a prioritized list of migration opportunities:
+
+```markdown
+# Migration Scan Report
+
+**Generated**: {date}
+**Target**: {directory}
+**Total Opportunities**: {N}
+
+## Critical (Security/Breaking)
+| Package/Pattern | Current | Target | Risk | Effort |
+|-----------------|---------|--------|------|--------|
+| {name} | {version} | {version} | {desc} | {est} |
+
+## High Priority (Deprecation Deadline)
+...
+
+## Medium Priority (Tech Debt)
+...
+
+## Low Priority (Improvements)
+...
+```
+
+Save to `docs/08-project/migrations/scan-{YYYYMMDD}.md`
+
+### STEP 6: Offer Next Steps
+
+```
+Scan complete: [N] migration opportunities found ([critical] critical, [high] high priority).
+
+Options:
+- Generate migration plan for critical items (Recommended)
+- Create stories for all findings
+- Re-scan with different focus
+- Save report and done
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:migrate:plan` - Generate step-by-step migration roadmap
+- `/agileflow:migrate:codemods` - Generate AST-based codemods
+- `/agileflow:migrate:validate` - Post-migration verification
+- `/agileflow:packages` - Dependency management

package/src/core/commands/migrate/validate.md

@@ -0,0 +1,119 @@
+---
+description: Post-migration verification - run tests, check for deprecated usage, validate types, and confirm migration completeness
+argument-hint: "[migration-plan|package-name] [--strict]"
+---
+
+# /agileflow:migrate:validate
+
+Run comprehensive post-migration verification to confirm the migration was successful - tests pass, no deprecated APIs remain, types check, and no regressions introduced.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:migrate:validate                                # Validate latest migration
+/agileflow:migrate:validate react                          # Validate React migration
+/agileflow:migrate:validate next@15                        # Validate Next.js 15 migration
+/agileflow:migrate:validate . --strict                     # Strict mode - zero warnings
+```
+
+---
+
+## How It Works
+
+1. **Run test suite** - Full test run to catch regressions
+2. **Re-scan for deprecated usage** - Verify no deprecated APIs remain
+3. **Type check** - Run TypeScript/type checker for type errors
+4. **Lint check** - Run linter for new issues
+5. **Build check** - Verify production build succeeds
+6. **Generate validation report** - Pass/fail with details
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = migration plan path, package name, or current directory
+STRICT = --strict flag (zero warnings tolerance)
+```
+
+### STEP 2: Run Validation Checks
+
+Execute all checks and collect results:
+
+| Check | Command | Pass Criteria |
+|-------|---------|--------------|
+| Tests | `npm test` | All passing |
+| Type check | `npx tsc --noEmit` | No errors |
+| Lint | `npm run lint` | No errors (warnings OK unless strict) |
+| Build | `npm run build` | Exits 0 |
+| Deprecated scan | Re-run `/agileflow:migrate:scan` | No critical findings |
+
+### STEP 3: Compare Before/After
+
+If a migration plan exists, compare:
+- Test count: same or more (not fewer)
+- Build size: within 10% (flag large increases)
+- Type errors: zero new errors
+- Deprecated usage: reduced to zero for migrated items
+
+### STEP 4: Generate Validation Report
+
+```markdown
+# Migration Validation Report
+
+**Generated**: {date}
+**Migration**: {target}
+**Status**: {PASS | PARTIAL | FAIL}
+
+## Check Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Tests | {pass/fail} | {N} passing, {M} failing |
+| Types | {pass/fail} | {N} errors |
+| Lint | {pass/fail} | {N} errors, {M} warnings |
+| Build | {pass/fail} | Build size: {N} |
+| Deprecated scan | {pass/fail} | {N} remaining items |
+
+## Failures (if any)
+
+### Test Failures
+{list of failing tests with details}
+
+### Type Errors
+{list of new type errors}
+
+### Remaining Deprecated Usage
+{list of deprecated items still in codebase}
+
+## Verdict
+
+{Overall assessment and recommended next steps}
+```
+
+Save to `docs/08-project/migrations/validation-{YYYYMMDD}.md`
+
+### STEP 5: Offer Next Steps
+
+```
+Migration validation: [STATUS]. [N]/[M] checks passed.
+
+Options:
+- Fix failing tests (Recommended)
+- Fix remaining deprecated usage
+- Accept partial migration and create stories for remaining work
+- Mark migration as complete
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:migrate:scan` - Detect migration opportunities
+- `/agileflow:migrate:plan` - Generate migration roadmap
+- `/agileflow:migrate:codemods` - Generate AST-based codemods
+- `/agileflow:verify` - Run project tests

package/src/core/commands/multi-expert.md

@@ -1,5 +1,6 @@
 ---
 description: Deploy multiple domain experts on the same problem for higher confidence
+phase: planning
 argument-hint: "<question>"
 compact_context:
   priority: high

package/src/core/commands/pr.md

@@ -1,5 +1,6 @@
 ---
 description: Generate pull request description from story
+phase: pre-pr
 argument-hint: "STORY=<US-ID> [TITLE=<text>] [TEST_EVIDENCE=<text>]"
 compact_context:
   priority: high

package/src/core/commands/review.md

@@ -1,5 +1,6 @@
 ---
 description: AI-powered code review with quality suggestions
+phase: post-impl
 argument-hint: "[BRANCH=<name>] [BASE=<branch>] [FOCUS=all|security|performance|style]"
 compact_context:
   priority: critical

package/src/core/commands/sprint.md

@@ -1,5 +1,6 @@
 ---
 description: Data-driven sprint planning with velocity forecasting
+phase: pre-story
 argument-hint: "[SPRINT=<id>] [DURATION=<number>] [AGENTS=<list>] [MODE=suggest|commit] [FOCUS_EPIC=<EP-ID>]"
 model: haiku
 compact_context:

package/src/core/commands/status/undo.md

@@ -0,0 +1,191 @@
+---
+description: Undo the last status change for a story (rollback)
+argument-hint: "STORY=<US-ID>"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:status:undo - Rollback story status to previous value"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:user_confirmation}}"
+    - "{{RULES:file_preview}}"
+    - "MUST read bus/log.jsonl to find the last status change"
+    - "MUST show current vs previous status as diff"
+    - "MUST confirm with AskUserQuestion before applying"
+    - "MUST log revert event to bus/log.jsonl with type=status-reverted"
+  state_fields:
+    - story_id
+    - current_status
+    - previous_status
+---
+
+# /agileflow:status:undo
+
+Undo the last status change for a story by reading the bus event log to find the previous status.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js status:undo
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:status:undo STORY=<US-ID>`
+**Purpose**: Rollback a story's status to its previous value using bus log history
+
+### Flow
+1. Parse STORY parameter (required)
+2. Read bus/log.jsonl to find status change history for the story
+3. Read current status from status.json
+4. Show diff: current status vs previous status
+5. Confirm via AskUserQuestion
+6. Apply rollback to status.json
+7. Log status-reverted event to bus/log.jsonl
+
+### Critical Rules
+- **Bus log sourced**: Previous status comes from bus/log.jsonl history
+- **Diff preview**: Show current vs previous before applying
+- **Confirmation**: Never write without user approval
+- **Bus logging**: Append status-reverted event after rollback
+- **No history = no undo**: If no previous status event found, inform user
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| STORY | Yes | Story ID to revert (e.g., US-0042) |
+
+---
+
+## IMMEDIATE ACTIONS
+
+### Step 1: Validate Input
+
+If STORY not provided, list recently changed stories from bus log.
+
+### Step 2: Find Previous Status
+
+Read `docs/09-agents/bus/log.jsonl` and find status change events for the given story. Look for events with:
+- `type: "status"` and matching `story` field
+- `type: "assign"` (initial creation = "ready")
+- `type: "status-reverted"` (previous undos)
+
+Parse the log in reverse chronological order to find:
+1. **Current status event** (most recent)
+2. **Previous status event** (the one before that)
+
+If only one status event exists (the initial creation), inform the user:
+```
+No previous status found for US-0042.
+Current status "ready" is the original status from story creation.
+Nothing to undo.
+```
+
+### Step 3: Read Current State
+
+Read story from `docs/09-agents/status.json` to confirm the current status matches what the bus log says.
+
+### Step 4: Show Diff Preview
+
+```markdown
+## Status Undo: US-0042
+
+| | Status |
+|---|--------|
+| Current | in_progress |
+| Revert to | ready |
+
+Based on bus event from 2026-03-01T14:30:00Z:
+  "Story US-0042 status changed to in_progress"
+```
+
+### Step 5: Confirm Rollback
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Revert US-0042 from 'in_progress' back to 'ready'?",
+  "header": "Confirm undo",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, revert status (Recommended)", "description": "Change status from in_progress back to ready"},
+    {"label": "No, cancel", "description": "Keep current status"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 6: Apply Rollback
+
+On confirmation:
+
+1. **Update status.json** using Edit tool:
+   - Set story status to the previous value
+   - Update the `updated` timestamp
+
+2. **Validate JSON**:
+```bash
+node -e "JSON.parse(require('fs').readFileSync('docs/09-agents/status.json','utf8')); console.log('valid')"
+```
+
+3. **Append to bus/log.jsonl**:
+```json
+{"ts":"<ISO>","type":"status-reverted","from":"USER","story":"<STORY>","from_status":"<current>","to_status":"<previous>","text":"Status reverted from <current> to <previous>"}
+```
+
+### Step 7: Confirm Success
+
+```
+US-0042 status reverted: in_progress -> ready
+```
+
+---
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No status events in bus log | Check status.json only, inform "no history available" |
+| Story not found | Error: "Story {ID} not found in status.json" |
+| Current status doesn't match bus log | Warn user, show both, ask which to revert to |
+| Multiple rapid changes | Revert to the immediately previous status only |
+
+---
+
+## Example Usage
+
+```bash
+# Undo last status change
+/agileflow:status:undo STORY=US-0042
+
+# Typical flow: accidentally marked done, want to go back
+# Before: done -> After: in_progress
+```
+
+---
+
+## Rules
+
+- **Always preview**: Show current vs previous status before applying
+- **Always confirm**: Use AskUserQuestion before writes
+- **Always log**: Append status-reverted event to bus/log.jsonl
+- **Always validate**: Check JSON integrity after write
+- **One level**: Only undo one status change at a time (run again for more)
+- **Bus log is source of truth**: Previous status comes from event history
+
+---
+
+## Related Commands
+
+- `/agileflow:status` - Update story status
+- `/agileflow:story:view` - View story details
+- `/agileflow:story:edit` - Edit story fields
+- `/agileflow:board` - View kanban board

package/src/core/commands/status.md

@@ -1,5 +1,6 @@
 ---
 description: Update story status and progress
+phase: pre-story
 argument-hint: "STORY=<US-ID> STATUS=<status> [SUMMARY=<text>] [PR=<url>] [TO=<agent-id>]"
 compact_context:
   priority: high