Refresh stack workflow

AGENTS.md

@@ -17,6 +17,7 @@ This repository contains reusable AI coding workflows that can be installed glob
 - **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond)
 - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff)
 - **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond)
+- **rebase-stack** — Rebase a stacked-branch chain with conflict guidance, per-branch validation, and push (start, continue, validate, push)
 - **sizing** — Pre-cycle Feature sizing with T-shirt sizes and team effort breakdowns (ingest, assess, apply)
 - **skill-reviewer** — Meta-workflow that audits AI skill directories
 - **triage** — Bulk Jira bug triage with AI-driven categorization and HTML reports
@@ -146,6 +147,7 @@ ai-workflows/
 ├── implement/
 ├── kcs/
 ├── prd/
+├── rebase-stack/
 ├── sizing/
 ├── skill-reviewer/
 │   ├── prompts/

README.md

@@ -39,6 +39,9 @@ Reusable AI coding workflows a team member can install globally or per-project,
 - **KCS** -- KCS Solution article workflow: gather bug context from Jira, draft a KCS article in markdown, validate against the KCS Content Standard, and produce a handoff message for the support engineer.
   See [kcs/README.md](kcs/README.md).
 
+- **Rebase Stack** -- Rebase a stacked-branch chain onto an updated base using `gh stack`, guide through conflict resolution, validate each branch, and push all updated branches.
+  See [rebase-stack/README.md](rebase-stack/README.md).
+
 - **Sizing** -- Pre-cycle Feature sizing: ingest Features from Jira (single or batch by Fix Version), assess against a T-shirt size rubric (XS–XXL) with per-team effort breakdowns (DEV, QE, UX, UI, DOCS), and write results back to Jira.
   See [sizing/README.md](sizing/README.md).
 

rebase-stack/README.md

