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

package/content/plugins/refactoring/skills/agileflow-refactor/workflows/extract-module.md

@@ -0,0 +1,226 @@
+# Workflow: Extract Module
+
+**Triggers:** "extract this to its own file", "this class is too big", "make this reusable", "this code belongs in a shared utility", user identifies a function or class that should live somewhere else
+
+**Goal:** Extract a cohesive set of functions or a class from a large file into its own well-named module, with correct imports updated across all callers.
+
+---
+
+## When to extract a module
+
+| Signal                                                   | Extraction candidate                                |
+| -------------------------------------------------------- | --------------------------------------------------- |
+| A class handles multiple concerns                        | Split by responsibility (see Extract Class pattern) |
+| A utility function is duplicated across files            | Extract to `utils/` or `lib/`                       |
+| A domain concept is embedded in infrastructure code      | Extract domain object                               |
+| A file is > 300 lines                                    | Candidate for splitting                             |
+| Other files are copying the same logic                   | Extract shared module                               |
+| A function group doesn't depend on the class it lives in | Extract to standalone module                        |
+
+---
+
+## Inputs needed
+
+| Input           | Required | How to get it                                   |
+| --------------- | -------- | ----------------------------------------------- |
+| Source file     | Yes      | File path                                       |
+| What to extract | Yes      | Function names, class section, or "the X logic" |
+| Target location | No       | I'll suggest based on project conventions       |
+| Existing tests  | Check    | Find adjacent test file                         |
+
+---
+
+## Steps
+
+### Step 1: Understand the current dependencies
+
+Before extracting, map what the candidate code depends on:
+
+```
+What will move:
+  - calculateOrderTotal(order)
+  - applyDiscount(subtotal, couponCode)
+  - TAX_RATE constant
+
+What it depends on:
+  - Coupon model (from '../models/coupon')
+  - formatCurrency() utility (from '../utils/format')
+  - Logger (from '../lib/logger')
+
+What depends on it (callers in the current file):
+  - processOrder() calls calculateOrderTotal()
+
+Other callers (outside the current file):
+  - grep -r "calculateOrderTotal" → none (only internal)
+```
+
+This map becomes the new module's import list.
+
+### Step 2: Determine the target location
+
+Follow the project's existing conventions:
+
+| What you're extracting                 | Likely destination                     |
+| -------------------------------------- | -------------------------------------- |
+| General utility function               | `src/utils/`                           |
+| Domain logic (pricing, shipping, etc.) | `src/domain/` or `src/lib/`            |
+| Data access / query                    | `src/repositories/`                    |
+| External service adapter               | `src/integrations/` or `src/adapters/` |
+| Type definitions                       | `src/types/`                           |
+| Configuration                          | `src/config/`                          |
+
+If the project doesn't have clear conventions, use the location closest to where the extracted code is most heavily used.
+
+### Step 3: Write the new module file
+
+1. Create the new file at the target path
+2. Copy (don't yet delete) the code from the source
+3. Add the necessary imports the code needs
+4. Export everything that callers will need
+
+```js
+// src/pricing/order-total.js (extracted from src/services/order-service.js)
+
+import { Coupon } from "../models/coupon.js";
+import { logger } from "../lib/logger.js";
+
+export const TAX_RATE = 0.1;
+
+export async function calculateOrderTotal(order) {
+  const subtotal = order.lineItems.reduce(
+    (sum, item) => sum + item.price * item.qty,
+    0,
+  );
+  const discounted = await applyDiscount(subtotal, order.couponCode);
+  return discounted * (1 + TAX_RATE);
+}
+
+async function applyDiscount(subtotal, couponCode) {
+  if (!couponCode) return subtotal;
+  const coupon = await Coupon.findByCode(couponCode);
+  if (!coupon || !coupon.isValid) return subtotal;
+  return subtotal * (1 - coupon.discountPct / 100);
+}
+```
+
+### Step 4: Update the source file to import from the new module
+
+In the original file:
+
+```js
+// Before (in src/services/order-service.js):
+// ... calculateOrderTotal and applyDiscount defined here (40 lines) ...
+
+// After:
+import { calculateOrderTotal, TAX_RATE } from "../pricing/order-total.js";
+// ... rest of the file unchanged, the function calls work as before ...
+```
+
+### Step 5: Update all other callers
+
+Search for all usages of the extracted symbols outside the source file:
+
+```bash
+grep -r "calculateOrderTotal" src/
+grep -r "TAX_RATE" src/
+```
+
+Update each import to point to the new module.
+
+### Step 6: Run tests
+
+Run the full test suite. All tests should pass without modification — if tests break, the extraction changed observable behaviour (find and fix before continuing).
+
+### Step 7: Write or update tests for the new module
+
+The extracted module should have its own test file:
+
+```
+src/pricing/order-total.js       (new module)
+src/pricing/order-total.test.js  (new test file)
+```
+
+If the original tests covered this code through integration tests, those still pass. But also add direct unit tests for the new module — they're now fast and isolated.
+
+### Step 8: Delete the original code
+
+Only after:
+
+- [ ] New module file created and tested
+- [ ] Source file imports from the new module
+- [ ] All other callers updated
+- [ ] All tests pass
+
+Delete (or remove) the original code from the source file.
+
+### Step 9: Final verification
+
+```bash
+# No broken imports
+npx tsc --noEmit    # TypeScript
+# or
+node --check src/services/order-service.js  # Node.js ESM
+
+# Tests pass
+npm test
+
+# No references to old location remain
+grep -r "calculateOrderTotal" src/   # should all point to new location
+```
+
+### Step 10: Commit
+
+Commit in two parts for cleaner history:
+
+```bash
+git add src/pricing/order-total.js src/pricing/order-total.test.js
+git commit -m "refactor: extract order total calculation to pricing module"
+
+git add src/services/order-service.js src/  # remaining callers
+git commit -m "refactor: update callers to import from pricing/order-total"
+```
+
+Or a single commit if the change is small:
+
+```bash
+git commit -m "refactor: extract calculateOrderTotal to src/pricing/order-total.js"
+```
+
+---
+
+## Handling circular dependencies
+
+If the extraction would create a circular dependency (A imports B, B imports A):
+
+1. **Identify the cycle**: draw the dependency chain
+2. **Extract the shared code** into a third module that neither A nor B imports (the shared dependency)
+3. Both A and B import from the third module
+
+```
+Before: service.js ↔ repository.js (circular)
+After:  service.js → shared-types.js ← repository.js (no cycle)
+```
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+After analysis, present as a numbered plan:
+
+```
+Extraction plan for calculateOrderTotal from order-service.js:
+
+New module: src/pricing/order-total.js
+Exports: calculateOrderTotal(), TAX_RATE
+Callers to update: 1 (only order-service.js uses it)
+
+Steps:
+1. Create src/pricing/order-total.js with the extracted code
+2. Update order-service.js to import from the new module
+3. Run tests to confirm behaviour preserved
+4. Write direct unit tests for the new module
+
+Reply with "proceed" to apply all steps, or tell me what to change.
+```

package/content/plugins/refactoring/skills/agileflow-refactor/workflows/safe-refactor.md

@@ -0,0 +1,169 @@
+# Workflow: Safe Refactor
+
+**Triggers:** "refactor this", "clean this up", "this is too complex", user identifies technical debt or asks to improve code quality
+
+**Goal:** Apply a refactoring pattern safely — with tests confirmed, impact analysed, pattern applied, and behaviour verified.
+
+---
+
+## Inputs needed
+
+| Input           | Required  | How to get it                                               |
+| --------------- | --------- | ----------------------------------------------------------- |
+| Target code     | Yes       | File path or paste the code                                 |
+| Motivation      | Preferred | Why does this need refactoring? What problem does it solve? |
+| Existing tests  | Check     | Search for adjacent test file                               |
+| Desired outcome | No        | What should the code feel like after?                       |
+
+---
+
+## Steps
+
+### Step 1: Read and understand the code
+
+Read the target file completely. Build a mental model of:
+
+- What does this code do?
+- What are the inputs and outputs?
+- What side effects does it have?
+- What are the callers? (do a quick search)
+
+Don't propose a refactoring until you fully understand what the code is doing.
+
+### Step 2: Identify the code smells
+
+Cross-reference with `references/refactoring-patterns.md` to match the code to named smells:
+
+```
+Smells detected in src/services/order-service.js:
+  - Long method: processOrder() is 87 lines
+  - Magic numbers: 0.1 used on line 34 (tax rate?), 86400000 on line 62 (ms in a day?)
+  - Duplicate code: email validation on lines 12 and 45 — same logic
+  - Missing early returns: 4 levels of nesting on line 28–61
+```
+
+### Step 3: Check the safety preconditions
+
+Work through `references/safety-checks.md` — pre-refactoring checklist:
+
+- [ ] Tests exist?
+- [ ] Tests pass right now?
+- [ ] Impact analysis complete?
+- [ ] Not a public API change without a plan?
+
+**If tests don't exist:**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "No tests found for this code. Safe refactoring requires a test safety net.",
+  "header": "How to proceed",
+  "multiSelect": false,
+  "options": [
+    {"label": "Write characterisation tests first (Recommended)", "description": "I'll write tests that document the current behaviour — then we refactor safely"},
+    {"label": "Write proper tests based on expected behaviour", "description": "Better for greenfield or well-understood code — takes longer but produces better tests"},
+    {"label": "Proceed without tests (I accept the risk)", "description": "Only for trivial renames or obvious dead code — I'll flag any risks"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 4: Propose the refactoring plan
+
+Before writing any code, present the plan:
+
+```
+Proposed refactoring for src/services/order-service.js:
+
+1. Extract `calculateOrderTotal(order)` from processOrder() (lines 28–47)
+   Pattern: Extract Function
+   Risk: Low — pure function, well-tested path
+
+2. Replace tax magic number 0.1 with named constant TAX_RATE
+   Pattern: Replace Magic Number
+   Risk: Very low — rename only
+
+3. Replace nested conditional on lines 28–61 with guard clauses
+   Pattern: Guard Clause
+   Risk: Low — same logic, different structure; tests will verify
+
+4. Extract duplicate email validation to shared validateEmail() utility
+   Pattern: Consolidate Duplicate Code
+   Risk: Low — two call sites, both covered by tests
+
+Each step will be a separate commit. Shall I proceed?
+```
+
+Show this plan and get confirmation before writing code.
+
+### Step 5: Apply refactorings one at a time
+
+For each step:
+
+1. Make the specific change
+2. Run tests (or ask the user to run them)
+3. Confirm tests still pass
+4. Commit with a descriptive message: `refactor: extract calculateOrderTotal function`
+
+**Do not proceed to the next step if tests fail.**
+
+### Step 6: Final verification
+
+After all steps are complete:
+
+- [ ] All tests pass
+- [ ] No new linting errors
+- [ ] Code reads as intended (spot-check the key sections)
+- [ ] Commit history is clean (each commit is one pattern, one purpose)
+
+### Step 7: Offer next steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Refactoring complete. Applied {N} patterns to {file}. All tests pass.",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Review the final diff (Recommended)", "description": "I'll show the before/after comparison so you can confirm it looks right"},
+    {"label": "Run the tests to confirm", "description": "Run the test suite and show the output"},
+    {"label": "Continue refactoring — there are more issues", "description": "I found {M} additional smells — want me to plan the next pass?"},
+    {"label": "That's enough for now", "description": "Commit and move on"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Quick refactoring (trivial changes)
+
+For very low-risk refactorings (rename a variable, extract a constant), skip the full flow:
+
+1. Make the change
+2. Confirm tests pass
+3. Done
+
+Flag: "This is a trivial rename — no plan needed. Proceeding directly."
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+Present the plan as a numbered list and ask for confirmation:
+
+```
+Proposed refactoring plan for {file}:
+
+1. Extract calculateOrderTotal() — Extract Function pattern
+2. Replace magic number 0.1 with TAX_RATE constant
+3. Replace nested conditional with guard clauses
+4. Extract duplicate email validation to shared utility
+
+Reply with:
+- "proceed" — I'll apply all steps sequentially, one commit each
+- "just step N" — I'll apply only that step
+- "revise" — tell me what to change about the plan
+```