Worktree Workflow

Overview

Orchestrate the full development loop: review → implement → audit → finish/reach.

Core principle: Guided workflow with state persistence across sessions.

Announce at start: "I'm using the worktree-workflow skill to [start/continue] the development workflow."

State file: .workflow-state.json (repo root)

Invocation Patterns

Phase Flow

start → [plan-readiness-review] → markdown summary
                                        ↓
                              User: "looks good" / adjust
                                        ↓
implement → [executing-plans autonomous] → markdown summary
                                        ↓
audit → [implementation-review] → markdown summary
                                        ↓
                    AskUserQuestion: "What next?"
                         ┌──────────────┴──────────────┐
                         ↓                             ↓
                   "Done, finish branch"        "Explore reach opportunities"
                         ↓                             ↓
                   [sync-with-base]             reach → [reach-opportunities]
                         ↓                             ↓
           [finishing-a-development-branch]    pick items → implement
                         ↓                             ↓
                   [plan-complete]             back to audit

State Management

State File Location

Check for Emacs metadata first:

REPO=$(basename "$(git rev-parse --show-toplevel)")
BRANCH=$(git branch --show-current)
EMACS_METADATA="$HOME/worktrees/metadata/$REPO/$BRANCH.json"

if [[ -f "$EMACS_METADATA" ]]; then
  # Use Emacs metadata - read/write workflow as nested key
  # Read:  jq -r '.workflow // empty' "$EMACS_METADATA"
  # Write: Use Read tool, modify plist, use Write tool
  STATE_LOCATION="emacs"
else
  # Fallback for non-Emacs sessions
  STATE_LOCATION=".workflow-state.json"
  # Ensure state file is gitignored (workflow state is session-specific)
  if ! grep -q ".workflow-state.json" .gitignore 2>/dev/null; then
    echo ".workflow-state.json" >> .gitignore
  fi
fi

Emacs metadata workflow key:

{
  "workflow": {
    "plan": "plan-name",
    "phase": "review",
    "started": "2026-02-01T10:00:00Z",
    "history": []
  }
}

