Cursor rule

1---
2description: "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions \"start a branch\" or \"new worktree\"."
3alwaysApply: false
4---
5 
6# story: e51s03
7# story: e20s03
8 
9 
10# Kickoff Branch
11 
12> **HARD GATE** — Direct work on `main` or `master` is PROHIBITED. Every task MUST start with this skill to create a feature branch or worktree.
13>
14> **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.
15 
16Create an isolated working environment before touching any code. **Preflight must be green** before you write feature code — solo-default owns the whole tree, not just the current task diff.
17 
18## Process
19 
20### 1. Confirm task name
21 
22Ask 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).
23 
24### 2. Anchor on default branch (main or master)
25 
26> **HARD GATE** — Kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).
27 
28```bash
29# Detect default branch
30DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
31
32git checkout "$DEFAULT"
33git pull --ff-only origin "$DEFAULT"   # skip if no remote
34git status                             # working tree MUST be clean
35git log --oneline -5
36```
37 
38**Spec-only pre-kickoff** — before enforcing the clean-tree gate, check whether dirty files are spec artifacts:
39 
40```bash
41DIRTY=$(git status --porcelain | awk '{print $2}')
42NON_SPEC=$(echo "$DIRTY" | grep -v '^specs/' || true)
43
44if [ -z "$DIRTY" ]; then
45  : # clean — proceed
46elif [ -z "$NON_SPEC" ]; then
47  # spec-only dirty tree — offer auto-commit
48  echo "Dirty spec artifacts: $(echo $DIRTY | tr '\n' ' ')"
49  read -p "Commit spec artifacts before kickoff? [Y/n]: " CONFIRM
50  CONFIRM=${CONFIRM:-Y}
51  if [[ "$CONFIRM" =~ ^[Yy] ]]; then
52    git add specs/
53    git commit -m "chore(state): checkpoint before kickoff"
54  fi
55else
56  echo "Dirty tree: $NON_SPEC (not a spec artifact). Stash or commit before proceeding."
57  exit 1
58fi
59```
60 
61- **Spec artifacts** match `specs/` — state.yaml, epics YAMLs, execution-status.yaml, etc.
62- **Non-spec dirty files** (src/, scripts/, SKILL.md, …) still enforce the full clean-tree gate.
63- If not on `$DEFAULT` after checkout, stop and fix before continuing.
64 
65### 3. Pre-flight & Conflict Resolution
66 
67Before creating the worktree, verify the target environment is clean:
68 
69```bash
70# 1. Check for existing directory
71ls -d ../<task-slug> 2>/dev/null
72 
73# 2. Check for existing branch
74git branch --list <task-slug>
75 
76# 3. Check for "ghost" worktrees (metadata exists but directory is gone)
77git worktree list | grep "<task-slug>"
78```
79 
80**Handling Conflicts:**
81- **Directory exists:** If `../<task-slug>` already exists, ask the user if they want to use it or delete it.
82- **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.
83- **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.
84 
85### 4. Create worktree + branch
86 
87```bash
88# From the main repo root (not another worktree)
89git worktree add ../&lt;task-slug&gt; -b &lt;task-slug&gt;
90cd ../&lt;task-slug&gt;
91```
92 
93If the user prefers a branch without a worktree:
94```bash
95git checkout -b &lt;task-slug&gt;
96```
97 
98### 4. Verify clean baseline
99 
100> **HARD GATE (e39s02):** Acquire story lock in `specs/agent-locks.yaml` before running tests.
101 
102```bash
103LOCK=&quot;specs/agent-locks.yaml&quot;; STORY=&quot;&lt;story-id&gt;&quot;
104if [ -f &quot;$LOCK&quot; ]; then
105  python3 -c &quot;
106import yaml,sys,datetime
107d=yaml.safe_load(open('$LOCK'))or{'locks':[]}
108for l in d['locks']:
109  if l['story_id']=='$STORY':print(f'LOCKED by {l[\"locked_by\"]} at {l[\"locked_at\"]}');sys.exit(1)
110d['locks'].append({'story_id':'$STORY','locked_by':'agent: build-epic','locked_at':datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),'files_touched':[]})
111yaml.dump(d,open('$LOCK','w'),default_flow_style=False)
112print(f'LOCK ACQUIRED: $STORY')
113&quot;
114fi
115```
116 
117If locked: abort. If unlocked: entry added, proceed.
118 
119Run **Preflight** (from `CLAUDE.md` Commands table, or `BP_PREFLIGHT` from `bash scripts/bp-read-agents.sh`) and confirm green before writing any code:
120 
121```bash
122# Preflight — project's full local verification stack
123# bigpowers example:
124npm run compliance && bash scripts/run-verification-gates.sh
125 
126# Or project-specific from CLAUDE.md / AGENTS.md
127```
128 
129- [ ] Preflight passes (all chained gates green)
130- [ ] No type errors (`npm run typecheck` or equivalent, if not in Preflight)
131- [ ] No lint errors (`npm run lint` or equivalent, if not in Preflight)
132 
133If Preflight is red, **stop** — route to `quick-fix` or `fix-bug`. Fix before kickoff continues.
134 
135### 5. Confirm readiness
136 
137Report: `✓ Preflight green` + branch + worktree. Suggest next: `develop-tdd` or `execute-plan`.
138 
139## Handoff
140 
141Gate: READY -> next: develop-tdd
142Writes: state.yaml handoff.next_skill = develop-tdd
143