@@ -0,0 +1,121 @@
+# Rebase Stack Workflow
+
+Rebases a stacked-branch chain onto an updated base branch using `gh stack`,
+guides you through conflict resolution if needed, validates each branch, and
+pushes all updated branches. Creates any missing PRs afterwards, with
+fork-aware targeting.
+
+## Phase Flow
+
+```
+/start ──── success ──────────────────────── /validate ──── /push ──── done
+       └─── conflict ──── (resolve) ──── /continue ──┐
+                                                      │
+                          conflict ──── (resolve) ────┘
+                          success ──────────────── /validate ──── /push ──── done
+```
+
+## Prerequisites
+
+| Tool | Purpose |
+|------|---------|
+| `git` | Rebase and push operations |
+| `gh` (GitHub CLI) | Stack management, PR creation |
+| `gh-stack` extension | `gh extension install github/gh-stack` |
+| Remote access (`origin`) | Fetch and push |
+
+`/start` installs the extension automatically if it is not found.
+
+> **Note:** `gh-stack` is in private preview. The CLI extension installs for
+> anyone, but the Stacked PRs feature (used by `gh stack submit`) requires
+> enablement on the upstream repository. If `gh stack submit` exits with
+> code 9, the repo does not have it enabled — the skill falls back to
+> `gh pr create` automatically.
+
+## Stack Initialization
+
+`/start` detects whether your branches are already tracked by `gh stack`:
+
+- **Already tracked** (`gh stack view --json` exits 0): proceeds directly to
+  the rebase.
+- **Not yet tracked** (exit code 2): discovers branches from the commit graph
+  (`git log --reverse --decorate origin/{base}..HEAD`), presents the
+  bottom-to-top list for your confirmation, then runs:
+  ```bash
+  gh stack init --base {base} branch-1 branch-2 branch-3 ...
+  ```
+  `gh stack` adopts the existing branches and detects any open PRs automatically.
+
+You only need to initialize once per stack. Subsequent `/start` runs skip
+this step.
+
+## Commands
+
+| Command | When to use |
+|---------|-------------|
+| `/start` | Begin the rebase. Takes an optional base branch (default: `main`). Installs `gh-stack` if needed, initializes the stack if not yet tracked, then rebases. Local only — does not push. |
+| `/continue` | Resume after resolving a conflict mid-rebase. Repeat as needed. Local only — does not push. |
+| `/validate` | After rebase completes: re-fetches to check remote currency, runs lint and unit tests on each branch independently, and shows a branch overview table. Does not push. |
+| `/push` | After validation: asks for confirmation, pushes all branches atomically with `gh stack push`, then creates any missing PRs with fork-aware targeting. |
+
+## Usage Examples
+
+### Typical: rebase a stack onto updated main
+
+You have three branches stacked: `main → story-1 → story-2 → story-3 (HEAD)`.
+Main has moved forward. Run:
+
+```
+/start
+```
+
+The agent checks for `gh-stack`, detects the stack (or initializes it),
+then runs `gh stack rebase --remote origin`. On success it prompts you to
+run `/validate`, which checks each branch and shows an overview table. Then
+run `/push` to push all branches atomically with `gh stack push` after
+confirmation.
+
+### With conflicts
+
+Same scenario, but `story-2` conflicts with a change on main:
+
+1. `/start` — rebase stops at `story-2`, shows the conflicting files
+2. Resolve conflicts. For "old version vs evolved version" conflicts (the lower
+   branch was rebased and this branch has older copies): `git checkout --ours <file> && git add <file>`.
+   For genuine new-code conflicts: merge manually, then `git add <file>`. Do not `git commit`.
+3. `/continue` — rebase resumes; if clean, prompts you to run `/validate`
+4. If another conflict appears, repeat steps 2–3
+5. `/validate` — shows branch overview table after per-branch lint/test
+6. `/push` — pushes after confirmation, creates any missing PRs
+
+### Rebasing onto a branch other than main
+
+```
+/start feature/platform-upgrade
+```
+
+The agent fetches `origin/feature/platform-upgrade` and rebases onto it.
+
+### Fork-based workflow (no Stacked PRs)
+
+After `/push` completes the push, it tries `gh stack submit --auto`. If the
+upstream repo does not have Stacked PRs enabled (exit code 9), it falls back
+to `gh pr create` with `--head fork-owner:branch --repo upstream/repo`, setting
+`Depends on: #N` in each PR body. All PRs target the upstream default branch.
+
+## Artifacts
+
+Local state written to `.artifacts/rebase-stack/` during the workflow (gitignored):
+
+| File | Written by | Purpose | How to clear |
+|------|-----------|---------|--------------|
+| `validation-cache` | `/validate` | `branch:sha` pairs for each branch that has passed validation. Persists across runs; stale entries are ignored automatically when SHAs change after a rebase. | `rm .artifacts/rebase-stack/validation-cache` to force full re-validation on the next `/validate` run. |
+| `logs/{branch}.log` | `/validate` | Full lint and test output per branch. Kept on failure for inspection; deleted on success. | Inspect directly; deleted automatically on the next successful `/validate` run. |
+
+## Push Safety
+
+- Branches are pushed **atomically**: `gh stack push` uses `--force-with-lease
+  --atomic`, so if any remote branch was updated since the last fetch, the
+  entire push is rejected rather than partially applied.
+- Protected branches (`main`, `master`, `develop`, PR targets) are never
+  pushed — only the stack branches above them.

rebase-stack/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: rebase-stack
+version: 0.1.0
+description: >-
+  Rebases a stacked-branch chain onto an updated base branch using gh-stack,
+  guides through conflict resolution if needed, validates each branch, and
+  pushes all updated branches. Creates PRs for any branch that lacks one,
+  with fork-aware targeting. Works on repos with or without Stacked PRs enabled.
+  Use when rebasing stacked stories or PRs onto main or another updated branch.
+  Activated by commands: /start, /continue, /validate, /push.
+---
+# Rebase Stack Workflow
+
+## Quick Start
+
+1. If the user invoked `/start`, read `commands/start.md` and follow it.
+2. If the user invoked `/continue`, read `commands/continue.md` and follow it.
+3. If the user invoked `/validate`, read `commands/validate.md` and follow it.
+4. If the user invoked `/push`, read `commands/push.md` and follow it.
+5. Otherwise, read `skills/controller.md` and present the available phases to the user.
+
+If a step fails or produces unexpected output, stop and report to the user.
+Always wait for the user before advancing to the next phase.
+
+For safety rules, see `guidelines.md`.