When writing to Emacs metadata, merge the workflow key into existing JSON (don't overwrite other fields).

State Schema

{
  "plan": "plan-name",
  "phase": "review | implement | audit | reach | complete",
  "started": "2025-01-31T10:00:00Z",
  "history": [
    { "phase": "review", "verdict": "READY", "timestamp": "..." },
    { "phase": "implement", "tasks": "12/12", "timestamp": "..." }
  ],
  "reachIterations": 0
}

Reading State

cat .workflow-state.json 2>/dev/null || echo "No workflow state"

Writing State

Use Write tool to update .workflow-state.json after each phase.

The Process

On Invocation: Detect Current State

1. •Check for .workflow-state.json
2. •If exists: Resume from recorded phase
3. •If not: Prompt user for plan name to start

Phase: start

Trigger: /worktree-workflow start {plan-name} or first run with plan name

1. •Verify not on main branch:
   bash

   current=$(git branch --show-current)
   if [[ "$current" == "main" || "$current" == "master" ]]; then
     echo "ERROR: Cannot run workflow on $current branch. Use a feature branch in a worktree."
     exit 1
   fi
   

2. •Verify plan exists at plans/active/{plan-name}/
3. •Initialize state file:
   json

   {
     "plan": "{plan-name}",
     "phase": "review",
     "started": "{timestamp}",
     "history": [],
     "reachIterations": 0
   }
   

4. •INVOKE: gremlins:plan-readiness-review
5. •Present markdown summary
6. •Wait for user to approve or request changes

If READY: User says "looks good" → advance to implement phase If NEEDS WORK: User fixes issues → re-run review

Phase: implement

Trigger: User approves plan review OR /worktree-workflow implement

1. •Update state to "phase": "implement"
2. •INVOKE: gremlins:executing-plans (autonomous mode)
3. •On completion, update state with task count
4. •Add history entry
5. •Present completion summary
6. •Advance to audit phase

Phase: audit

Trigger: Implementation complete OR /worktree-workflow audit

1. •Update state to "phase": "audit"
2. •INVOKE: gremlins:implementation-review
3. •Add history entry with verdict

If MERGE READY:

Present choice using AskUserQuestion:

Implementation passed review. What would you like to do?

1. Done - finish the branch (merge/PR)
2. Explore reach opportunities first

• •Option 1 → Sync with base, then INVOKE: gremlins:finishing-a-development-branch, then plan-complete
• •Option 2 → Advance to reach phase

If NEEDS FIXES:

• •Present issues
• •User fixes
• •Re-run audit

Phase: reach

Trigger: User chooses "Explore reach opportunities" OR /worktree-workflow reach

1. •Check iteration count:
   code

   if reachIterations >= 2:
     Present: "You've done 2 reach cycles. Recommend finishing branch now."
     Offer: finish anyway OR one more reach cycle
   

2. •Update state: "phase": "reach", increment reachIterations
3. •INVOKE: gremlins:reach-opportunities
4. •Present opportunities
5. •User picks items to implement (or none)

If items selected:

• •Implement selected items
• •Return to audit phase for re-review

If no items selected:

• •Sync with base
• •INVOKE: gremlins:finishing-a-development-branch
• •INVOKE: gremlins:plan-complete
• •Mark complete

Before Finishing: Sync With Base

Always run this before invoking finishing-a-development-branch:

# Fetch latest from remote
git fetch origin

# Detect base branch
base_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$base_branch" ]; then
  base_branch=$(git merge-base HEAD main 2>/dev/null && echo main || echo master)
fi

# Check if base has advanced since we branched
merge_base=$(git merge-base HEAD "origin/$base_branch")
if [ "$(git rev-parse origin/$base_branch)" != "$merge_base" ]; then
  echo "Base branch ($base_branch) has new commits since you started."
fi

If base has advanced, present options:

Base branch has new commits. How would you like to proceed?

1. Rebase on latest base (recommended - cleaner history)
2. Merge base into feature branch (preserves history)
3. Proceed anyway (PR may have conflicts)

Option 1 (Rebase):

git rebase "origin/$base_branch"
# If conflicts, stop and let user resolve
# Re-run tests after rebase

Option 2 (Merge base in):

git merge "origin/$base_branch" -m "Merge $base_branch into $(git branch --show-current)"
# If conflicts, stop and let user resolve
# Re-run tests after merge

Option 3: Proceed without sync (user accepts potential conflicts)

If base hasn't advanced: Skip directly to finishing-a-development-branch.

Phase: complete

1. •

   INVOKE: gremlins:plan-complete (moves plan from active/ to complete/)

2. •

   Update state:

{
  "phase": "complete",
  "history": [..., { "phase": "complete", "timestamp": "..." }]
}

1. •Report: "Workflow complete for {plan-name}. Plan moved to complete/."

Abort Command

/worktree-workflow abort handles workflow abandonment:

1. •Read current state
2. •Report what was completed:
   code

   ## Workflow Aborted: {plan-name}
   
   ### Progress Before Abort
   | Phase | Status |
   |-------|--------|
   | review | ✓ READY |
   | implement | 8/12 tasks |
   
   ### Branch State
   - Branch: {branch-name}
   - Commits since start: {N}
   
   ### Cleanup
   - State file removed
   - Branch preserved (delete manually if needed)
   

3. •Delete .workflow-state.json
4. •Do NOT delete the branch or commits (user decides)

Status Command

/worktree-workflow status outputs:

## Workflow Status: {plan-name}

**Current Phase:** {phase}
**Started:** {started}

### History
| Phase | Result | Timestamp |
|-------|--------|-----------|
| review | READY | 2025-01-31 10:00 |
| implement | 12/12 tasks | 2025-01-31 11:30 |

### Next Step
[What to do next based on current phase]

Key Behaviors

• •State persists: Pick up where you left off across sessions
• •Phases are skippable: Can jump to audit if implemented manually
• •Reach is opt-in: Only explore if user chooses after passing audit
• •Sub-skills do the work: Orchestrator invokes, doesn't duplicate logic
• •Sync before finishing: Always fetch and check base branch before merge/PR
• •Plan lifecycle: Invokes plan-complete to move plan from active/ to complete/

Red Flags

Never:

• •Skip phases without user acknowledgment
• •Proceed to implement without plan review passing
• •Proceed to finish without audit passing
• •Force reach opportunities on user

Always:

• •Check state on every invocation
• •Update state after every phase transition
• •Present clear options at decision points
• •Invoke sub-skills rather than duplicating their logic
• •Sync with base branch before finishing (fetch + check for divergence)
• •Move plan to complete/ after successful finish

Integration

Invokes:

• •gremlins:plan-readiness-review (start phase)
• •gremlins:executing-plans (implement phase)
• •gremlins:implementation-review (audit phase)
• •gremlins:reach-opportunities (reach phase, opt-in)
• •gremlins:finishing-a-development-branch (completion)
• •gremlins:plan-complete (moves plan to complete/)

Prerequisite:

• •gremlins:using-git-worktrees - Creates the worktree first

Assumption:

• •Plan committed to repo before worktree created