chore(CMP-62): add gh-stack workflow skill

[github-actions]

Opened automatically when rg/cmp-62-gh-stack-skill was pushed.

The title is written from the diff and rewritten as you push, because this is squashed onto main and the title becomes the commit subject and the changelog line. Retitle it yourself and it is yours — the automation stops touching it.

---

Summary by cubic

Adds the gh-stack skill to guide non-interactive, safe use of gh stack for managing stacked PRs. Addresses Linear CMP-62 by standardizing stack creation, sync, and merge workflows and providing clear recovery paths.

• New Features

  • Adds .agents/skills/gh-stack/SKILL.md with setup, non-interactive rules, core loop, sync/merge guidance, JSON schema for view --json, exit codes, and constraints.
  • Adds references:
    • references/commands.md — preconditions, side effects, atomicity, and failure modes per command.
    • references/stack-design.md — planning layers, naming, staging, and when to add a layer.
    • references/troubleshooting.md — rebase conflicts, squash-merge handling, divergence, restructuring, multi-worktree usage, and lock/recovery cases.

• Migration

  • Install the extension: gh extension install github/gh-stack.
  • Configure Git: git config rerere.enabled true and git config remote.pushDefault origin (when multiple remotes).

^{Written for commit 9a9a1de. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
crm-agent	Ready	Preview	Aug 7, 2026 7:36pm
crm-api	Ready	Preview	Aug 7, 2026 7:36pm
crm-app	Ready	Preview	Aug 7, 2026 7:36pm

[cubic-dev-ai]

2 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".agents/skills/gh-stack/references/commands.md">

<violation number="1" location=".agents/skills/gh-stack/references/commands.md:101">
P3: The atomicity claims conflict across commands: `push` says its multi-ref push of all active branches is "Not atomic", while `sync` step 5 describes the same all-branches push as "atomically" and `link` calls its push "atomic". A reader cannot tell whether this is an accurate behavioral difference or an error; reconcile the wording or explain why sync/link pushes are atomic when `push` is not.</violation>
</file>

<file name=".agents/skills/gh-stack/references/troubleshooting.md">

<violation number="1" location=".agents/skills/gh-stack/references/troubleshooting.md:43">
P3: The `view --json` comment in the squash-merge section implies `state` is a branch-level field, but per SKILL.md's schema it is `branches[].pr.state` (an `"OPEN"|"MERGED"|"QUEUED"` enum), while `isMerged` is the branch-level boolean. Clarify so an agent parsing the JSON looks in the right namespace.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The atomicity claims conflict across commands: push says its multi-ref push of all active branches is "Not atomic", while sync step 5 describes the same all-branches push as "atomically" and link calls its push "atomic". A reader cannot tell whether this is an accurate behavioral difference or an error; reconcile the wording or explain why sync/link pushes are atomic when push is not.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .agents/skills/gh-stack/references/commands.md, line 101:

<comment>The atomicity claims conflict across commands: `push` says its multi-ref push of all active branches is "Not atomic", while `sync` step 5 describes the same all-branches push as "atomically" and `link` calls its push "atomic". A reader cannot tell whether this is an accurate behavioral difference or an error; reconcile the wording or explain why sync/link pushes are atomic when `push` is not.</comment>

<file context>
@@ -0,0 +1,179 @@
+   from its remote, or a branch no longer contains its expected parent. Merged PRs are handled
+   automatically. On conflict, **all branches are restored** to their pre-rebase state and the
+   command exits **3**.
+5. **Push** all active branches, atomically.
+6. **Refresh PR state** from GitHub.
+7. **Sync the stack object** — link open PRs into a stack, additively. Only when two or more PRs
</file context>

[cubic-dev-ai]

P3: The view --json comment in the squash-merge section implies state is a branch-level field, but per SKILL.md's schema it is branches[].pr.state (an "OPEN"|"MERGED"|"QUEUED" enum), while isMerged is the branch-level boolean. Clarify so an agent parsing the JSON looks in the right namespace.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .agents/skills/gh-stack/references/troubleshooting.md, line 43:

<comment>The `view --json` comment in the squash-merge section implies `state` is a branch-level field, but per SKILL.md's schema it is `branches[].pr.state` (an `"OPEN"|"MERGED"|"QUEUED"` enum), while `isMerged` is the branch-level boolean. Clarify so an agent parsing the JSON looks in the right namespace.</comment>

<file context>
@@ -0,0 +1,159 @@
+
+```bash
+gh stack sync
+gh stack view --json    # merged branch reports "isMerged": true, "state": "MERGED"
+```
+
</file context>