clearer prefix instructions

Author: skarim

skills/gh-stack/SKILL.md

@@ -16,9 +16,9 @@ metadata:
 
 ```
 main (trunk)
- └── auth-layer     → PR #1 (base: main)          - bottom (closest to trunk)
-  └── api-endpoints → PR #2 (base: auth-layer)
-   └── frontend     → PR #3 (base: api-endpoints) - top (furthest from trunk)
+ └── feat/auth-layer     → PR #1 (base: main)               - bottom (closest to trunk)
+  └── feat/api-endpoints → PR #2 (base: feat/auth-layer)
+   └── feat/frontend     → PR #3 (base: feat/api-endpoints) - top (furthest from trunk)
 ```
 
 The **bottom** of the stack is the branch closest to the trunk, and the **top** is the branch furthest from the trunk. Each branch inherits from the one below it. Navigation commands (`up`, `down`, `top`, `bottom`) follow this model: `up` moves away from trunk, `down` moves toward it.
@@ -44,13 +44,14 @@ gh extension install github/gh-stack
 ## Agent rules
 
 1. **Always supply branch names as positional arguments** to `init`, `add`, and `checkout`.
-2. **Always use `--auto` when pushing** to skip PR title prompts.
-3. **Always use `--json` when viewing** to get structured output.
-4. **Use `--remote <name>` when multiple remotes are configured**, or set `remote.pushDefault` in git config.
-5. **Avoid branches shared across multiple stacks.** If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
-6. **Plan your stack layers by dependency order before writing code.** Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
-7. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
-8. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
+2. **When a prefix is set, pass only the suffix to `add`.** `gh stack add auth` with prefix `feat` → `feat/auth`. Passing `feat/auth` creates `feat/feat/auth`.
+3. **Always use `--auto` when pushing** to skip PR title prompts.
+4. **Always use `--json` when viewing** to get structured output.
+5. **Use `--remote <name>` when multiple remotes are configured**, or set `remote.pushDefault` in git config.
+6. **Avoid branches shared across multiple stacks.** If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
+7. **Plan your stack layers by dependency order before writing code.** Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
+8. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
+9. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
 
 ## Thinking about stack structure
 
@@ -64,14 +65,18 @@ Stacked branches form a dependency chain: each branch builds on the one below it
 
 ```
 main (trunk)
- └── data-models       ← shared types, database schema
-  └── api-endpoints    ← API routes that use the models
-   └── frontend-ui     ← UI components that call the APIs
-    └── integration    ← tests that exercise the full stack
+ └── feat/data-models    ← shared types, database schema
+  └── feat/api-endpoints ← API routes that use the models
+   └── feat/frontend-ui  ← UI components that call the APIs
+    └── feat/integration ← tests that exercise the full stack
 ```
 
 This is illustrative — choose branch names and layer boundaries that reflect the specific work you're doing. The key principle is: if code in one layer depends on code in another, the dependency must be in the same branch or a lower one.
 
+### Branch naming
+
+Prefer initializing stacks with a prefix (`-p`). Prefixes group branches under a namespace (e.g., `feat/auth`, `feat/api`) and keep branch names clean and consistent. When a prefix is set, pass only the suffix to subsequent `add` calls — the prefix is applied automatically. Without a prefix, you'll need to pass the full branch name each time.
+
 ### Staging changes deliberately
 
 Don't dump all changes into a single commit or branch. Stage changes in batches based on logical grouping:
@@ -111,12 +116,12 @@ Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current
 
 | Task | Command |
 |------|---------|
-| Create a stack | `gh stack init branch-a` |
-| Create a stack with a prefix | `gh stack init -p feat auth` |
+| Create a stack (recommended) | `gh stack init -p feat auth` |
+| Create a stack without prefix | `gh stack init auth` |
 | Adopt existing branches | `gh stack init --adopt branch-a branch-b` |
 | Set custom trunk | `gh stack init --base develop branch-a` |
