AI agent skill · by @danielvm-git

Kickoff Branch

Create an isolated Git worktree/branch or Jujutsu workspace, then verify a clean test baseline before code. Use when starting a feature or task.

Archived 2026-10-23 · Source updated 2026-09-17 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# story: e51s03
# story: e20s03
# story: e82s02


# Kickoff Branch

> **HARD GATE** — Direct Git work on `main`/`master` or reuse of an unrelated Jujutsu change is prohibited. Create a feature branch/worktree or Jujutsu workspace/change.
>
> **HARD GATE** — Do NOT proceed with development until **Preflight** passes on the default branch. Red Preflight blocks branch creation and all forward work — invoke `quick-fix` or `fix-bug` per CONVENTIONS § Discovered Defects.

Create an isolated Git worktree or Jujutsu workspace before code. **Preflight must be green** first — solo-default owns the whole tree.

## Process

### 1. Confirm task name

Ask if not already known: "What's the name of this feature or task?" Use it as the branch name slug (kebab-case, max 40 chars).

### 2. Select the VCS procedure

Read `state.yaml` `vcs.kind`. For `jj`, do not run the Git blocks below: verify with `jj status` and `jj log -r '::@' -n 5`, create isolation with `jj workspace add ../<task-slug> -r @`, then run `jj -R ../<task-slug> describe -m "feat: <task>"`. Record the new stable change ID. For `git`, continue below.

### 2a. Anchor Git on the default branch (main or master)

> **HARD GATE** — Git kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).

```bash
# Detect default branch
DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)

git checkout "$DEFAULT"
git pull --ff-only origin "$DEFAULT"   # skip if no remote
git status                             # working tree MUST be clean
git log --oneline -5
```

**Spec-only pre-kickoff** — before enforcing the clean-tree gate, check whether dirty files are spec artifacts:

```bash
DIRTY=$(git status --porcelain | awk '{print $2}')
NON_SPEC=$(echo "$DIRTY" | grep -v '^specs/' || true)

if [ -z "$DIRTY" ]; then
  : # clean — proceed
elif [ -z "$NON_SPEC" ]; then
  # spec-only dirty tree — offer auto-commit
  echo "Dirty spec artifacts: $(echo $DIRTY | tr '\n' ' ')"
  read -p "Commit spec artifacts before kickoff? [Y/n]: " CONFIRM
  CONFIRM=${CONFIRM:-Y}
  if [[ "$CONFIRM" =~ ^[Yy] ]]; then
    git add specs/
    git commit -m "chore(state): checkpoint before kickoff"
  fi
else
  echo "Dirty tree: $NON_SPEC (not a spec artifact). Stash or commit before proceeding."
  exit 1
fi
```

- **Spec artifacts** match `specs/` — state.yaml, epics YAMLs, execution-status.yaml, etc.
- **Non-spec dirty files** (src/, scripts/, SKILL.md, …) still enforce the full clean-tree gate.
- If not on `$DEFAULT` after checkout, stop and fix before continuing.

### 3. Git pre-flight & conflict resolution

Before creating the worktree, verify the target environment is clean:

```bash
# 1. Check for existing directory
ls -d ../<task-slug> 2>/dev/null

# 2. Check for existing branch
git branch --list <task-slug>

# 3. Check for "ghost" worktrees (metadata exists but directory is gone)
git worktree list | grep "<task-slug>"
```

**Handling Conflicts:**
- **Directory exists:** If `../<task-slug>` already exists, ask the user if they want to use it or delete it.
- **Branch exists:** If the branch exists but no worktree is attached, ask to use the existing branch (`git worktree add ../<task-slug> <task-slug>`) or delete it.
- **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata. `bash scripts/cleanup-worktrees.sh` does this plus reports any worktree whose branch is already merged or deleted — advisory only, it prints the `git worktree remove`/`git branch -d` commands rather than running them, so review before acting.

### 4. Create Git worktree + branch

```bash
# From the main repo root (not another worktree)
git worktree add ../<task-slug> -b <task-slug>
cd ../<task-slug>
```

If the user prefers a branch without a worktree:
```bash
git checkout -b <task-slug>
```

### 4. Verify clean baseline

> **HARD GATE (e39s02):** Acquire story lock in `specs/agent-locks.yaml` before running tests.

```bash
LOCK="specs/agent-locks.yaml"; STORY="<story-id>"
if [ -f "$LOCK" ]; then
  python3 -c "
import yaml,sys,datetime
d=yaml.safe_load(open('$LOCK'))or{'locks':[]}
for l in d['locks']:
  if l['story_id']=='$STORY':print(f'LOCKED by {l[\"locked_by\"]} at {l[\"locked_at\"]}');sys.exit(1)
d['locks'].append({'story_id':'$STORY','locked_by':'agent: build-epic','locked_at':datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),'files_touched':[]})
yaml.dump(d,open('$LOCK','w'),default_flow_style=False)
print(f'LOCK ACQUIRED: $STORY')
"
fi
```

If locked: abort. If unlocked: entry added, proceed.

Run **Preflight** (from `CLAUDE.md` Commands table, or `BP_PREFLIGHT` from `bash scripts/bp-read-agents.sh`) and confirm green before writing any code:

```bash
# Preflight — project's full local verification stack
# bigpowers example:
npm run compliance && bash scripts/run-verification-gates.sh

# Or project-specific from CLAUDE.md / AGENTS.md
```

- [ ] Preflight passes (all chained gates green)
- [ ] No type errors (`npm run typecheck` or equivalent, if not in Preflight)
- [ ] No lint errors (`npm run lint` or equivalent, if not in Preflight)

If Preflight is red, **stop** — route to `quick-fix` or `fix-bug`. Fix before kickoff continues.

### 5. Confirm readiness

Report: `✓ Preflight green` + branch + worktree. Suggest next: `develop-tdd` or `execute-plan`.

## Handoff

Gate: READY -> next: develop-tdd
Writes: state.yaml handoff.next_skill = develop-tdd