aep-git-ref
/aep-git-ref
Canonical AEP git reference: base resolution, worktree lifecycle, naming, task commits, PRs, recovery. Use when a git convention is needed.
- Author
- memorysaver ↗
- Repository
- agentic-engineering-patterns ↗
- Licence
- MIT
- Last repository change
- 18.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 18.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Canonical AEP git reference: base resolution, worktree lifecycle, naming, task commits, PRs, recovery. Use when a git convention is needed.
Original author description
Canonical AEP git reference: base resolution, worktree lifecycle, naming, task commits, PRs, recovery. Use when a git convention is needed.
How it works
- Integration Branch
- Worktree Lifecycle
- Branch Naming
- The One-Commit-per-Task Pattern (Phase 4 of /aep-build)
- Publishing & PR Conventions
- Control-Plane Commits (on the integration branch)
- Recovery
- Disk Budget
- Cheat Sheet
SKILL.md preview
---
name: aep-git-ref
description: >-
Canonical AEP git reference: base resolution, worktree lifecycle, naming,
task commits, PRs, recovery. Use when a git convention is needed.
---
# Git + Worktree Reference (AEP)
`/aep-launch`, `/aep-build`, and `/aep-wrap` operate on a plain git repository plus `git worktree` for parallel agent isolation — when these skills say "commit", they mean `git commit`. This skill is the **canonical home** for AEP's git conventions: every other skill resolves `$BASE`, creates/removes worktrees, and opens PRs by pointing here, never by re-inlining these blocks. Rationale for plain git (agent training data, universal tooling): [docs/decisions/migrate-from-jj-to-git.md](https://github.com/memorysaver/agentic-engineering-patterns/blob/main/docs/decisions/migrate-from-jj-to-git.md).
---
## Integration Branch
Every AEP git operation targets the **integration branch** — the branch feature worktrees are
created from, rebased onto, PR'd into, merged into, and where control-plane commits (`/aep-dispatch`,
`/aep-design`, the `/aep-wrap` archive) land. Throughout this skill and the bash blocks in `/aep-launch`,
`/aep-build`, `/aep-wrap`, and the product-context skills, this branch is referred to as `$BASE`.
AEP **auto-detects** one of two modes — no configuration required for the common cases:
| Mode | Condition | Integration (`$BASE`) | Production |
| --------------------------- | ------------------- | --------------------- | --------------------- |
| **single-branch** (default) | no `develop` branch | `main` | `main` (same branch) |
| **two-branch** | `develop` exists | `develop` (staging) | `main` (promote-only) |
A project grows from single- to two-branch mode simply by creating a `develop` branch — no
reconfiguration. In two-branch mode AEP **never touches the production branch** (`main`): promotion
from integration to production (`develop` → `main`) is the user's concern, exactly like deployment,
which is already outside AEP's scope.
### Resolving `$BASE`
Every git-touching skill resolves the integration branch at the top of its first bash block:
```bash
# Resolve AEP integration branch ($BASE): override → auto-detect develop → main
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
if [ -z "$BASE" ]; then
if git show-ref --verify --quiet refs/heads/develop \
|| git show-ref --verify --quiet refs/remotes/origin/develop; then
BASE=develop
else
BASE=main
fi
fi
```
Resolution order:
1. **Explicit override** — `git config --get aep.integration-branch`. This is an **override only**,
for a non-standard integration branch name (e.g. `staging`, `integration`). You do **not** set it
for the standard `main`/`develop` cases — those are auto-detected. `/aep-onboard` reports the detected
mode and only writes this key when you use a non-standard name
(`git config aep.integration-branch <name>`; unset with `git config --unset aep.integration-branch`).
2. **Auto-detect** — `develop` if it exists locally or on `origin`.
3. **Default** — `main` (single-branch mode).
Because the standard cases are auto-detected (not pinned), a project **grows from single- to
two-branch mode with no reconfiguration**: create `develop` and every skill resolves `$BASE` to it
on the next run. (If you had pinned `aep.integration-branch=main`, that override would win and
suppress the upgrade — which is why setup does not pin the default.)
`git config --get aep.integration-branch` is repo-local and shared across all worktrees via the
common `.git/config`, so `$BASE` resolves identically in the main session and inside any
`.feature-workspaces/<name>` worktree.
---
## Worktree Lifecycle
### Create
```bash
# Resolve $BASE first — see "Resolving $BASE" above
mkdir -p .feature-workspaces
git worktree add -b feat/<name> .feature-workspaces/<name> "$BASE"
```
- Path is **always** under `.feature-workspaces/<name>` (kept gitignored).
- Branch is **always** `feat/<name>` — corresponding to the OpenSpec change name or story id.
- Base is **always** the integration branch `$BASE`.
The worktree shares `.git/objects` with the main repo, so creating it is fast and history is not duplicated. Only the working tree files are duplicated on disk.
### Inspect
```bash
git worktree list # all worktrees, branches, paths
git -C .feature-workspaces/<name> status # status inside a specific worktree
git -C .feature-workspaces/<name> log --oneline "$BASE"..HEAD # commits unique to the feature branch
```
### Remove (`/aep-wrap` step 6)
```bash
git worktree remove .feature-workspaces/<name>
git branch -d feat/<name>
```
If `git branch -d` warns the branch isn't fully merged (likely because the PR was squash-merged so commit SHAs differ), force with `git branch -D feat/<name>` _after_ confirming via `gh pr view <number> --json state` that the PR is `MERGED`.
### Recover from a corrupt worktree directory
If `.feature-workspaces/<name>/` was deleted manually:
```bash
git worktree prune # forget the orphaned registration
git branch -D feat/<name> # delete the orphan branch (if needed)
```
If `.git/worktrees/<name>/` still references a missing path (e.g. you moved the parent directory):
```bash
git worktree repair .feature-workspaces/<name>
```
---
## Branch Naming
| Branch | Pattern | Created by |
| ----------------- | -------------------- | ----------------------------- |
| Feature work | `feat/<short-name>` | `/aep-launch` (one per story) |
| Migration / chore | `chore/<short-name>` | manually, when applicable |
| Hotfix off main | `fix/<short-name>` | manually |
| Migration project | `migration/<topic>` | manually |
**Rules:**
- Use kebab-case after the slash. No spaces, no underscores.
- Keep names short (≤ 30 chars) — they appear in tab labels, signal files, and PR titles.
- Reuse a deleted branch name once its worktree is fully removed (`git worktree prune` clears the dangling refs).
---
## The One-Commit-per-Task Pattern (Phase 4 of `/aep-build`)
### What
`tasks.md` lists N tasks. The feature branch ends up with N commits — one per task — in the same order. Conventional-commit format. Workspace agents implement linearly, committing after each task, so the commit count matches the task count:
```bash
# Implement task 1
# ... edit files ...
git add -A
git commit -m "feat(auth): extract auth service"
# Implement task 2
# ... edit files ...
git add -A
git commit -m "feat(auth): add token refresh flow"
# ... etc.
```
After each commit, record the short SHA in `.dev-workflow/feature-verification.json` against the matching task entry's `commit_sha` field.
### Why this shape
- The PR's commit list reads like a table of contents matching `tasks.md`.
- Each commit is a self-contained unit that the evaluator (in Phase 5) and reviewers (in Phase 11) can `git show <sha>` independently.
- We squash-merge at PR-merge time, so per-commit hygiene only matters for review readability — the integration branch's history stays clean automatically.
- It removes any need to rewrite history mid-stream, which is where agents most often go off the rails.
### What to do when something goes wrong
| Situation | Action |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forgot a file in the just-committed task | `git add <file> && git commit --amend --no-edit` (only safe **before** the next task's commit) |
| Realized the previous task is broken, several commits ago | Add a new commit: `fix(<scope>): correct <issue from task N>` — the history stays append-only |
| Review feedback or eval-loop FAIL | Add a follow-up commit: `fix(<scope>): address review on <topic>` |
| Need to update against new origin/`$BASE` | `git fetch origin && git rebase origin/"$BASE" && git push --force-with-lease origin feat/<name>` |
| Conflicts during rebase | Resolve in working tree, `git add <files> && git rebase --continue`. If hopelessly tangled, `git rebase --abort` and surface to the orchestrator via signal file. |
Push a rewritten branch with `--force-with-lease` rather than a bare `--force`: the lease variant fails safely when someone else has pushed since your last fetch.
---
## Publishing & PR Conventions
### Push the feature branch
```bash
# First push (after Phase 9 cleanup):
git push -u origin feat/<name>
# Subsequent pushes (review fixes, rebases):
git push origin feat/<name>
# or after a rebase:
git push --force-with-lease origin feat/<name>
```
### Open the PR — always set base explicitly
```bash
# $BASE is the integration branch — resolve it first (see "Integration Branch" above)
gh pr create --base "$BASE" --title "<title>" --body "<body>"
```
The `--base "$BASE"` flag is **mandatory**: without it `gh` infers the base from local branch state (a dispatch commit can look like a recent base), the PR merges into a non-integration branch, and the code never lands on `$BASE`. In two-branch mode an inferred base could be production `main`, which AEP never merges feature work into.
### Merge the PR
```bash
gh pr merge <number> --squash --delete-branch
```
We always squash-merge. The feature branch's per-task commits collapse into one commit on the integration branch (`$BASE`), which keeps its log readable while preserving the per-task review trail in the PR's "Commits" tab.
---
## Control-Plane Commits (on the integration branch)
`/aep-design`, `/aep-dispatch`, `/aep-envision`, `/aep-map`, `/aep-calibrate`, `/aep-validate`, `/aep-reflect`, and the `/aep-wrap` archive step all commit directly to the integration branch (`$BASE`). The pattern is identical:
```bash
# Resolve $BASE first — see "Resolving $BASE" above
git pull --ff-only origin "$BASE" # fail-fast if the integration branch has diverged
git add <specific-files> # never -A on the integration branch; be explicit
git commit -m "<conventional message>"
git push origin "$BASE"
```
The `--ff-only` is intentional — it refuses a non-fast-forward pull, which means concurrent pushes get caught instead of silently merged. If the pull fails because someone else pushed first, fetch, rebase your work, and try again.
---
## Recovery
### Lost a commit (committed to wrong branch, or amend'd away)
```bash
git reflog # find the orphaned commit's SHA
git cherry-pick <sha> # bring it onto the current branch
# or
git reset --hard <sha> # if you want to rewind to that point
```
### Lost an entire branch (deleted with -D)
```bash
git reflog # the deleted branch's tip is in here
git branch <name> <sha> # recreate the branch at that tip
```
### Lost work in a worktree directory you removed
If you ran `rm -rf .feature-workspaces/<name>` without committing first, the work is gone — `git worktree` only tracks committed history. `.dev-workflow/` files (signals, lessons, progress) are also gone since they're gitignored. Use `git worktree remove` instead of `rm -rf` next time; it refuses if the worktree has uncommitted changes.
### OpenSpec files missing after rebase
If the dispatch commit's OpenSpec files disappeared during a rebase or merge:
```bash
git log --oneline -n 30 # find the dispatch commit SHA
git restore --source=<sha> -- openspec/
```
This restores `openspec/` to the state of the dispatch commit without touching anything else.
---
## Disk Budget
Each worktree adds approximately one full working-tree copy on disk. `.git/objects` is shared across all worktrees, so commit history isn't duplicated. For a typical AEP repo (~100 MB working tree, multi-GB `.git/objects` after years of history), three concurrent agents adds ~300 MB on top of one shared `.git/`.
Monitor with:
```bash
du -sh .feature-workspaces/ # working-tree footprint
du -sh .git/objects # shared history
```
If disk pressure hits before agents finish, prefer pausing new `/aep-launch` invocations over forcibly removing in-flight worktrees.
---
## Cheat Sheet
| You want to… | Run |
| ---------------------------- | ----------------------------------------------------------------------- |
| Create a feature worktree | `git worktree add -b feat/<n> .feature-workspaces/<n> "$BASE"` |
| List all worktrees | `git worktree list` |
| See feature-branch commits | `git log --oneline "$BASE"..HEAD` |
| Sync against latest `$BASE` | `git fetch origin && git rebase origin/"$BASE"` |
| Push after rebase | `git push --force-with-lease origin feat/<n>` |
| Open PR | `gh pr create --base "$BASE"` |
| Merge PR | `gh pr merge <#> --squash --delete-branch` |
| Remove worktree post-merge | `git worktree remove .feature-workspaces/<n> && git branch -d feat/<n>` |
| Recover deleted commit | `git reflog` then `git cherry-pick <sha>` |
| Restore lost openspec/ files | `git restore --source=<sha> -- openspec/` |
Versions
The database has no other skills named aep-git-ref.
Database snapshot: 13.11.2026 · package version 4151dc18ab32 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95aep-dispatch
Picks one ready story and hands it to /aep-design or /aep-launch. Use for "what's next" or "dispatch"; running continuously is /aep-autopilot. - 95aep-autopilot
Runs dispatch through wrap continuously for a whole layer, unattended. Use for "autopilot" or "hands-free"; for a single story use /aep-dispatch. - 100git-wtpr
Opens or deletes a git-wt worktree for a GitHub pull request. Use when creating, switching to, or removing a PR worktree. - 100git-workflows
Execute git and GitHub operations with Conventional Commits and agent-safe defaults. Use raw git/gh directly. Use gw only for worktree lifecycle (create/finish). Use when making commits, managing branches, working with PRs/issues, or performing any version control operations. - 90git-workflow
Safely inspect and perform everyday Git work: branches, focused commits, history, integration, conflicts, worktrees, and recovery. Use for local version-control tasks that are not GitHub settings or release publication. - 100checkout
Use when checking out a PR, branch, or ref for local work - sets up worktree with context