rebase-stack/commands/continue.md

@@ -0,0 +1,11 @@
+---
+name: rebase-stack:continue
+description: Resume a rebase after conflict resolution, then force-push updated branches.
+---
+# /continue
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **continue** phase. Context:
+
+$ARGUMENTS

rebase-stack/commands/push.md

@@ -0,0 +1,11 @@
+---
+name: rebase-stack:push
+description: Push all stack branches atomically to origin and create any missing PRs.
+---
+# /push
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **push** phase. Context:
+
+$ARGUMENTS

rebase-stack/commands/start.md

@@ -0,0 +1,11 @@
+---
+name: rebase-stack:start
+description: Verify gh-stack, detect or initialize the stack, then rebase it onto the updated base.
+---
+# /start
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **start** phase. Context:
+
+$ARGUMENTS

rebase-stack/commands/validate.md

@@ -0,0 +1,11 @@
+---
+name: rebase-stack:validate
+description: Check remote currency, validate each branch, and show a push overview.
+---
+# /validate
+
+Read `../skills/controller.md` and follow it.
+
+Dispatch the **validate** phase. Context:
+
+$ARGUMENTS

rebase-stack/guidelines.md

@@ -0,0 +1,41 @@
+# Rebase Stack Guidelines
+
+## Safety Rules
+
+- **Push with `gh stack push --remote origin`.** It uses `--force-with-lease --atomic`
+  internally, so if the remote was updated since your last fetch the entire push is
+  rejected rather than partially applied.
+- **Never push protected branches.** Do not push to `main`, `master`, `develop`, or any
+  branch that is the PR target — only push the stack branches above it.
+- **Confirm before pushing.** Always present the full list of branches to be pushed and
+  wait for explicit user confirmation.
+- **Stop on unexpected state.** If git or `gh stack` output is ambiguous or unexpected,
+  stop and report rather than guess.
+
+## Conflict Handling
+
+- When a conflict occurs, show the user the commit that caused it and the conflicting files,
+  then ask whether they want the agent to fix it or prefer to fix it themselves. Do not
+  attempt resolution before the user answers.
+- **Conflict strategy:** When the conflict is "old version vs evolved version" (a lower
+  branch was rebased and this branch carries older copies of the same commits), take
+  `--ours`. In a rebase, `--ours` is the onto-branch (the lower branch's updated tip),
+  so it keeps the evolved version and discards the stale copy:
+  ```bash
+  git checkout --ours <file>
+  git add <file>
+  ```
+  For conflicts involving genuinely new code unique to this branch, manually merge both sides.
+- Instruct the user to resolve, `git add` the resolved files (do NOT `git commit`),
+  then run `/continue`.
+- `gh stack rebase --continue` resumes from where the rebase paused — do not restart
+  from scratch.
+
+## PR Creation
+
+- After pushing, check which branches lack an open PR (use `gh stack view --json`).
+- For repos with Stacked PRs enabled: try `gh stack submit --auto`. If it succeeds, done.
+- For forks or repos where Stacked PRs are not enabled (exit code 9): create PRs manually
+  with `gh pr create`, setting `--head owner:branch` and `--repo upstream` for forks.
+- All PRs in a fork-based workflow target the upstream default branch (PR Target), not
+  each other's branches. Use `Depends on: #N` in the PR body to express ordering.

rebase-stack/skills/continue.md

@@ -0,0 +1,76 @@
+---
+name: continue
+description: Resume a gh stack rebase after conflict resolution.
+---
+
+# Continue Rebase Stack
+
+## Process
+
+### Step 1: Verify Conflicts Are Resolved
+
+```bash
+git diff --name-only --diff-filter=U
+```
+
+If any files are listed, conflicts are still unresolved. Tell the user to
+resolve them and `git add` each file before running `/continue` again.
+
+### Step 2: Continue the Rebase
+
+```bash
+gh stack rebase --continue --remote origin
+```
+
+Capture the full output. Two outcomes:
+
+---
+
+**On conflict** — another commit in the stack conflicted. Show the user:
+
+1. The commit that caused the conflict:
+   ```bash
+   git rebase --show-current-patch 2>/dev/null | head -10
+   ```
+2. The conflicting files:
+   ```bash
+   git diff --name-only --diff-filter=U
+   ```
+
+Then ask:
+
+> A conflict was detected. How would you like to proceed?
+> - **Fix it for me** — I'll attempt to resolve the conflicts and continue.
+> - **I'll fix it** — Pause here; I'll resolve the conflicts manually and run `/continue` when ready.
+
+**Stop here.** Wait for the user's choice before doing anything.
+
+If the user asks you to fix it: examine each conflicting file. For files where
+the conflict is "old version vs evolved version" (this branch carries a stale
+copy of a commit that the lower branch already updated), apply `--ours` — in a
+rebase, `--ours` is the onto-branch (the lower branch's updated tip):
+
+```bash
+git checkout --ours <file>
+git add <file>
+```
+
+For files with genuinely new code on both sides, show the conflict markers and
+ask the user which version to keep before proceeding.
+
+Once all files are resolved and staged, run `gh stack rebase --continue --remote origin` automatically.
+
+If the user wants to fix it themselves: instruct them to resolve the conflicts,
+then `git add <resolved files>` (do **not** `git commit`), then run `/continue` again.
+
+---
+
+**On success** — proceed to Step 3.
+
+---
+
+### Step 3: Report and Hand Off
+
+Tell the user:
+
+> Rebase complete. Run `/validate` to validate each branch before pushing.

rebase-stack/skills/controller.md

@@ -0,0 +1,46 @@
+---
+name: controller
+description: Phase dispatcher for the rebase-stack workflow.
+---
+
+# Rebase Stack Controller
+
+## Phases
+
+1. **Start** (`/start`) — `start.md`
+   Verify the `gh-stack` extension, detect or initialize the stack, then rebase
+   it onto the updated base with `gh stack rebase`. Local-only — does not push.
+   On success, hands off to `/validate`.
+
+2. **Continue** (`/continue`) — `continue.md`. Repeatable.
+   Only needed when `/start` (or a previous `/continue`) stopped due to a
+   merge conflict. Resumes the rebase after the user resolves conflicts.
+   Local-only — does not push. On success, hands off to `/validate`.
+
+3. **Validate** (`/validate`) — `validate.md`
+   Re-fetches to check remote currency, validates lint and unit tests on each
+   branch independently, and shows a branch overview table. Does not push.
+   On success, hands off to `/push`.
+
+4. **Push** (`/push`) — `push.md`
+   Pushes all branches atomically with `gh stack push`, then creates any
+   missing PRs with fork-aware targeting.
+
+### Typical Flow
+
+```text
+start → (success) → validate → push → done
+start → (conflict) → [continue loop] → (success) → validate → push → done
+```
+
+## How to Execute a Phase
+
+1. Read `../guidelines.md` for safety rules before executing any phase.
+2. Announce the phase to the user.
+3. Read and follow the corresponding skill file.
+4. Stop and wait for the user between phases — do not auto-advance.
+
+## Rules
+
+- **Never auto-advance.** Always wait for the user between phases.
+- Stop and report on any unexpected git or `gh stack` state. Do not guess or continue past errors.