agileflow 3.4.0 → 3.4.1

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

@@ -0,0 +1,118 @@
+---
+description: Deep explanation of code areas - not just what the code does, but WHY it was written this way, with git history and design reasoning
+argument-hint: "[file|function|feature] [DEPTH=quick|thorough]"
+---
+
+# /agileflow:learn:explain
+
+Get a deep "why" explanation of code areas. Goes beyond what the code does to explain why it was written this way, what alternatives were considered, and what historical context shaped it.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:learn:explain src/auth/middleware.ts             # Explain specific file
+/agileflow:learn:explain handleCheckout                     # Explain a function
+/agileflow:learn:explain "the caching layer"                # Explain a concept/area
+/agileflow:learn:explain app/api/ DEPTH=thorough            # Thorough explanation
+```
+
+---
+
+## How It Works
+
+1. **Find the code** - Locate the target file, function, or feature
+2. **Read the code** - Understand what it does
+3. **Check git history** - Find when/why it was written or changed
+4. **Analyze design decisions** - Explain the "why" behind the approach
+5. **Surface alternatives** - What other approaches could have been used
+6. **Present explanation** - Clear, educational explanation with context
+
+---
+
+## Step-by-Step Process
+
+### STEP 1: Parse Arguments
+
+```
+TARGET = file path, function name, or feature description
+DEPTH = quick (3-5 min read) or thorough (10-15 min read)
+```
+
+### STEP 2: Find and Read Code
+
+1. If file path: read the file directly
+2. If function name: search codebase for the function
+3. If feature description: use `Explore` agent to find relevant files
+
+### STEP 3: Analyze Git History
+
+```bash
+git log --follow --oneline {file}        # See file history
+git log -p --follow -S "{function}" -- . # Find when function was added/changed
+git blame {file}                          # See who wrote each line and when
+```
+
+### STEP 4: Generate Explanation
+
+Structure the explanation:
+
+```markdown
+## What This Code Does
+
+{Clear explanation of the code's purpose and behavior}
+
+## Why It's Written This Way
+
+{Design reasoning - what constraints or requirements led to this approach}
+
+### Historical Context
+{Git history insights - when it was written, major changes, why changes were made}
+
+### Design Decisions
+| Decision | Choice Made | Why | Alternative Considered |
+|----------|-------------|-----|----------------------|
+| {decision} | {choice} | {reasoning} | {what else could have been done} |
+
+## How It Connects
+
+{Data flow diagram showing where this code fits in the system}
+
+```mermaid
+graph LR
+    A[Input] --> B[This Code] --> C[Output]
+    B --> D[Side Effects]
+```
+
+## Key Concepts
+
+| Concept | Explanation |
+|---------|-------------|
+| {term} | {what it means in this context} |
+
+## Gotchas
+
+{Non-obvious behaviors, edge cases, or things to be careful about}
+```
+
+### STEP 5: Offer Follow-Up
+
+```
+Explanation complete for {target}.
+
+Options:
+- Explain a related area
+- Tour the broader system this belongs to
+- See similar patterns elsewhere in the codebase
+- Done
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:learn:tour` - Guided codebase walkthrough
+- `/agileflow:learn:patterns` - Design patterns catalog
+- `/agileflow:learn:glossary` - Domain terminology
+- `/agileflow:context:full` - Full project context

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