agileflow 3.3.0 → 3.4.1

package/src/core/commands/learn/glossary.md

@@ -0,0 +1,135 @@
+---
+description: Auto-generate domain terminology glossary from code identifiers, comments, and documentation with definitions and context
+argument-hint: "[file|directory] [--update] [--format=table|definitions]"
+---
+
+# /agileflow:learn:glossary
+
+Auto-generate a domain terminology glossary by analyzing code identifiers, comments, and documentation. Maps domain-specific terms to their meaning in the codebase context.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:learn:glossary                                  # Generate from entire project
+/agileflow:learn:glossary src/                             # Generate from specific directory
+/agileflow:learn:glossary --update                         # Update existing glossary
+/agileflow:learn:glossary --format=definitions             # Definition-style output
+```
+
+---
+
+## How It Works
+
+1. **Extract identifiers** - Collect class names, function names, type names, constants
+2. **Analyze comments** - Find inline documentation and JSDoc descriptions
+3. **Detect domain terms** - Identify business/domain-specific vocabulary
+4. **Generate definitions** - Create clear, contextual definitions
+5. **Organize alphabetically** - Create a browsable reference
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = file or directory (default: current directory)
+UPDATE = --update flag to merge with existing glossary
+FORMAT = table (default) or definitions
+```
+
+### STEP 2: Extract Domain Terms
+
+Scan the codebase for domain-specific terms:
+
+**Sources**:
+- Class and interface names (e.g., `OrderFulfillment`, `PricingTier`)
+- Type aliases and enums (e.g., `type OrderStatus = 'pending' | 'shipped'`)
+- Constants (e.g., `MAX_RETRY_ATTEMPTS`, `DEFAULT_CURRENCY`)
+- Database table/column names
+- API endpoint names and parameters
+- JSDoc comments with @description
+- README and documentation files
+
+**Filtering**:
+- Exclude common programming terms (get, set, handle, process)
+- Exclude framework terms (useState, useEffect, middleware)
+- Focus on business/domain-specific vocabulary
+
+### STEP 3: Generate Definitions
+
+For each term, generate a definition:
+
+```markdown
+### {Term}
+
+**Type**: {class | type | function | constant | concept}
+**Found in**: `{file_path}`
+**Definition**: {clear, contextual definition}
+**Example**: `{code usage example}`
+**Related terms**: {list of related terms}
+```
+
+### STEP 4: Organize and Output
+
+```markdown
+# Domain Glossary
+
+**Project**: {project name}
+**Generated**: {date}
+**Terms**: {N}
+
+## A
+
+### Account
+**Type**: model
+**Found in**: `src/models/Account.ts`
+**Definition**: A registered user entity with authentication credentials and profile information.
+**Related**: User, Session, Subscription
+
+### ACL (Access Control List)
+**Type**: concept
+**Found in**: `src/auth/acl.ts`
+**Definition**: Permission rules mapping roles to allowed operations on resources.
+**Related**: Role, Permission, Authorization
+
+## B
+...
+```
+
+Save to `docs/08-project/glossary.md`
+
+### STEP 5: Offer Follow-Up
+
+```
+Glossary generated: [N] domain terms extracted from [M] files.
+
+Options:
+- Add/edit specific term definitions
+- Generate glossary for specific module
+- Explain a specific term in depth
+- Done
+```
+
+---
+
+## Output Formats
+
+**Table format** (default):
+| Term | Type | Definition | File |
+|------|------|------------|------|
+| Account | model | Registered user entity | models/Account.ts |
+
+**Definitions format** (--format=definitions):
+Full definition blocks with examples and related terms.
+
+---
+
+## Related Commands
+
+- `/agileflow:learn:tour` - Guided codebase walkthrough
+- `/agileflow:learn:explain` - Deep code explanation
+- `/agileflow:learn:patterns` - Design patterns catalog
+- `/agileflow:docs` - Documentation synchronization

package/src/core/commands/learn/patterns.md

