Skip to content

Commit bc8e719

Browse files
jwaldripclaude
andcommitted
fix(plugin): create intent worktree before discovery to avoid artifacts on main
Move worktree creation from Phase 6 to Phase 2.25 so discovery.md and all subsequent files are written directly on the intent branch. This prevents untracked .ai-dlc/{slug}/ artifacts from being left on main during elaboration. Also updates Phase 0 "Start fresh" cleanup to properly remove worktrees and intent branches. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 78c56b2 commit bc8e719

File tree

1 file changed

+60
-44
lines changed

1 file changed

+60
-44
lines changed

plugin/skills/elaborate/SKILL.md

Lines changed: 60 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,22 @@ If the user invoked this with a slug argument:
149149

150150
If no slug provided, or the intent doesn't exist, proceed to Phase 1.
151151

152-
**Start fresh cleanup:** When the user chooses "Start fresh", delete the entire `.ai-dlc/{slug}/` directory. This includes any `discovery.md` that may have been created in a prior elaboration attempt:
152+
**Start fresh cleanup:** When the user chooses "Start fresh", remove the intent worktree and its branch (if they exist from a prior elaboration attempt), then clean up any leftover `.ai-dlc/{slug}/` directory:
153153

154154
```bash
155+
PROJECT_ROOT=$(git rev-parse --show-toplevel)
156+
INTENT_WORKTREE="${PROJECT_ROOT}/.ai-dlc/worktrees/${slug}"
157+
INTENT_BRANCH="ai-dlc/${slug}/main"
158+
159+
# Remove worktree if it exists
160+
if [ -d "$INTENT_WORKTREE" ]; then
161+
git worktree remove --force "$INTENT_WORKTREE" 2>/dev/null
162+
fi
163+
164+
# Delete the intent branch if it exists
165+
git branch -D "$INTENT_BRANCH" 2>/dev/null
166+
167+
# Clean up any leftover directory on main (from older elaboration format)
155168
rm -rf ".ai-dlc/${slug}"
156169
```
157170

@@ -192,17 +205,38 @@ Continue asking until you can articulate back to the user, in your own words, ex
192205

193206
---
194207

195-
## Phase 2.25: Discovery Artifact Initialization
208+
## Phase 2.25: Intent Worktree & Discovery Initialization
196209

197-
Before beginning technical exploration, initialize the discovery scratchpad. This file persists elaboration findings to disk so they survive context compaction and are available to builders later.
210+
Before beginning technical exploration, create the intent worktree and initialize the discovery scratchpad inside it. Creating the worktree early ensures **no artifacts are left on `main`** — all files from this point forward are written on the intent branch.
198211

199212
```bash
200213
# Derive intent slug from the user's description (same slug used throughout elaboration)
201214
INTENT_SLUG="{intent-slug}"
215+
PROJECT_ROOT=$(git rev-parse --show-toplevel)
216+
INTENT_BRANCH="ai-dlc/${INTENT_SLUG}/main"
217+
INTENT_WORKTREE="${PROJECT_ROOT}/.ai-dlc/worktrees/${INTENT_SLUG}"
218+
219+
# Ensure worktrees directory exists and is gitignored (on main, before creating worktree)
220+
mkdir -p "${PROJECT_ROOT}/.ai-dlc/worktrees"
221+
if ! grep -q '\.ai-dlc/worktrees/' "${PROJECT_ROOT}/.gitignore" 2>/dev/null; then
222+
echo '.ai-dlc/worktrees/' >> "${PROJECT_ROOT}/.gitignore"
223+
git add "${PROJECT_ROOT}/.gitignore"
224+
git commit -m "chore: gitignore .ai-dlc/worktrees"
225+
fi
226+
227+
# Create the intent worktree on its own branch
228+
git worktree add -B "$INTENT_BRANCH" "$INTENT_WORKTREE"
229+
cd "$INTENT_WORKTREE"
230+
```
231+
232+
**Tell the user the worktree location** so they know where to find it.
233+
234+
Now initialize the discovery scratchpad. This file persists elaboration findings to disk so they survive context compaction and are available to builders later.
235+
236+
```bash
202237
DISCOVERY_DIR=".ai-dlc/${INTENT_SLUG}"
203238
DISCOVERY_FILE="${DISCOVERY_DIR}/discovery.md"
204239

205-
# Create directory (may already exist from Phase 0)
206240
mkdir -p "$DISCOVERY_DIR"
207241

208242
# Initialize discovery.md with frontmatter header
@@ -221,7 +255,15 @@ Builders: read section headers for an overview, then dive into specific sections
221255
DISCOVERY_EOF
222256
```
223257

