ez-stack: Instructions file for Codex

AGENTS.md

Instructions for AI agents working with ez-stack.

Purpose

ez is a CLI for managing stacked pull requests on GitHub. If a repository has .git/ez/stack.json, branch management and PR operations should go through ez, not raw git checkout -b, git commit, git push, or gh pr create.

Install or update the tool

# First install
pip install ez-stack
ez setup --yes    # configures shell integration (PATH + worktree auto-cd)

# Update to latest (auto-detects install method)
ez update

# Check for updates without installing
ez update --check

Requirements:

• git
• gh, authenticated via gh auth login
• Rust/Cargo available to install ez-stack

Install the skill

Install the ez-workflow skill for the current user so all agents auto-discover it:

ez skill install
# Installs canonical skill to ~/.agents/skills/ez-workflow/SKILL.md
# Symlinks agent-specific skill roots like ~/.claude/skills/ and ~/.codex/skills/
# Works from any directory

This installs the workflow defined in SKILL.md.

Core rule

When .git/ez/stack.json exists, prefer these commands:

• Create branch: ez create <name>
• Commit specific files: ez commit -m "msg" -- path1 path2
• Commit all tracked changes: ez commit -am "msg"
• Commit tracked + untracked changes: ez commit -Am "msg"
• Commit patch-selected hunks: git add -p then ez commit -m "msg"
• Diff vs parent: ez diff --stat or ez diff --name-only
• Get parent branch: ez parent
• Push current branch and create/update PR: ez push
• Push the stack: ez submit
• Sync after trunk changes or merges: ez sync or ez sync --autostash
• Repair a divergent GitHub native stack only when explicitly requested: ez sync --repair-native-stack
• Adopt branches from GitHub PRs: ez adopt or ez adopt --pr 42
• Inspect state programmatically: ez status --json and ez log --json

Avoid these raw commands in an ez-managed repo:

• git checkout -b ... → ez create
• git commit -m ... → ez commit -m
• git push → ez push
• gh pr create → ez push
• git diff main...HEAD → ez diff