@@ -0,0 +1,138 @@
+---
+description: Catalog and explain design patterns actually used in the codebase with real code examples and rationale
+argument-hint: "[pattern-name|category] [--generate]"
+---
+
+# /agileflow:learn:patterns
+
+Discover and catalog the design patterns actually used in the codebase. Shows real code examples, explains why each pattern was chosen, and documents the project's architectural vocabulary.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:learn:patterns                                  # Discover all patterns
+/agileflow:learn:patterns "repository"                     # Find repository pattern usage
+/agileflow:learn:patterns --generate                       # Generate full pattern catalog
+/agileflow:learn:patterns "error handling"                  # How errors are handled
+/agileflow:learn:patterns creational                       # Creational patterns only
+```
+
+---
+
+## How It Works
+
+1. **Scan codebase** - Identify design patterns in use
+2. **Extract examples** - Find real code examples of each pattern
+3. **Document rationale** - Explain why each pattern was chosen
+4. **Categorize** - Group by pattern category
+5. **Generate catalog** - Create a reference document
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = specific pattern name, category, or "all"
+GENERATE = --generate flag to create/update catalog file
+```
+
+### STEP 2: Scan for Patterns
+
+Use `Explore` agent to identify patterns:
+
+| Category | Patterns to Detect |
+|----------|-------------------|
+| **Creational** | Factory, Builder, Singleton, Module |
+| **Structural** | Adapter, Facade, Proxy, Decorator, Composite |
+| **Behavioral** | Observer/PubSub, Strategy, Command, Middleware, State Machine |
+| **Architectural** | MVC, Repository, Service Layer, CQRS, Event Sourcing |
+| **Frontend** | Container/Presenter, HOC, Render Props, Custom Hooks, Compound Components |
+| **Error Handling** | Error Boundary, Result Type, Error Middleware, Retry |
+| **Data** | DAO, Active Record, Data Mapper, Unit of Work |
+
+### STEP 3: Extract Examples
+
+For each detected pattern:
+
+```markdown
+## {Pattern Name}
+
+**Category**: {Creational/Structural/Behavioral/etc.}
+**Used in**: {N} places
+**Key files**: {list}
+
+### What It Is
+{Brief pattern description}
+
+### How We Use It
+{Explanation specific to this codebase}
+
+### Real Example
+\`\`\`{language}
+// {file_path}:{line}
+{actual code from the project}
+\`\`\`
+
+### Why This Pattern
+{Rationale for choosing this pattern over alternatives}
+
+### When to Use
+{Guidelines for when to apply this pattern in new code}
+```
+
+### STEP 4: Generate Catalog (if --generate)
+
+```markdown
+# Design Patterns Catalog
+
+**Project**: {project name}
+**Generated**: {date}
+**Patterns Found**: {N}
+
+## Pattern Overview
+
+| Pattern | Category | Usage Count | Key File |
+|---------|----------|-------------|----------|
+| {name} | {category} | {count} | {file} |
+
+## Detailed Patterns
+
+{Each pattern with full documentation}
+
+## Patterns NOT Used (and Why)
+
+| Pattern | Reason |
+|---------|--------|
+| {name} | {why it's not used or not appropriate} |
+
+## Conventions
+
+{Project-specific conventions for applying patterns}
+```
+
+Save to `docs/08-project/patterns/pattern-catalog-{YYYYMMDD}.md`
+
+### STEP 5: Offer Follow-Up
+
+```
+Pattern catalog: [N] patterns found across [M] files.
+
+Options:
+- Explain a specific pattern in more detail
+- See where to apply a pattern in new code
+- Generate full catalog document
+- Done
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:learn:tour` - Guided codebase walkthrough
+- `/agileflow:learn:explain` - Deep code explanation
+- `/agileflow:learn:glossary` - Domain terminology
+- `/agileflow:code:architecture` - Architecture health audit

package/src/core/commands/learn/tour.md