224-
This file lives in the main repo's working directory (not in a worktree — the worktree doesn't exist yet). It will be copied into the intent worktree in Phase 6.
258+
This file is written directly in the intent worktree on the `ai-dlc/{intent-slug}/main` branch. No artifacts touch `main`.
259+
260+
This ensures:
261+
- Main working directory stays on `main` for other work
262+
- All discovery findings are written directly on the intent branch
263+
- All subsequent `han keep` operations use the intent branch's storage
264+
- Multiple intents can run in parallel in separate worktrees
265+
- Clean separation between main and AI-DLC orchestration state
266+
- Subagents spawn from the intent worktree, not the original repo
225267

226268
---
227269

@@ -842,53 +884,27 @@ Map selections to the `announcements` array in intent.md frontmatter:
842884

843885
## Phase 6: Write AI-DLC Artifacts
844886

845-
Create the intent branch and worktree, then write files in `.ai-dlc/{intent-slug}/`:
887+
Write intent and unit files in `.ai-dlc/{intent-slug}/` (already in the intent worktree since Phase 2.25):
846888

847-
### 1. Create intent branch and worktree
889+
### 1. Verify intent worktree
848890

849-
**CRITICAL: The intent MUST run in an isolated worktree, not the main working directory. Create this BEFORE writing any artifacts so all files are committed to the intent branch.**
891+
The intent worktree was already created in **Phase 2.25** (before discovery began), so all files — including `discovery.md` — are already on the intent branch. Verify we're in the right place:
850892

851893
```bash
894+
INTENT_SLUG="{intent-slug}"
852895
PROJECT_ROOT=$(git rev-parse --show-toplevel)
853-
INTENT_BRANCH="ai-dlc/${intentSlug}/main"
854-
INTENT_WORKTREE="${PROJECT_ROOT}/.ai-dlc/worktrees/${intentSlug}"
855-
856-
# Ensure worktrees directory exists and is gitignored
857-
mkdir -p "${PROJECT_ROOT}/.ai-dlc/worktrees"
858-
if ! grep -q '\.ai-dlc/worktrees/' "${PROJECT_ROOT}/.gitignore" 2>/dev/null; then
859-
echo '.ai-dlc/worktrees/' >> "${PROJECT_ROOT}/.gitignore"
860-
git add "${PROJECT_ROOT}/.gitignore"
861-
git commit -m "chore: gitignore .ai-dlc/worktrees"
862-
fi
863-
864-
git worktree add -B "$INTENT_BRANCH" "$INTENT_WORKTREE"
865-
cd "$INTENT_WORKTREE"
866-
```
867-
868-
#### 1b. Copy discovery.md into worktree
869-
870-
If a discovery log was created during Phase 2.5, copy it into the worktree so it gets committed with the intent artifacts:
871-
872-
```bash
873-
DISCOVERY_SOURCE="${PROJECT_ROOT}/.ai-dlc/${INTENT_SLUG}/discovery.md"
874-
if [ -f "$DISCOVERY_SOURCE" ]; then
875-
mkdir -p "${INTENT_WORKTREE}/.ai-dlc/${INTENT_SLUG}"
876-
cp "$DISCOVERY_SOURCE" "${INTENT_WORKTREE}/.ai-dlc/${INTENT_SLUG}/discovery.md"
896+
INTENT_WORKTREE="${PROJECT_ROOT}" # We should already be cd'd into the worktree
897+
898+
# Verify we're on the intent branch
899+
CURRENT_BRANCH=$(git branch --show-current)
900+
EXPECTED_BRANCH="ai-dlc/${INTENT_SLUG}/main"
901+
if [ "$CURRENT_BRANCH" != "$EXPECTED_BRANCH" ]; then
902+
echo "ERROR: Expected to be on branch $EXPECTED_BRANCH but on $CURRENT_BRANCH"
903+
echo "The intent worktree should have been created in Phase 2.25."
904+
exit 1
877905
fi
878906
```
879907

880-
The file is already caught by `git add .ai-dlc/` in Step 5's commit.
881-
882-
This ensures:
883-
- Main working directory stays on `main` for other work
884-
- All artifacts are written directly on the intent branch
885-
- All subsequent `han keep` operations use the intent branch's storage
886-
- Multiple intents can run in parallel in separate worktrees
887-
- Clean separation between main and AI-DLC orchestration state
888-
- Subagents spawn from the intent worktree, not the original repo
889-
890-
**Tell the user the worktree location** so they know where to find it.
891-
892908
### 2. Write `intent.md`:
893909
```markdown
894910
---

0 commit comments

Comments
 (0)