Menu
Branch stacking and PR management with git-spice for the agentd project. Use when creating stacked branches, submitting PRs, syncing with upstream, resolving rebase conflicts, or navigating a branch stack.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Store, search, and manage shared knowledge through the memory service. Use for persisting information across agent sessions, semantic search over stored knowledge, and inter-agent knowledge sharing.
Browse, read, and author per-project knowledgebase documents through the knowledge service CLI. Use for creating, updating, listing, and reading markdown documents stored against a project, and reconciling DB rows against disk.
Cut a new agentd release. Suggests the next semver version from conventional commits (or accepts an explicit `x.y.z`), bumps the workspace version, regenerates the changelog with git-cliff, then commits, tags, and pushes the `v*` tag that triggers the Release workflow. Use when the user runs /release or asks to publish/cut/tag a new version.
Create a new GitHub plan issue with the "Plan: <title>" format, appropriate labels, and structured body. Use when the user wants to capture a high-level plan for future work.
Ask the human user a question during workflow execution and check for answers. Use for agent-to-human Q&A, collecting decisions, and reacting to human responses via ask_response workflow triggers.
Create, list, and manage conversation rooms, participants, and messages through the communicate service. Use for inter-agent messaging, room management, real-time message watching, and participant coordination.
| name | git-spice |
| description | Branch stacking and PR management with git-spice for the agentd project. Use when creating stacked branches, submitting PRs, syncing with upstream, resolving rebase conflicts, or navigating a branch stack. |
Reference skill for using git-spice (git-spice) in the agentd project. git-spice manages stacked branches and coordinated pull requests.
[!IMPORTANT] All agent usage MUST include
--no-promptto prevent blocking on interactive input.
which git-spice # should return a path (e.g. /opt/homebrew/bin/git-spice)
git-spice --version # expect 0.24.x or later
# Initialize git-spice with trunk = main
git-spice repo init --trunk main
# Authenticate with GitHub — must be run by a human, cannot be automated
git-spice auth login
[!NOTE]
git-spice auth loginis an interactive OAuth flow. Agents cannot perform this step. A human must run it once per environment before anygit-spice branch submitoperations.
These are set in .git/config by the initialization process. If missing in a fresh clone:
git config spice.submit.navigationComment true
git config spice.submit.navigationComment.downstack true
git config spice.log.all true
git config spice.log.crStatus true
[!NOTE]
spice.submit.labelis not set as a project default. Pass--label review-agentexplicitly when a PR is ready for review — not for draft PRs.
| Purpose | Branch name pattern |
|---|---|
| Feature / implementation | issue-NNN |
| Documentation | docs/issue-NNN |
| Refactoring | refactor/issue-NNN |
| Hotfix | fix/issue-NNN |
Before creating a branch, determine where to stack it:
If the issue has 'blocked-by' relationships pointing to another open issue:
→ Check out that blocking issue's branch
→ git-spice branch create issue-NNN
Otherwise (no blocking dependencies):
→ git-spice trunk # go to main/trunk
→ git-spice branch create issue-NNN
For the current milestone, non-trunk base is feature/autonomous-pipeline:
git checkout feature/autonomous-pipeline
git-spice branch create issue-NNN
# Pull latest, clean merged branches, rebase stack — run at the start of every session
git-spice repo sync
# Create a stacked branch (positioned on top of current branch)
git-spice branch create issue-NNN
# Create with a descriptive message (used in PR title)
git-spice branch create issue-NNN -m "feat: add authentication middleware"
# Navigate the stack
git-spice up # move to the branch stacked on top of current
git-spice down # move to the branch below current
git-spice trunk # jump to trunk (main)
# Check stack state
git-spice log short # concise stack view
git-spice log long --json # machine-readable full stack state
# Commit and automatically restack upstack dependents
git-spice commit create -m "feat: implement thing"
# Amend the last commit and restack
git-spice commit amend -m "feat: implement thing (revised)"
# Submit current branch as PR — idempotent (creates or updates)
git-spice branch submit --fill --no-prompt
# Submit with the review-agent label (use when PR is ready for automated review)
git-spice branch submit --fill --no-prompt --label review-agent
# Submit entire stack as coordinated PRs
git-spice stack submit --fill --no-prompt
# Submit with explicit title and body (bypasses --fill inference)
git-spice branch submit --no-prompt \
--title "feat(auth): add token refresh logic" \
--body "Implements automatic token refresh on 401 responses."
# After upstream merges: sync + rebase everything
git-spice repo sync --restack --no-prompt
# Rebase branches stacked above current branch
git-spice upstack restack
# Rebase only the current branch onto its parent
git-spice branch restack
If a restack hits a merge conflict:
# 1. Identify the conflicting files
git status
# 2. Resolve conflicts manually in each file
# 3. Stage resolved files
git add <resolved-file>
# 4. Continue the rebase
git-spice rebase continue
If the conflict is unresolvable:
# Abort and restore previous state
git-spice rebase abort
# Then: post to the engineering notification channel describing:
# - Which branches conflict
# - What the conflicting changes are
# - What was attempted
# Wait for human guidance before retrying.
agent notify create \
--title "Rebase conflict: needs human review" \
--body "Conflict between <branch-A> and <branch-B>: <description>" \
--channel engineering
Labels used in the autonomous pipeline workflow:
| Label | Applied by | Meaning |
|---|---|---|
review-agent | Worker agent | PR is ready for automated review; triggers reviewer workflow |
merge-queue | Reviewer agent | PR is approved; triggers conductor to merge |
needs-restack | Reviewer agent | Branch is behind its parent; worker must restack before merge |
conductor-sync | Any agent | Triggers an immediate conductor run for the associated issue |
git-spice branch submit --fill --no-prompt --label review-agent
git-spice stack submit --fill --no-prompt
git-spice repo sync --restack --no-prompt
# Verify stack looks correct
git-spice log short
git-spice log long --json | jq '.[] | {branch: .branch, pr: .pr}'
not allowed to prompt for inputAdd --no-prompt to your command. All agent invocations must be non-interactive.
refs/spice/data missing after fresh clonegit-spice state is stored in a git ref, not tracked files. Re-initialize:
git-spice repo init --trunk main
If you created a branch with git checkout -b instead of git-spice branch create, track it:
git-spice branch track --base <parent-branch>
gs alias deprecation warningThe gs alias for git-spice is deprecated. Use git-spice directly, or set:
export GIT_SPICE_NO_GS_WARNING=1