ci: auto-resolve skills/ conflicts in backport to stable (#1798)

* ci: auto-resolve skills/ conflicts in backport to stable

The skills/ directory is not maintained on the stable branch (skill
files are unrelated to npm packaging). Extend the backport workflow's
auto-resolution — and the AI-assisted fallback prompt — to treat
skills/ conflicts the same way docs app conflicts are handled: keep
the stable side and drop the incoming change from main.

Also updates AGENTS.md to document which directories are stable-only
placeholders and how the backport action handles them.

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Nathan Rajlich <n@n8.io>

---------

Signed-off-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: TooTallNate

.github/workflows/backport.yml

@@ -47,23 +47,30 @@ jobs:
             echo "status=clean" >> "$GITHUB_OUTPUT"
             echo "cherry_pick_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           else
-            # The docs app on the stable branch is a minimal placeholder —
-            # only docs/content/ is actively maintained (markdown files
-            # bundled into npm packages via prepack scripts). Auto-resolve
-            # any non-content docs/ conflicts by keeping the stable branch
-            # version (discarding the incoming change from main).
-            git diff --name-only --diff-filter=U | grep '^docs/' | grep -v '^docs/content/' | while IFS= read -r file; do
-              echo "Auto-resolving docs conflict (keeping stable version): $file"
-              # Check for a stage-2 ("ours") entry in the index, which means
-              # the file exists on the stable side of the conflict. Otherwise
-              # the file was newly added on main and we drop it.
-              if git show ":2:$file" >/dev/null 2>&1; then
-                git checkout --ours -- "$file"
-                git add -- "$file"
-              else
-                git rm -f -- "$file"
-              fi
-            done || true
+            # Auto-resolve conflicts in directories that are not maintained
+            # on the stable branch by keeping the stable side (discarding the
+            # incoming change from main):
+            #   - docs/ (except docs/content/): the docs app is a minimal
+            #     placeholder on stable; only docs/content/ is actively
+            #     maintained (markdown files bundled into npm packages via
+            #     prepack scripts).
+            #   - skills/: skill files are unrelated to npm packaging and
+            #     are not maintained on stable.
+            git diff --name-only --diff-filter=U \
+              | { grep -E '^(docs/|skills/)' || true; } \
+              | { grep -v '^docs/content/' || true; } \
+              | while IFS= read -r file; do
+                  echo "Auto-resolving conflict (keeping stable version): $file"
+                  # Check for a stage-2 ("ours") entry in the index, which means
+                  # the file exists on the stable side of the conflict. Otherwise
+                  # the file was newly added on main and we drop it.
+                  if git show ":2:$file" >/dev/null 2>&1; then
+                    git checkout --ours -- "$file"
+                    git add -- "$file"
+                  else
+                    git rm -f -- "$file"
+                  fi
+                done
 
             # Lockfile conflicts can be resolved by re-running pnpm install,
             # but only when no other conflicts remain (to avoid pnpm choking
@@ -120,12 +127,19 @@ jobs:
           PR title: $PR_TITLE
           Commit message: $COMMIT_MSG
 
-          IMPORTANT: On the stable branch, only docs/content/ is actively
-          maintained (markdown files bundled into npm packages). The rest of
-          the docs app is a minimal placeholder. If any remaining conflicts
-          involve files under docs/ that are NOT in docs/content/, resolve
-          them by keeping the stable branch version (the <<<<<<< HEAD side)
-          and discarding the incoming change from main. If the file does not
+          IMPORTANT: Some directories are not fully maintained on the stable
+          branch and should be auto-resolved by keeping the stable side:
+
+          - docs/ (except docs/content/): the docs app is a minimal
+            placeholder on stable; only docs/content/ is actively maintained
+            (markdown files bundled into npm packages).
+          - skills/: skill files are unrelated to npm packaging and are not
+            maintained on stable.
+
+          If any remaining conflicts involve files under docs/ that are NOT
+          in docs/content/, or any files under skills/, resolve them by
+          keeping the stable branch version (the <<<<<<< HEAD side) and
+          discarding the incoming change from main. If the file does not
           exist on the stable side (HEAD side is empty), remove it with
           "git rm". Conflicts in docs/content/ should be resolved normally.
 

AGENTS.md

@@ -173,7 +173,12 @@ This repository uses a dual-branch release model with [changesets](https://githu
 
 Both branches trigger the release workflow (`.github/workflows/release.yml`) on push. The changesets action creates a "Version Packages" PR on each branch when there are pending changesets.
 
-**Important:** On the `stable` branch, only `docs/content/` is actively maintained — the rest of the docs app is a minimal placeholder. Documentation is deployed only from `main`. The `docs/content/` directory is kept on `stable` because the markdown files are bundled into npm packages via `prepack` scripts. When backporting changes to `stable`, any conflicts involving docs app files (outside of `docs/content/`) should be resolved by keeping the `stable` branch version (discarding the incoming change from `main`). Conflicts in `docs/content/` should be resolved normally. The backport GitHub Action handles this automatically.
+**Important:** Some directories are not fully maintained on the `stable` branch:
+
+- **`docs/`**: Only `docs/content/` is actively maintained on `stable` — the rest of the docs app is a minimal placeholder (documentation is deployed only from `main`). `docs/content/` is kept on `stable` because the markdown files are bundled into npm packages via `prepack` scripts.
+- **`skills/`**: Not maintained on `stable` at all. Skill files are unrelated to npm packaging, so there is no reason to keep them in sync on the release branch.
+
+When backporting changes to `stable`, any conflicts involving docs app files (outside of `docs/content/`) or `skills/` files should be resolved by keeping the `stable` branch version (discarding the incoming change from `main`). Conflicts in `docs/content/` should be resolved normally. The backport GitHub Action handles this automatically.
 
 ### Changesets
 
@@ -192,7 +197,7 @@ Both branches trigger the release workflow (`.github/workflows/release.yml`) on
 
 To backport a change from `main` to `stable`, add the `backport-stable` label to the PR on `main`. A GitHub Action (`.github/workflows/backport.yml`) will automatically cherry-pick the squashed commit to `stable`. The label can be added before or after merging — the action triggers on both merge and label events. The changeset file is included in the cherry-pick, so the correct semver bump type is preserved on `stable`.
 
-If the cherry-pick fails due to conflicts, the action first auto-resolves any docs app conflicts (files under `docs/` except `docs/content/`) by keeping the `stable` branch version, since the docs app is a minimal placeholder on `stable` and not actively maintained there. It also auto-resolves `pnpm-lock.yaml` conflicts by re-running `pnpm install`. If those resolve everything, the cherry-pick is pushed directly to `stable`. Otherwise, it attempts to resolve remaining conflicts using [opencode](https://opencode.ai) (AI-powered conflict resolution). If successful, it creates a PR targeting `stable` for human review instead of pushing directly. If the AI cannot resolve the conflicts, the action will comment on the original PR with instructions for manual resolution.
+If the cherry-pick fails due to conflicts, the action first auto-resolves conflicts in directories that are not maintained on `stable` (docs app files under `docs/` except `docs/content/`, and any files under `skills/`) by keeping the `stable` branch version. It also auto-resolves `pnpm-lock.yaml` conflicts by re-running `pnpm install`. If those resolve everything, the cherry-pick is pushed directly to `stable`. Otherwise, it attempts to resolve remaining conflicts using [opencode](https://opencode.ai) (AI-powered conflict resolution). If successful, it creates a PR targeting `stable` for human review instead of pushing directly. If the AI cannot resolve the conflicts, the action will comment on the original PR with instructions for manual resolution.
 
 ### Pre-release Lifecycle