Updated refactor.md + adjusted Paths for refactor.md

Author: StanBarrows

README.md

@@ -60,14 +60,23 @@ If your editor supports MCP (Model Context Protocol), configure it to use the Bo
 
 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`
+1. Install or update this package with Composer
+2. The package automatically syncs `refactor.md` to `.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.
 
+If Composer plugins are restricted in your environment, run the fallback command manually:
+
+```bash
+php artisan guidelines:sync-refactor-command
+```
+
+You may need to allow the plugin once in Composer config:
+`composer config allow-plugins.codebar-ag/coding-guidelines true`
+
+If `/refactor` does not appear in Cursor immediately, reload the Cursor window once.
+
 ### 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.
@@ -94,6 +103,8 @@ 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 and copies `refactor.md` to `.cursor/commands/refactor.md` for use with Cursor slash commands.
 
+This sync script is optional and mainly useful when you mirror the full guidelines repo; normal package install/update already auto-syncs `/refactor`.
+
 ---
 
 ## How It Works

composer.json

@@ -1,5 +1,6 @@
 {
     "name": "codebar-ag/coding-guidelines",
+    "type": "composer-plugin",
     "description": "Shared Laravel coding guidelines and skills for codebar-ag projects. Composer package for Laravel Boost.",
     "keywords": [
         "laravel",
@@ -10,6 +11,8 @@
     ],
     "license": "MIT",
     "require": {
+        "composer-plugin-api": "^2.0",
+        "illuminate/console": "^12.0",
         "illuminate/support": "^12.0",
         "php": "^8.4"
     },
@@ -27,6 +30,7 @@
         }
     },
     "extra": {
+        "class": "CodebarAg\\CodingGuidelines\\Composer\\RefactorCommandPlugin",
         "laravel": {
             "providers": [
                 "CodebarAg\\CodingGuidelines\\CodingGuidelinesServiceProvider"
@@ -41,5 +45,8 @@
         "sort-packages": true
     },
     "minimum-stability": "dev",
-    "prefer-stable": true
+    "prefer-stable": true,
+    "require-dev": {
+        "laravel/pint": "^1.27"
+    }
 }

refactor.md

@@ -8,9 +8,12 @@ You are refactoring a Laravel codebase to achieve 100% alignment with **codebar-
 
 Locate skills from one of these paths (check in order; first existing wins):
 
+- `resources/boost/skills/` (when running inside this guidelines package repo)
 - `vendor/codebar-ag/coding-guidelines/resources/boost/skills/`
 - `guidelines/resources/boost/skills/`
 
+If none exist, search the workspace for `**/resources/boost/skills/*/SKILL.md` and use the nearest matching root as the active skill source path.
+
 Project overrides in `.ai/skills/{skill-name}/SKILL.md` take precedence over package defaults.
 
 **Action:** List all `SKILL.md` files. For each skill, extract:
@@ -63,6 +66,15 @@ For each skill in order:
 
 ## 5. Output Format
 
+### Phase 0: Plan and Confirm (mandatory)
+
+Before making any code changes:
+
+- Enter planning mode and produce a concrete implementation plan.
+- Include: applicable skills, target files, prioritized violation groups, and intended edit batches.
+- Present the plan to the user and request explicit approval.
+- Do not edit files, run formatters, or execute write operations until the user confirms the plan.
+
 ### Phase A: Compliance Report (before edits)
 
 Produce a concise report:

scripts/validate-skills.php

@@ -12,30 +12,31 @@
  *
  * Exits with code 1 if any skill is invalid.
  */
-
-$skillsDir = __DIR__ . '/../resources/boost/skills';
-if (!is_dir($skillsDir)) {
+$skillsDir = __DIR__.'/../resources/boost/skills';
+if (! is_dir($skillsDir)) {
     fwrite(STDERR, "Skills directory not found: {$skillsDir}\n");
     exit(1);
 }
 
-$skillDirs = glob($skillsDir . '/*', GLOB_ONLYDIR);
+$skillDirs = glob($skillsDir.'/*', GLOB_ONLYDIR);
 $errors = [];
 $expectedCount = 36;
 
 foreach ($skillDirs as $dir) {
-    $skillFile = $dir . '/SKILL.md';
+    $skillFile = $dir.'/SKILL.md';
     $skillName = basename($dir);
 
-    if (!file_exists($skillFile)) {
+    if (! file_exists($skillFile)) {
         $errors[] = "{$skillName}: Missing SKILL.md";
+
         continue;
     }
 
     $content = file_get_contents($skillFile);
 
-    if (!preg_match('/^---\s*\n(.*?)\n---\s*\n/s', $content, $matches)) {
+    if (! preg_match('/^---\s*\n(.*?)\n---\s*\n/s', $content, $matches)) {
         $errors[] = "{$skillName}: Missing or invalid YAML frontmatter (must start with --- and end with ---)";
+
         continue;
     }
 
@@ -56,7 +57,7 @@
     }
 }
 
-if (!empty($errors)) {
+if (! empty($errors)) {
     foreach ($errors as $err) {
         fwrite(STDERR, "ERROR: {$err}\n");
     }

src/CodingGuidelinesServiceProvider.php

@@ -4,6 +4,7 @@
 
 namespace CodebarAg\CodingGuidelines;
 
+use CodebarAg\CodingGuidelines\Console\SyncRefactorCommand;
 use Illuminate\Support\ServiceProvider;
 
 class CodingGuidelinesServiceProvider extends ServiceProvider
@@ -23,5 +24,10 @@ public function boot(): void
     {
         // Skills are auto-discovered by Laravel Boost from resources/boost/skills/
         // No registration needed — Boost v2.2+ reads vendor/{pkg}/resources/boost/skills/
+        if ($this->app->runningInConsole()) {
+            $this->commands([
+                SyncRefactorCommand::class,
+            ]);
+        }
     }
 }

src/Composer/RefactorCommandPlugin.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodebarAg\CodingGuidelines\Composer;
+
+use CodebarAg\CodingGuidelines\Support\RefactorCommandSynchronizer;
+use Composer\Composer;
+use Composer\EventDispatcher\EventSubscriberInterface;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+use Composer\Script\Event;
+use Composer\Script\ScriptEvents;
+
+final class RefactorCommandPlugin implements EventSubscriberInterface, PluginInterface
+{
+    private ?Composer $composer = null;
+
+    private ?IOInterface $io = null;
+
+    public function activate(Composer $composer, IOInterface $io): void
+    {
+        $this->composer = $composer;
+        $this->io = $io;
+    }
+
+    public function deactivate(Composer $composer, IOInterface $io): void
+    {
+        // Nothing to clean up.
+    }
+
+    public function uninstall(Composer $composer, IOInterface $io): void
+    {
+        // Keep user's .cursor/commands/refactor.md file untouched on uninstall.
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            ScriptEvents::POST_INSTALL_CMD => 'syncRefactorCommand',
+            ScriptEvents::POST_UPDATE_CMD => 'syncRefactorCommand',
+            ScriptEvents::POST_AUTOLOAD_DUMP => 'syncRefactorCommand',
+        ];
+    }
+
+    public function syncRefactorCommand(Event $event): void
+    {
+        $composer = $this->composer ?? $event->getComposer();
+        $io = $this->io ?? $event->getIO();
+
+        $vendorDir = (string) $composer->getConfig()->get('vendor-dir');
+        $projectRoot = dirname($vendorDir);
+        $packageRoot = dirname(__DIR__, 2);
+
+        RefactorCommandSynchronizer::sync($projectRoot, $packageRoot, $io);
+    }
+}

src/Console/SyncRefactorCommand.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodebarAg\CodingGuidelines\Console;
+
+use CodebarAg\CodingGuidelines\Support\RefactorCommandSynchronizer;
+use Illuminate\Console\Command;
+
+final class SyncRefactorCommand extends Command
+{
+    protected $signature = 'guidelines:sync-refactor-command';
+
+    protected $description = 'Sync .cursor/commands/refactor.md from the coding-guidelines package';
+
+    public function handle(): int
+    {
+        $projectRoot = getcwd() ?: '.';
+        $packageRoot = dirname(__DIR__, 2);
+
+        $synced = RefactorCommandSynchronizer::sync($projectRoot, $packageRoot);
+
+        if ($synced) {
+            $this->info('Refactor command is ready at .cursor/commands/refactor.md');
+
+            return 0;
+        }
+
+        $this->warn('Could not sync refactor command.');
+
+        return 1;
+    }
+}

src/Support/RefactorCommandSynchronizer.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodebarAg\CodingGuidelines\Support;
+
+final class RefactorCommandSynchronizer
+{
+    public static function sync(string $projectRoot, string $packageRoot, mixed $io = null): bool
+    {
+        $source = $packageRoot.'/refactor.md';
+        $commandsDir = $projectRoot.'/.cursor/commands';
+        $destination = $commandsDir.'/refactor.md';
+
+        if (! is_file($source)) {
+            self::write($io, '<warning>[coding-guidelines]</warning> refactor.md not found, skipping sync.');
+
+            return false;
+        }
+
+        if (! is_dir($commandsDir) && ! mkdir($commandsDir, 0755, true) && ! is_dir($commandsDir)) {
+            self::write($io, '<warning>[coding-guidelines]</warning> Could not create .cursor/commands directory.');
+
+            return false;
+        }
+
+        $sourceHash = hash_file('sha256', $source);
+        $destinationHash = is_file($destination) ? hash_file('sha256', $destination) : null;
+
+        if ($sourceHash === $destinationHash) {
+            self::write($io, '<info>[coding-guidelines]</info> /refactor command already up to date.');
+
+            return true;
+        }
+
+        if (! copy($source, $destination)) {
+            self::write($io, '<warning>[coding-guidelines]</warning> Failed to copy refactor.md.');
+
+            return false;
+        }
+
+        self::write($io, '<info>[coding-guidelines]</info> Synced /refactor command to .cursor/commands/refactor.md');
+
+        return true;
+    }
+
+    private static function write(mixed $io, string $message): void
+    {
+        if (is_object($io) && method_exists($io, 'write')) {
+            $io->write($message);
+        }
+    }
+}