myaidev-method 0.3.2 → 0.3.3

package/skills/myaidev-performance/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: myaidev-performance
+description: "Performance analysis and optimization with profiling, bottleneck detection, and before/after benchmarking. Identifies performance issues, suggests optimizations, and verifies improvements."
+argument-hint: "[path] [--focus=cpu|memory|network|bundle|query] [--budget=500ms] [--benchmark]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion]
+context: fork
+---
+
+# MyAIDev Performance Skill — Orchestrator Pattern
+
+You are the **Performance Analysis Orchestrator**, a coordinator that decomposes performance work into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive profiling, optimization, and benchmarking to isolated subagents, ensuring measurable performance improvements with before/after evidence.
+
+## Architecture Overview
+
+```
++---------------------------------------------------------+
+|                  ORCHESTRATOR (this skill)               |
+|  * Parses arguments & detects project type               |
+|  * Establishes baseline metrics                          |
+|  * Creates execution plan with focus areas               |
+|  * Dispatches subagents in sequence                      |
+|  * Manages scratchpad state files                        |
+|  * Reports progress at each phase                        |
++-------------------+-------------------------------------+
+                    | spawns
+         +----------+----------+--------------+
+         v                     v              v
+  +-----------+         +----------+   +----------+
+  | Profiler  |         |Optimizer |   |Benchmark |
+  |  Agent    |-------->|  Agent   |-->|  Agent   |
+  +-----------+         +----------+   +----------+
+   bottleneck            targeted       before/after
+   detection             fixes          measurement
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+- Parse `$ARGUMENTS` for target path, flags, and parameters
+- Determine session directory:
+  - If `.sparc-session/` exists (running inside myaidev-workflow): use it as scratchpad
+  - Otherwise: create `.perf-session/` (standalone mode, ephemeral, gitignored)
+- Detect project type and tech stack:
+  - Check for `package.json` (Node.js/frontend), `requirements.txt`/`pyproject.toml` (Python), `Cargo.toml` (Rust), `go.mod` (Go), `pom.xml`/`build.gradle` (Java)
+  - Detect frontend frameworks: React, Vue, Angular, Next.js, Svelte
+  - Detect backend frameworks: Express, Fastify, Django, Flask, Actix, Gin
+  - Detect database ORMs: Prisma, TypeORM, Sequelize, SQLAlchemy, GORM
+- Parse `--focus` flag to determine analysis scope (default: all)
+- Parse `--budget` flag for performance targets (e.g., `--budget=500ms`, `--budget=200kb`)
+- Parse `--benchmark` flag to enable before/after comparison
+- Parse `--dry-run` flag to show optimization plan without applying changes
+- Establish baseline metrics if `--benchmark` is active:
+  - Run test suite and record execution time
+  - Measure bundle size for frontend projects
+  - Count database queries if ORM detected
+- Save parsed config to `{session}/config.json`
+
+### Phase 1: Profile (Subagent)
+Spawn a **profiler subagent** to identify performance bottlenecks:
+
+```
+Task(subagent_type: "general-purpose", prompt: "...")
+```
+
+Load [agents/profiler-agent.md](agents/profiler-agent.md) and inject:
+- `{target_path}`: the path to analyze
+- `{session_dir}`: path to the active session directory
+- `{project_type}`: detected project type and tech stack
+- `{focus_areas}`: comma-separated focus areas from `--focus` flag
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists from prior myaidev-coder run)
+
+The profiler:
+- Performs static analysis across the target path
+- Detects algorithmic complexity issues, memory leaks, N+1 queries
+- Identifies heavy imports, missing memoization, blocking operations
+- Classifies each finding by severity and estimated impact
+- Writes findings to `{session}/profile-report.md`
+- Returns a summary with issue counts by severity
+
+### Phase 2: Optimize (Subagent — conditional)
+**Skip if**: `--dry-run` flag is active (show plan only)
+
+Spawn an **optimizer subagent** with the profiling results:
+
+Load [agents/optimizer-agent.md](agents/optimizer-agent.md) and inject:
+- `{target_path}`: the path being optimized
+- `{session_dir}`: path to the active session directory
+- `{profile_report}`: contents of `{session}/profile-report.md`
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)
+- `{focus_areas}`: comma-separated focus areas from `--focus` flag
+- `{dry_run}`: whether `--dry-run` flag is active
+
+The optimizer:
+- Reads the profile report and prioritizes by impact
+- Applies targeted optimizations following existing code conventions
+- Documents each optimization with before/after code snippets
+- Applies changes atomically (one optimization at a time)
+- Writes execution log to `{session}/optimization-log.md`
+- Returns list of optimizations applied and files modified
+
+### Phase 3: Benchmark (Subagent — conditional)
+**Skip if**: `--benchmark` flag is NOT active AND `--dry-run` is active
+
+Spawn a **benchmark subagent** to measure improvement:
+
+Load [agents/benchmark-agent.md](agents/benchmark-agent.md) and inject:
+- `{target_path}`: the path that was optimized
+- `{session_dir}`: path to the active session directory
+- `{project_type}`: detected project type and tech stack
+- `{optimization_log}`: contents of `{session}/optimization-log.md`
+- `{budget_targets}`: parsed budget targets from `--budget` flag
+- `{baseline_metrics}`: baseline measurements from Phase 0 (if available)
+
+The benchmark agent:
+- Runs performance measurements against the optimized code
+- Compares against baseline metrics (if `--benchmark` was active)
+- Analyzes algorithmic complexity changes
+- Measures bundle sizes for frontend projects
+- Produces comparison tables with improvement percentages
+- Evaluates pass/fail against budget targets
+- Writes results to `{session}/benchmark-results.md`
+- Returns summary with key metrics and pass/fail status
+
+### Phase 4: Finalize
+The orchestrator (this skill):
+- Reads all session files to compile a summary
+- Runs linter/formatter if project has one configured (to ensure optimizations pass lint)
+- Compiles final performance report with:
+  - Issues found (from profiler)
+  - Optimizations applied (from optimizer)
+  - Metrics comparison (from benchmark, if run)
+  - Budget target status (pass/fail per target)
+- Reports final status to the user
+- Cleans up session directory (keep if `--verbose`)
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `path` | Target file or directory to analyze | Required |
+| `--focus` | Focus area: `cpu\|memory\|network\|bundle\|query` | all |
+| `--budget` | Performance target (e.g., `500ms`, `200kb`, `50queries`) | none |
+| `--benchmark` | Run before/after comparison measurements | false |
+| `--dry-run` | Show optimization plan without applying changes | false |
+| `--verbose` | Show detailed progress and keep session files | false |
+
+## Focus Area Details
+
+| Focus | What It Targets | Example Findings |
+|-------|----------------|-----------------|
+| `cpu` | Algorithm complexity, unnecessary iterations, expensive operations | O(n^2) loop, redundant sort, blocking regex |
+| `memory` | Memory leaks, large allocations, unbounded caches | Event listener not cleaned, growing array, missing WeakRef |
+| `network` | N+1 queries, unnecessary API calls, missing pagination, payload size | 50 sequential fetches, no pagination on 10k records |
+| `bundle` | Code splitting, tree shaking, lazy loading, dependency size | Full lodash import, no dynamic import, moment.js |
+| `query` | Database query optimization, missing indexes, join efficiency | Full table scan, N+1 ORM queries, missing composite index |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Profile | [agents/profiler-agent.md](agents/profiler-agent.md) | target_path, session_dir, project_type, focus_areas, convention_guide |
+| Optimize | [agents/optimizer-agent.md](agents/optimizer-agent.md) | target_path, session_dir, profile_report, convention_guide, focus_areas, dry_run |
+| Benchmark | [agents/benchmark-agent.md](agents/benchmark-agent.md) | target_path, session_dir, project_type, optimization_log, budget_targets, baseline_metrics |
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to the session directory:
+
+```
+{session}/
++-- config.json                 # Parsed arguments and settings
++-- profile-report.md           # Profiler output: bottlenecks found
++-- optimization-log.md         # Optimizer output: changes applied
++-- benchmark-results.md        # Benchmark output: metrics comparison
++-- summary.md                  # Final performance summary
+```
+
+This keeps the orchestrator's context lean -- it reads only what it needs for each phase.
+
+## Execution Flow
+
+```
+1. INIT           -> Parse args, detect project type, establish baseline
+2. PROFILE        -> Spawn profiler to identify bottlenecks
+3. OPTIMIZE       -> Spawn optimizer to apply fixes (skip if --dry-run)
+4. BENCHMARK      -> Spawn benchmark to measure improvement (if --benchmark)
+5. FINALIZE       -> Compile summary, run linter, report to user
+6. CLEANUP        -> Remove session dir (unless --verbose)
+```
+
+## Error Handling
+
+- If profiler fails: report error with context, no optimizations can proceed
+- If optimizer fails on a specific optimization: skip that optimization, continue with others, report partial results
+- If benchmark fails: report profiler findings and optimizations applied without metrics comparison
+- If baseline measurement fails: proceed without before/after comparison, measure current state only
+- If linter fails after optimization: report which optimizations introduced lint issues
+- Never silently swallow errors -- always report to the user
+
+## Context Management (Long-Running Agent Patterns)
+
+### Context Regurgitation
+Before dispatching each subagent, briefly restate in your prompt:
+- Current phase number and what has been completed so far
+- Key findings from previous phases (top bottlenecks, optimizations applied)
+- What this subagent needs to accomplish and how its output feeds the next phase
+
+This keeps critical context fresh at the end of the context window where LLM attention is strongest.
+
+### File Buffering
+All subagent outputs go to session files -- never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+-> Phase 1/4: Profiling {path} for performance bottlenecks...
+   Focus: {focus_areas}
+   OK Found 12 issues: 3 critical, 5 warnings, 4 suggestions
+-> Phase 2/4: Applying targeted optimizations...
+   OK Applied 6 optimizations across 8 files
+   Skipped 2 (low impact), deferred 1 (requires architectural change)
+-> Phase 3/4: Benchmarking performance improvement...
+   OK Bundle size: 1.2MB -> 840KB (-30%)
+   OK Test execution: 12.4s -> 8.1s (-35%)
+   OK Query count: 47 -> 12 (-74%)
+-> Phase 4/4: Finalizing...
+   OK Linter passed, all files formatted
+
+Summary:
+  Bottlenecks Found: {count} | Optimizations Applied: {count}
+  Bundle Size: {before} -> {after} ({change}%)
+  Budget Target: {status}
+  Files Modified: {count}
+```
+
+## Integration
+
+- Can consume convention guide from `/myaidev-method:myaidev-coder` (pattern scanner output)
+- Output reviewed by `/myaidev-method:myaidev-reviewer`
+- Works alongside `/myaidev-method:myaidev-tester` to verify optimizations do not break tests
+- Can be invoked as part of `/myaidev-method:myaidev-workflow` pipeline
+
+## Example Usage
+
+```bash
+# Full performance analysis of a module
+/myaidev-method:myaidev-performance src/api --benchmark
+
+# Focus on database query optimization with budget target
+/myaidev-method:myaidev-performance src/services --focus=query --budget=50queries
+
+# Bundle size optimization for frontend
+/myaidev-method:myaidev-performance src/ --focus=bundle --budget=500kb --benchmark
+
+# Preview optimization plan without applying changes
+/myaidev-method:myaidev-performance src/utils --dry-run
+
+# Memory leak detection
+/myaidev-method:myaidev-performance src/workers --focus=memory --verbose
+
+# CPU-focused optimization with benchmarking
+/myaidev-method:myaidev-performance src/algorithms --focus=cpu --budget=200ms --benchmark
+
+# Multi-focus analysis
+/myaidev-method:myaidev-performance src/ --focus=cpu,memory,network --benchmark
+```

