From f51409f91eb513899ad111a4c7b3451f48404f21 Mon Sep 17 00:00:00 2001
From: Aaron Powell <me@aaron-powell.com>
Date: Wed, 18 Feb 2026 16:52:40 +1100
Subject: [PATCH] ci: add resolution guidance to plugin structure check

Provides two options: rebase onto staged (with exact commands using
the contributor's branch name) or manually remove the files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/check-plugin-structure.yml | 29 +++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/check-plugin-structure.yml b/.github/workflows/check-plugin-structure.yml
index 97780e63..e71b3503 100644
--- a/.github/workflows/check-plugin-structure.yml
+++ b/.github/workflows/check-plugin-structure.yml
@@ -75,6 +75,10 @@ jobs:
             }
 
             if (errors.length > 0) {
+              const prBranch = context.payload.pull_request.head.ref;
+              const prRepo = context.payload.pull_request.head.repo.full_name;
+              const isFork = context.payload.pull_request.head.repo.fork;
+
               const body = [
                 '⚠️ **Materialized files or symlinks detected in plugin directories**',
                 '',
@@ -83,9 +87,32 @@ jobs:
                 '- `README.md`',
                 '',
                 'Agent, command, and skill files are copied in automatically when publishing to `main`.',
-                'Please remove the following:',
                 '',
+                '**Issues found:**',
                 ...errors.map(e => `- ${e}`),
+                '',
+                '---',
+                '',
+                '### How to fix',
+                '',
+                'It looks like your branch may be based on `main` (which contains materialized files). Here are two options:',
+                '',
+                '**Option 1: Rebase onto `staged`** (recommended if you have few commits)',
+                '```bash',
+                `git fetch origin staged`,
+                `git rebase --onto origin/staged origin/main ${prBranch}`,
+                `git push --force-with-lease`,
+                '```',
+                '',
+                '**Option 2: Remove the extra files manually**',
+                '```bash',
+                '# Remove materialized files from plugin directories',
+                'find plugins/ -mindepth 2 -maxdepth 2 -type d \\( -name agents -o -name commands -o -name skills \\) -exec rm -rf {} +',
+                '# Remove any symlinks',
+                'find plugins/ -type l -delete',
+                'git add -A && git commit -m "fix: remove materialized plugin files"',
+                'git push',
+                '```',
               ].join('\n');
 
               await github.rest.pulls.createReview({