ez-workflow

name	ez-workflow
description	Use when about to run git branching, commit, push, or PR operations in a repo managed by ez-stack. Provides the complete command reference and agent-specific usage patterns.

ez-stack

ez-stack makes version control invisible for AI coding agents. Four commands cover the full development lifecycle. Stacked PRs, worktree isolation, and auto-restacking happen automatically.

When to use ez: If .git/ez/stack.json exists, ALL git operations go through ez.

The 4 Commands

ez create feat/auth              # 1. Start: worktree + branch + cd
# ... do your work ...
ez push -am "feat: add auth"     # 2. Ship tracked changes
ez push -Am "feat: add auth"     #    or include untracked files too
ez sync --autostash              # 3. Sync: pull trunk, clean merged, restack
ez delete feat/auth --yes        # 4. Done: remove worktree + branch, stop branch dev server, + cd back

That's it for normal flows. No raw git commit, no raw git push, no gh pr create, no manual cd. Use git add -p only when you need hunk-level selection before ez commit.

Never use these directly

Instead of	Use
git checkout -b	ez create
git commit	ez commit, ez push -am, or ez push -Am
git push	ez push
gh pr create	ez push
git diff main...HEAD	ez diff
git branch	ez list

Agent Startup

# 1. Check what's happening
ez list

# 2. Create your isolated workspace (always use --from main for independent work)
cd $(ez create my-task --from main)

# 3. You're in .worktrees/my-task with your own branch. Work here.

After any ez create, ez switch, ez checkout, ez delete, or ez sync that may change directories, immediately re-anchor file operations to the active worktree root:

pwd
git rev-parse --show-toplevel

Use that path, not the main repo checkout, for every subsequent read or write. Never reuse an absolute file path captured before switching into a linked worktree.

Always use --from main for independent tasks. Without it, ez stacks on the current branch.

Hooks: If .ez/hooks/post-create/default.md exists in the repo, ez prints its instructions after worktree creation. Follow them to set up the worktree (install deps, copy env, etc.). Use --hook <name> for a specific hook: ez create feat/auth --hook setup-node reads .ez/hooks/post-create/setup-node.md.

Hooks are markdown instructions for agents, not executable scripts. ez prints them, you follow them.

Working

Commit specific files (keeps changes focused)

ez commit -m "feat: add types" -- src/types.rs src/mod.rs

Bulk update when the whole tracked diff belongs together

ez commit -am "chore: regenerate fixtures"

Bulk update including untracked files

ez commit -Am "feat: add new docs and generated fixtures"

Partial hunks when one file mixes concerns

git add -p
ez commit -m "fix: keep intended hunks only"

Stack changes (multiple PRs from one workflow)

ez create feat/auth-api            # stacks on current branch
ez commit -m "feat: add API"
ez create feat/auth-middleware     # stacks on auth-api
ez commit -m "feat: add middleware"
ez submit                          # pushes + creates PRs for entire stack

Self-review before pushing

ez diff --stat       # what files changed vs parent
ez diff --name-only  # just file names
ez status            # stack info + working tree state

Ship it

ez push -am "feat: done"               # stage tracked changes + commit + push + create PR
ez push -Am "feat: done"               # include untracked files too
ez push --title "feat: auth" --body "..." # with PR metadata
ez push --no-pr                        # push branch only
ez push --pr                           # create/update PR even if no_pr config is true
ez submit                                # push entire stack
ez merge --yes                           # merge bottom PR non-interactively
ez merge --stack --yes                   # merge the current linear stack bottom-to-top

Sync with other agents' work

ez sync --autostash   # pulls trunk, cleans merged PRs, restacks your branches

Adopt branches from another machine or collaborator

ez adopt              # adopt all open PRs rooted on trunk
ez adopt --pr 42      # adopt PR #42 and its dependency chain
ez adopt feat/a feat/b  # adopt specific branches by name

ez adopt reads the PR graph from GitHub and reconstructs stack.json locally. Use it to continue working on someone else's stack from a fresh clone.

Finish

cd $(ez delete my-task --yes)   # removes worktree + branch, stops the branch dev server, cd's to repo root

Multi-Agent Rules

• One worktree per agent. Never share a worktree.
• Always --from main for independent tasks.
• Sync before push to pick up other agents' merged work.
• Preferred commit flow: ez commit -m "msg" -- path1 path2
• Bulk tracked update: ez commit -am "msg"
• Bulk tracked + untracked update: ez commit -Am "msg"
• Partial hunks: git add -p then ez commit -m "msg"

Receipts

Every mutating command emits a JSON receipt to stderr. Parse these to verify operations:

{"cmd":"create","branch":"feat/auth","parent":"main","worktree":".worktrees/feat-auth"}
{"cmd":"push","branch":"feat/auth","pr_number":42,"pr_url":"...","created":true}
{"cmd":"delete","branch":"feat/auth","worktree":".worktrees/feat-auth"}

Check redundant_commits > 0 after sync/restack — means commits were auto-dropped.

Exit Codes

Code	Meaning	Action
0	Success	Continue
1	Unexpected error	Log and stop
2	GitHub API error	gh auth status
3	Rebase conflict	Resolve, ez restack
4	Stale remote ref	git fetch, retry
5	Usage error	ez status
6	Unstaged changes	--autostash or --if-changed

Advanced Commands

See reference.md for the full command reference: ez adopt, ez commit, ez amend, ez diff, ez status, ez restack, ez log, ez move, ez merge, ez switch, ez pr-edit, ez draft/ez ready, ez pr-link, ez config, ez update, ez setup, ez skill install.