-| Add a branch to stack | `gh stack add branch-name` |
-| Add branch + stage all + commit (shortcut) | `gh stack add -Am "message" new-branch` |
+| Add a branch to stack (suffix only if prefix set) | `gh stack add api-routes` |
+| Add branch + stage all + commit | `gh stack add -Am "message" api-routes` |
 | Push + create PRs | `gh stack push --auto` |
 | Push as drafts | `gh stack push --auto --draft` |
 | Push without creating PRs | `gh stack push --skip-prs` |
@@ -174,7 +179,7 @@ git commit -m "Add auth middleware tests"
 
 # 4. When you're ready for a new concern, add the next branch
 gh stack add api-routes
-# → creates feat/api-routes (prefixed), checks it out
+# → creates feat/api-routes (prefix applied automatically — just pass the suffix)
 
 # 5. Write code for the API layer
 cat > api.go << 'EOF'
@@ -189,7 +194,7 @@ git commit -m "Add API routes"
 
 # 6. Add a third layer for frontend
 gh stack add frontend
-# → creates feat/frontend, checks it out
+# → creates feat/frontend (just the suffix — prefix is automatic)
 
 cat > frontend.go << 'EOF'
 package frontend
@@ -366,28 +371,33 @@ gh stack init [branches...] [flags]
 ```
 
 ```bash
-# Create a stack with new branches (branched from trunk)
+# Set a branch prefix (recommended — subsequent `add` calls only need the suffix)
+gh stack init -p feat auth
+# → creates feat/auth
+
+# Multi-part prefix (slashes are fine — suffix-only rule still applies)
+gh stack init -p monalisa/billing auth
+# → creates monalisa/billing/auth
+
+# Create a stack with new branches (no prefix — use full branch names)
 gh stack init branch-a branch-b branch-c
 
 # Use a different trunk branch
 gh stack init --base develop branch-a branch-b
 
 # Adopt existing branches into a stack
 gh stack init --adopt branch-a branch-b branch-c
-
-# Set a branch prefix (branch names you provide are automatically prefixed)
-gh stack init -p feat auth
-# → creates feat/auth
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-b, --base <branch>` | Trunk branch (defaults to the repo's default branch) |
 | `-a, --adopt` | Adopt existing branches instead of creating new ones |
-| `-p, --prefix <string>` | Set a branch name prefix for auto-generated names |
+| `-p, --prefix <string>` | Branch name prefix. Subsequent `add` calls only need the suffix (e.g., with `-p feat`, `gh stack add auth` creates `feat/auth`) |
 
 **Behavior:**
 
+- Using `-p` is recommended — it simplifies branch naming for subsequent `add` calls
 - Creates any branches that don't already exist (branching from the trunk branch)
 - In `--adopt` mode: validates all branches exist, rejects if any is already in a stack or has an existing PR
 - Checks out the last branch in the list
@@ -406,7 +416,7 @@ gh stack add [branch] [flags]
 **Recommended workflow — create the branch, then use standard git:**
 
 ```bash
-# Create a new branch and switch to it
+# Create a new branch and switch to it (just the suffix — prefix is applied automatically)
 gh stack add api-routes
 
 # Write code, stage deliberately, and commit
@@ -438,7 +448,7 @@ gh stack add -um "Fix auth bug" auth-fix
 
 - `-A` and `-u` are mutually exclusive.
 - When the current branch has no commits (e.g., right after `init`), `add -Am` commits directly on the current branch instead of creating a new one.
-- If a prefix was set during `init`, the prefix is applied to branch names: `prefix/branch-name`.
+- **Prefix handling:** Only pass the suffix when a prefix is set. `gh stack add api` with prefix `todo` → `todo/api`. Passing `todo/api` creates `todo/todo/api`. Without a prefix, pass the full branch name.
 - If called from a branch that is not the topmost in the stack, exits with code 5: `"can only add branches on top of the stack"`. Use `gh stack top` to switch first.
 - **Uncommitted changes:** When using `gh stack add branch-name` without `-Am`, any uncommitted changes (staged or unstaged) in your working tree carry over to the new branch. This is standard git behavior — the working tree is not touched. Commit or stash changes on the current branch before running `add` if you want a clean starting point on the new branch.