@@ -0,0 +1,126 @@
+---
+description: Guided interactive codebase walkthrough with annotated stops explaining architecture, data flow, and key design decisions
+argument-hint: "[topic|feature] [DEPTH=overview|detailed|deep-dive]"
+---
+
+# /agileflow:learn:tour
+
+Take an interactive guided tour through the codebase. The tour visits key files and explains architecture, data flow, and design decisions with annotated stops.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:learn:tour                                     # Full architecture tour
+/agileflow:learn:tour authentication                      # Tour the auth system
+/agileflow:learn:tour "data flow"                         # Follow data through the system
+/agileflow:learn:tour api DEPTH=deep-dive                 # Deep dive into API layer
+/agileflow:learn:tour "new developer"                     # Onboarding tour
+```
+
+---
+
+## How It Works
+
+1. **Discover project structure** - Map the codebase architecture
+2. **Generate tour route** - Plan stops based on topic and depth
+3. **Interactive walkthrough** - Visit each stop with explanation
+4. **Ask questions** - Pause at each stop for user questions
+5. **Generate tour notes** - Save the tour as a reference document
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TOPIC = specific feature/area or "full" for complete tour
+DEPTH = overview (5-8 stops) | detailed (10-15 stops) | deep-dive (15-25 stops)
+```
+
+### STEP 2: Discover Project Structure
+
+Use `Explore` agent to:
+- Map directory structure and architecture pattern
+- Identify entry points (main, index, app)
+- Find key configuration files
+- Detect framework and key libraries
+
+### STEP 3: Plan Tour Route
+
+Generate a sequence of stops based on topic:
+
+**Full Tour Route**:
+1. Entry point (main app file)
+2. Configuration and environment
+3. Routing/navigation structure
+4. Data models/schema
+5. API/service layer
+6. UI components (key ones)
+7. State management
+8. Authentication/authorization
+9. Testing approach
+
+**Feature-Specific Tour**: Follow the feature through:
+1. Entry point (where user triggers it)
+2. Route/handler
+3. Business logic
+4. Data access
+5. Side effects (email, queue, etc.)
+6. UI rendering
+
+### STEP 4: Interactive Walkthrough
+
+At each stop:
+
+```markdown
+## Stop {N}/{Total}: {Title}
+📍 `{file_path}`
+
+{Read and explain the key code in this file}
+
+**Why it matters**: {explanation of role in the system}
+**Key patterns**: {design patterns used}
+**Connected to**: {what files/modules this connects to}
+
+---
+Continue to next stop? [Next | Ask a question | Jump to specific stop | End tour]
+```
+
+### STEP 5: Generate Tour Notes
+
+Save a reference document:
+
+```markdown
+# Codebase Tour: {Topic}
+
+**Date**: {date}
+**Stops**: {N}
+**Coverage**: {files visited}
+
+## Tour Map
+1. {file} - {one-line summary}
+2. {file} - {one-line summary}
+...
+
+## Key Takeaways
+- {insight 1}
+- {insight 2}
+...
+
+## Architecture Diagram
+{Mermaid diagram of the system}
+```
+
+Save to `docs/08-project/tours/tour-{topic}-{YYYYMMDD}.md`
+
+---
+
+## Related Commands
+
+- `/agileflow:learn:explain` - Deep "why" explanation of specific code
+- `/agileflow:learn:patterns` - Catalog of design patterns used
+- `/agileflow:learn:glossary` - Domain terminology reference
+- `/agileflow:context:full` - Generate full project context

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