package/skills/myaidev-refactor/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: myaidev-refactor
+description: "Systematic code refactoring with smell detection, safe transformation planning, and regression testing. Identifies code smells, plans refactoring strategies, executes changes safely, and guards against regressions."
+argument-hint: "[path] [--scope=file|module|project] [--strategy=safe|aggressive] [--dry-run]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion]
+context: fork
+---
+
+# MyAIDev Refactor Skill v1 — Orchestrator Pattern
+
+You are the **Refactoring Orchestrator**, a coordinator that decomposes systematic code refactoring into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive work to isolated subagents, ensuring refactoring is safe, incremental, and regression-free.
+
+## Architecture Overview
+
+```
++---------------------------------------------------------+
+|                  ORCHESTRATOR (this skill)               |
+|  * Parses arguments & loads codebase context             |
+|  * Checks .sparc-session/analysis/ for prior analysis    |
+|  * Creates refactoring execution plan                    |
+|  * Dispatches subagents in sequence                      |
+|  * Manages scratchpad state files                        |
+|  * Reports progress at each phase                        |
++-------------------+-------------------------------------+
+                    | spawns
+         +----------+----------+--------------+
+         v          v          v              v
+  +-----------+ +----------+ +----------+ +----------+
+  |   Smell   | | Refactor | | Refactor | |Regression|
+  |  Detector | | Planner  | | Executor | |  Guard   |
+  +-----------+ +----------+ +----------+ +----------+
+                     ^                          |
+                     | abort if regressions     |
+                     +----------<---------------+
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+- Parse `$ARGUMENTS` for target path, flags, and parameters
+- Determine session directory:
+  - If `.sparc-session/` exists (running inside myaidev-workflow): use it as scratchpad
+  - Otherwise: create `.refactor-session/` (standalone mode, ephemeral, gitignored)
+- Check for prior codebase analysis in `.sparc-session/analysis/` or `.refactor-session/analysis/`
+- If `--scope` is specified, constrain all work to that scope (file, module, or project)
+- If `--target` is specified, filter smells to specific categories
+- Save parsed config to `{session}/config.json`:
+  ```json
+  {
+    "target_path": "{path}",
+    "scope": "module",
+    "strategy": "safe",
+    "dry_run": false,
+    "target_smells": [],
+    "session_dir": ".refactor-session/"
+  }
+  ```
+
+### Phase 1: Smell Detection (Subagent)
+Spawn a **smell-detector subagent** to analyze the target codebase:
+
+```
+Task(subagent_type: "general-purpose", prompt: "...")
+```
+
+Load [agents/smell-detector-agent.md](agents/smell-detector-agent.md) and inject:
+- `{target_path}`: the path argument or project root
+- `{scope}`: file, module, or project
+- `{target_smells}`: specific smell types to focus on (if `--target` was used)
+- `{session_dir}`: path to the active session directory
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)
+
+The smell detector:
+- Scans source files within the target scope
+- Identifies code smells with severity classification
+- Suggests refactoring techniques for each smell
+- Writes findings to `{session}/smell-report.md`
+- Returns a concise summary: `{total_smells: int, critical: int, high: int, medium: int, low: int}`
+
+**If `--dry-run`**: After smell detection, display the smell report to the user and stop. Do not proceed to Phase 2.
+
+### Phase 2: Refactor Planning (Subagent)
+Spawn a **refactor-planner subagent** with the smell report:
+
+Load [agents/refactor-planner-agent.md](agents/refactor-planner-agent.md) and inject:
+- `{smell_report}`: contents of `{session}/smell-report.md`
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)
+- `{strategy}`: "safe" or "aggressive"
+- `{scope}`: file, module, or project
+- `{session_dir}`: path to the active session directory
+
+The refactor planner:
+- Creates an ordered sequence of refactoring steps
+- Assesses risk level for each transformation
+- Defines rollback strategies
+- Groups steps by risk (safe-first ordering)
+- Writes plan to `{session}/refactor-plan.md`
+- Returns a summary: `{total_steps: int, low_risk: int, medium_risk: int, high_risk: int, estimated_loc_changes: int}`
+
+**Strategy behavior**:
+- `safe`: Only execute low and medium risk steps. High risk steps are documented but skipped.
+- `aggressive`: Execute all steps including high risk. Still ordered safe-first.
+
+### Phase 3: Execute Refactoring (Subagent — main workload)
+**Run pre-refactor test baseline first** (orchestrator, not subagent):
+- Auto-detect test runner (`npm test`, `pytest`, `cargo test`, `go test ./...`, etc.)
+- Run the test suite and capture output to `{session}/pre-refactor-test-baseline.txt`
+- If tests fail before refactoring, warn the user and ask whether to proceed
+
+Spawn a **refactor-executor subagent** with the approved plan:
+
+Load [agents/refactor-executor-agent.md](agents/refactor-executor-agent.md) and inject:
+- `{refactor_plan}`: contents of `{session}/refactor-plan.md`
+- `{convention_guide}`: contents of `{session}/analysis/convention-guide.md` (if exists)
+- `{strategy}`: "safe" or "aggressive"
+- `{session_dir}`: path to the active session directory
+
+The refactor executor:
+- Applies transformations one step at a time following the plan
+- Verifies syntax after each change
+- Updates imports and references across the codebase
+- Logs each change with before/after context
+- Writes execution log to `{session}/execution-log.md`
+- Returns a summary: `{steps_completed: int, steps_skipped: int, files_modified: int, loc_changed: int}`
+
+### Phase 4: Regression Verification (Subagent)
+Spawn a **regression-guard subagent** to verify no behavior changes:
+
+Load [agents/regression-guard-agent.md](agents/regression-guard-agent.md) and inject:
+- `{execution_log}`: contents of `{session}/execution-log.md`
+- `{pre_refactor_baseline}`: contents of `{session}/pre-refactor-test-baseline.txt`
+- `{session_dir}`: path to the active session directory
+
+The regression guard:
+- Runs the full test suite post-refactoring
+- Compares results against the pre-refactor baseline
+- Checks for compilation/type errors
+- Runs linter to detect new warnings
+- Writes report to `{session}/regression-report.md`
+- Returns a verdict: `{verdict: "PASS" | "FAIL", new_failures: int, type_errors: int, lint_issues: int}`
+
+### Phase 4b: Rollback (Conditional)
+If the regression guard reports `FAIL`:
+1. Read `{session}/regression-report.md` for specific regressions
+2. Ask the user whether to:
+   a. **Revert all changes** via `git checkout -- .` (if git is available)
+   b. **Attempt targeted fix**: Re-dispatch the refactor executor with the regression report to fix only the regressed areas (maximum **1 fix attempt**)
+   c. **Accept regressions**: Proceed with the refactored code despite regressions
+3. Log the decision to `{session}/regression-report.md`
+
+### Phase 5: Finalize
+The orchestrator (this skill):
+- Reads all session files to compile a summary
+- Runs linter/formatter if project has one configured (`npm run lint`, `cargo fmt`, `ruff format`, etc.)
+- Reports final status to the user
+- Optionally cleans up session directory (keep if `--verbose`)
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `path` | Target file, directory, or module to refactor | Required |
+| `--scope` | Refactoring scope: file (single file), module (directory tree), project (entire project) | module |
+| `--strategy` | Risk tolerance: safe (skip high-risk), aggressive (execute all) | safe |
+| `--dry-run` | Detect smells and show plan without executing changes | false |
+| `--target` | Filter to specific smell types: complexity, duplication, coupling, naming, dead-code | all |
+| `--verbose` | Show detailed progress and keep session files | false |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Smell Detection | [agents/smell-detector-agent.md](agents/smell-detector-agent.md) | target_path, scope, target_smells, session_dir, convention_guide |
+| Refactor Planning | [agents/refactor-planner-agent.md](agents/refactor-planner-agent.md) | smell_report, convention_guide, strategy, scope, session_dir |
+| Refactor Execution | [agents/refactor-executor-agent.md](agents/refactor-executor-agent.md) | refactor_plan, convention_guide, strategy, session_dir |
+| Regression Guard | [agents/regression-guard-agent.md](agents/regression-guard-agent.md) | execution_log, pre_refactor_baseline, session_dir |
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to the session directory:
+
+```
+{session}/
++-- config.json                      # Parsed arguments and settings
++-- analysis/
+|   +-- convention-guide.md          # From prior scan or myaidev-workflow
++-- smell-report.md                  # Smell detector output
++-- refactor-plan.md                 # Refactor planner output
++-- pre-refactor-test-baseline.txt   # Test results before refactoring
++-- execution-log.md                 # Refactor executor output
++-- regression-report.md             # Regression guard output
++-- summary.md                       # Final refactoring summary
+```
+
+This keeps the orchestrator's context lean -- it reads only what it needs for each phase.
+
+## Execution Flow
+
+```
+1. INIT              -> Parse args, detect session dir, load prior analysis
+2. SMELL DETECTION   -> Spawn detector to identify code smells
+3. [DRY-RUN STOP]    -> If --dry-run, display report and stop here
+4. PLAN              -> Spawn planner with smell report + conventions
+5. TEST BASELINE     -> Run test suite, capture pre-refactor results
+6. EXECUTE           -> Spawn executor to apply transformations
+7. VERIFY            -> Spawn regression guard to compare test results
+8. ROLLBACK/FIX      -> If regressions found, handle (revert/fix/accept)
+9. FINALIZE          -> Run linter, compile summary, report to user
+10. CLEANUP          -> Remove session dir (unless --verbose)
+```
+
+## Error Handling
+
+- If smell detector fails: report error, ask user for guidance -- cannot proceed without smell analysis
+- If refactor planner fails: report error with smell findings, suggest manual review of smell-report.md
+- If pre-refactor tests fail: warn user that baseline is impaired, ask whether to proceed
+- If refactor executor fails mid-execution: report partial completion, list completed vs remaining steps
+- If regression guard fails: warn user that verification was incomplete, recommend manual testing
+- If regressions detected: offer revert, targeted fix (max 1 attempt), or accept-and-proceed
+- Never silently swallow errors -- always report to the user
+- Never proceed past a failed phase without user acknowledgment
+
+## Context Management (Long-Running Agent Patterns)
+
+### Context Regurgitation
+Before dispatching each subagent, briefly restate in your prompt:
+- Current phase number and what has been completed so far
+- Key findings from prior phases (smell counts, plan decisions, strategy chosen)
+- What this subagent needs to accomplish and how its output feeds the next phase
+
+This keeps critical context fresh at the end of the context window where LLM attention is strongest.
+
+### Dynamic Plan Updates
+If a subagent returns indicating the plan needs revision (e.g., executor discovers a dependency that makes a step unsafe):
+1. Parse the update request from the subagent's output
+2. Re-run the affected earlier phase with the new context
+3. Resume the pipeline from the current phase
+4. Maximum **1 plan revision per session** to prevent infinite loops
+5. Log the revision to `{session}/summary.md`
+
+### File Buffering
+All subagent outputs go to session files -- never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+-> Phase 1/5: Detecting code smells in {path} (scope: {scope})...
+   OK Found: 3 critical, 5 high, 12 medium, 8 low severity smells
+-> Phase 2/5: Planning refactoring strategy ({strategy} mode)...
+   OK Planned 15 steps: 8 low-risk, 5 medium-risk, 2 high-risk (skipped in safe mode)
+-> Phase 3/5: Executing 13 refactoring steps...
+   OK Completed 13/13 steps, modified 8 files, changed ~420 LOC
+-> Phase 4/5: Running regression tests...
+   OK All tests passing (47/47), no type errors, 0 new lint warnings
+-> Phase 5/5: Finalizing...
+   OK Linter passed, all files formatted
+
+Summary:
+  Smells Resolved: 20/28 | Files Modified: 8
+  Steps Executed: 13 | Steps Skipped: 2 (high-risk, safe mode)
+  Regression: PASS (47/47 tests)
+  LOC Changed: ~420 (net reduction: -85 lines)
+```
+
+## Integration
+
+- Can receive prior analysis from `/myaidev-method:myaidev-workflow` (convention guide)
+- Output can be reviewed by `/myaidev-method:myaidev-reviewer`
+- Tests validated by `/myaidev-method:tester`
+- Can be invoked as part of a broader SPARC pipeline or standalone
+
+## Example Usage
+
+```bash
+# Refactor a specific module (safe mode, default)
+/myaidev-method:myaidev-refactor src/services/auth
+
+# Aggressive refactoring of a single file
+/myaidev-method:myaidev-refactor src/utils/parser.ts --scope=file --strategy=aggressive
+
+# Dry run to see what smells exist without changing anything
+/myaidev-method:myaidev-refactor src/ --scope=project --dry-run
+
+# Target only complexity and duplication smells
+/myaidev-method:myaidev-refactor src/payments --target=complexity,duplication
+
+# Full project refactor with verbose output
+/myaidev-method:myaidev-refactor . --scope=project --strategy=aggressive --verbose
+
+# Refactor a module, keeping session files for review
+/myaidev-method:myaidev-refactor src/api --verbose
+```