Windsurf rules

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