@@ -0,0 +1,151 @@
+---
+description: Generate and execute AST-based codemods for automated code transformations with dry-run preview and rollback support
+argument-hint: "[transformation] [file|directory] [--dry-run]"
+---
+
+# /agileflow:migrate:codemods
+
+Generate AST-based codemods for automated code transformations. Preview changes with dry-run before applying, with full rollback support.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:migrate:codemods "CommonJS to ESM" src/            # Generate CJS->ESM codemod
+/agileflow:migrate:codemods "class to function components"     # React class->function
+/agileflow:migrate:codemods "enzyme to testing-library"        # Test migration
+/agileflow:migrate:codemods "require to import" --dry-run      # Preview only
+/agileflow:migrate:codemods "update API v2 to v3" src/api/     # API migration
+```
+
+---
+
+## How It Works
+
+1. **Analyze transformation** - Understand the before/after patterns
+2. **Scan target files** - Find all instances of the "before" pattern
+3. **Generate transformation** - Create the codemod logic (using regex, AST, or direct edit)
+4. **Dry-run preview** - Show what would change without modifying files
+5. **Apply changes** - Execute the transformation with backup
+6. **Verify** - Run tests to confirm nothing broke
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TRANSFORMATION = description of the transformation
+TARGET = file or directory (default: current directory)
+DRY_RUN = --dry-run flag present (default: false, always dry-run first)
+```
+
+### STEP 2: Analyze Transformation
+
+Delegate to `agileflow-refactor` agent:
+- Understand the source and target patterns
+- Identify edge cases and exceptions
+- Determine if transformation is safe (reversible, no logic change)
+
+### STEP 3: Find All Instances
+
+Scan target files for the source pattern:
+- Count total instances
+- Group by file
+- Flag edge cases that need manual review
+
+### STEP 4: Generate Codemod
+
+Create the transformation logic:
+
+```markdown
+## Codemod: {Transformation Name}
+
+**Source Pattern**:
+\`\`\`javascript
+{before pattern}
+\`\`\`
+
+**Target Pattern**:
+\`\`\`javascript
+{after pattern}
+\`\`\`
+
+**Files Affected**: {N} files, {M} instances
+**Edge Cases**: {list of cases needing manual review}
+**Safety**: {safe/review-needed}
+```
+
+### STEP 5: Dry-Run Preview
+
+**ALWAYS show dry-run first** before applying:
+
+```
+Codemod Preview: "CommonJS to ESM"
+═══════════════════════════════════
+
+Files affected: 15
+Total transformations: 42
+Edge cases (manual review): 3
+
+Example transformation:
+  src/utils.js:1
+  - const { readFile } = require('fs');
+  + import { readFile } from 'fs';
+
+  src/utils.js:5
+  - module.exports = { helper };
+  + export { helper };
+
+Edge cases (skipped):
+  src/dynamic-loader.js:12 - dynamic require()
+  src/config.js:8 - conditional require()
+  src/legacy.js:1 - require with side effects
+
+Apply transformations? [Y/n/review-edge-cases]
+```
+
+### STEP 6: Apply and Verify
+
+After user approval:
+1. Create git stash or backup
+2. Apply transformations file by file
+3. Run linter to fix formatting
+4. Run tests to verify
+5. Show summary of changes
+
+### STEP 7: Offer Next Steps
+
+```
+Codemod applied: [N] transformations in [M] files. [E] edge cases need manual review.
+
+Options:
+- Run tests to verify changes (Recommended)
+- Review edge cases manually
+- Undo all changes (git checkout)
+- Continue with next migration step
+```
+
+---
+
+## Common Codemods
+
+| Transformation | Description |
+|---------------|-------------|
+| CJS to ESM | `require()` -> `import`, `module.exports` -> `export` |
+| Class to function | React class components -> function components with hooks |
+| Enzyme to RTL | Enzyme test assertions -> React Testing Library |
+| PropTypes to TypeScript | Runtime PropTypes -> TypeScript interfaces |
+| Callbacks to async/await | Callback-based code -> async/await |
+| var to const/let | `var` declarations -> `const`/`let` |
+
+---
+
+## Related Commands
+
+- `/agileflow:migrate:scan` - Detect migration opportunities
+- `/agileflow:migrate:plan` - Generate migration roadmap
+- `/agileflow:migrate:validate` - Post-migration verification
+- `/agileflow:verify` - Run tests after transformation

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