Updated refactor.md

Author: StanBarrows

README.md

@@ -56,7 +56,19 @@ Boost automatically discovers skills from `vendor/codebar-ag/coding-guidelines/r
 
 If your editor supports MCP (Model Context Protocol), configure it to use the Boost MCP server for full context. See the [Laravel Boost documentation](https://laravel.com/docs/boost) for your editor's setup.
 
-### Step 5: Override skills locally (optional)
+### Step 5: Refactor command (Cursor)
+
+To run a full codebase refactor against all guidelines:
+
+1. Ensure `.cursor/commands/` exists in your project
+2. Copy the refactor prompt:
+   - From package: `cp vendor/codebar-ag/coding-guidelines/refactor.md .cursor/commands/refactor.md`
+   - Or from guidelines (if synced): `cp guidelines/refactor.md .cursor/commands/refactor.md`
+3. In Cursor, type `/refactor` and run the command
+
+The prompt instructs the AI to discover all skills, map them to your codebase, analyze for violations, and refactor for full compliance. Use it when newly adopting guidelines or to cross-check AI implementations.
+
+### Step 6: Override skills locally (optional)
 
 To customize a skill for your project, create a file at `.ai/skills/{skill-name}/SKILL.md`. Your local version takes precedence over the package default.
 
@@ -80,7 +92,7 @@ To sync the complete guidelines repo (`.github/prompts`, `RULES.md`, etc.) into
 }
 ```
 
-Then run `composer sync-guidelines`. This clones or pulls the repo into `guidelines/` at your project root.
+Then run `composer sync-guidelines`. This clones or pulls the repo into `guidelines/` at your project root and copies `refactor.md` to `.cursor/commands/refactor.md` for use with Cursor slash commands.
 
 ---
 

refactor.md

@@ -0,0 +1,106 @@
+# Codebase Refactor — Full Guidelines Compliance
+
+You are refactoring a Laravel codebase to achieve 100% alignment with **codebar-ag coding guidelines**. This prompt is used when (a) newly adopting guidelines in an existing project, or (b) cross-checking AI-generated implementations for compliance.
+
+---
+
+## 1. Skill Discovery
+
+Locate skills from one of these paths (check in order; first existing wins):
+
+- `vendor/codebar-ag/coding-guidelines/resources/boost/skills/`
+- `guidelines/resources/boost/skills/`
+
+Project overrides in `.ai/skills/{skill-name}/SKILL.md` take precedence over package defaults.
+
+**Action:** List all `SKILL.md` files. For each skill, extract:
+
+- `name` (from frontmatter or folder)
+- `Tags` — the first path-like value (e.g. `app/Models/**/*.php`) is the glob for file discovery
+- `Rules`, `Anti-Patterns`, `Examples` — apply these when analyzing and refactoring
+
+---
+
+## 2. Processing Order (Dependency-Aware)
+
+Process skills in this order to avoid repeated edits and respect dependencies:
+
+| Phase | Skills |
+|-------|--------|
+| Foundation | `general`, `php`, `helperfunctions` |
+| Data layer | `migrations`, `enums`, `models`, `traits` |
+| Backend core | `actions`, `services`, `dto`, `exceptions`, `interfaces` |
+| HTTP layer | `formrequests`, `controllers`, `middleware`, `requests`, `resources`, `routing` |
+| Infrastructure | `commands`, `jobs`, `events`, `observers`, `policies` |
+| Frontend | `blade`, `design`, `livewire`, `tailwind`, `translations` |
+| Integrations | `saloon`, `docuware`, `albatros` (only if matching files exist) |
+| Helpers | `helpers` |
+| Testing | `phpunit`, `pesttesting`, `phpstan`, `dusk` |
+
+---
+
+## 3. Per-Skill Workflow
+
+For each skill in order:
+
+1. **Match files** — Find all files in the workspace that match the skill’s glob patterns from Tags (e.g. `app/Http/Controllers/**/*.php`).
+2. **Skip if empty** — If no files match (e.g. no Albatros service), skip the skill.
+3. **Read skill** — Load the full `SKILL.md` content for Rules, Examples, and Anti-Patterns.
+4. **Analyze** — Check each matching file against the Rules and Anti-Patterns.
+5. **Refactor** — Fix violations using the skill’s Examples. Preserve behavior; do not introduce breaking changes.
+6. **Batch edits** — Group edits by skill (e.g. all controller fixes in one pass).
+
+---
+
+## 4. Efficiency Directives
+
+- **Incremental changes** — Prefer small, reviewable edits over large rewrites.
+- **Prioritize when large** — If the scope is large, produce a prioritized compliance report and refactor in phases.
+- **Cross-check mode** — When validating recent AI work, focus first on recently changed files, then broaden if needed.
+- **Avoid redundant passes** — Process skills in the defined order so earlier fixes are not undone by later ones.
+
+---
+
+## 5. Output Format
+
+### Phase A: Compliance Report (before edits)
+
+Produce a concise report:
+
+- Skills that apply (have matching files)
+- Skills that are skipped (no matching files)
+- Per skill: files with violations, brief description of each violation
+- Summary: total violations, suggested commit grouping
+
+### Phase B: Refactoring (skill-by-skill)
+
+For each skill with violations:
+
+1. State the skill name and what is being fixed.
+2. Apply the changes.
+3. Suggest a commit message for that batch of changes.
+
+---
+
+## 6. Tags-to-Glob Mapping
+
+Skills use Tags like:
+
+```
+**Tags:** app/Models/**/*.php, laravel, php, backend, eloquent, model, database
+```
+
+Use the **first path-like Tag** (e.g. `app/Models/**/*.php`, `database/migrations/**/*.php`, `resources/views/**/*.blade.php`) as the glob. Some skills have multiple paths (e.g. `app/Events/**/*.php`, `app/Listeners/**/*.php`); include all path-like Tags for that skill.
+
+---
+
+## 7. Non-Breaking Refactors Only
+
+- Do not change observable behavior.
+- Do not remove or rename public APIs without explicit approval.
+- Prefer additive fixes (add missing types, FormRequests, transactions) over removals.
+- If a refactor is ambiguous or risky, report it and do not apply it automatically.
+
+---
+
+**Begin by discovering skills, then producing the compliance report, then executing refactors in the specified order.**

scripts/sync-guidelines.php

@@ -29,3 +29,17 @@
 }
 
 echo "Guidelines synced to {$targetDir}/.".PHP_EOL;
+
+// Copy refactor.md to .cursor/commands/ for Cursor slash commands
+$refactorSource = __DIR__.'/../refactor.md';
+$commandsDir = '.cursor/commands';
+$refactorDest = $commandsDir.'/refactor.md';
+
+if (file_exists($refactorSource)) {
+    if (! is_dir($commandsDir)) {
+        mkdir($commandsDir, 0755, true);
+    }
+    if (copy($refactorSource, $refactorDest)) {
+        echo "Refactor command copied to {$refactorDest}.".PHP_EOL;
+    }
+}