Autonomous Workflow

Execute complete feature development cycles autonomously—from task intake through tested PR delivery—using isolated Git worktrees.

⚠️ CRITICAL: Before Starting ANY Work

You MUST complete these steps IN ORDER before writing any code:

Step 1: Detect Workflow Mode (MANDATORY)

Analyze the task scope to determine the workflow mode:

When in doubt, choose Full Mode.

Step 2: Create Artifact Files (Full Mode ONLY)

For Full Mode, you MUST create these files in .gw/{branch-name}/ BEFORE Phase 1 Planning begins:

# Create artifact directory
mkdir -p .gw/{branch-name}

# Create required files
touch .gw/{branch-name}/task.md
touch .gw/{branch-name}/plan.md

⛔ DO NOT proceed to implementation without these files for Full Mode tasks.

⚠️ ARTIFACT UPDATE TRIGGERS (Full Mode)

Update .gw/{branch}/task.md at these key points:

Batch updates preferred: Update after completing a logical unit of work rather than after every single file. This reduces overhead while maintaining visibility.

Step 3: Announce Mode Selection

State your mode selection explicitly:

"This is a Full Mode task (affects 5+ files). Creating .gw/{branch-name}/ artifacts now."

or

"This is a Lite Mode task (2 files, simple fix). Proceeding without artifacts."

Prerequisites: gw CLI Installation

Before Phase 2 (Worktree Setup), verify the gw CLI is installed:

which gw

If gw is NOT installed

STOP and prompt the user to install gw. The workflow cannot proceed without it.

Installation options (present to user):

# Via npm (recommended)
npm install -g @gw-tools/gw

# Via Homebrew (macOS)
brew install mthines/gw-tools/gw

# Via pnpm
pnpm add -g @gw-tools/gw

After installation, set up shell integration:

# For zsh (add to ~/.zshrc)
echo 'eval "$(gw install-shell)"' >> ~/.zshrc
source ~/.zshrc

# For bash (add to ~/.bashrc)
echo 'eval "$(gw install-shell)"' >> ~/.bashrc
source ~/.bashrc

# For fish (add to ~/.config/fish/config.fish)
echo 'gw install-shell | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Verify installation:

gw --version
gw --help

Then initialize gw in the repository (if not already done):

# For existing repositories
gw init

# With auto-copy files (recommended)
gw init --auto-copy-files .env,secrets/ --post-checkout "npm install"

Once gw is installed and configured, resume the workflow from Phase 2.

Rules

Templates

Structured templates for consistent artifact generation:

Quick Reference

Full Mode (4+ files, complex changes)

Lite Mode (1-3 files, simple changes)

Workflow Modes

Full Mode: Creates .gw/{branch}/ artifacts for progress tracking and context recovery.

Lite Mode: Faster execution without artifact overhead. Still uses worktree isolation.

Key Principles

1. Detect workflow mode FIRST: Determine Full vs Lite before any other action.
2. Create artifacts BEFORE planning (Full Mode): .gw/{branch}/task.md and plan.md are MANDATORY.
3. Always validate first (Phase 0): Never skip directly to implementation.
4. Always create worktree (Phase 2): Isolation is mandatory (can skip for trivial fixes).
5. Update task.md at milestones: Every 2-3 files or at logical checkpoints (not every file).
6. Smart worktree detection: Check if current worktree matches task before creating new.
7. Iterate until correct: No artificial iteration limits (Ralph Wiggum pattern).
8. Fast feedback loops: Run tests frequently, fix failures immediately.
9. Self-validate continuously: Check work at every step.
10. ⛔ CREATE walkthrough.md AND SHOW IT at Phase 6: This is MANDATORY for Full Mode.
11. Stop and ask when blocked: Don't guess on ambiguity.

Artifact System

Inspired by Google Antigravity, this workflow produces three artifacts in .gw/{branch-name}/:

Files are gitignored and grouped by branch for easy browsing.

⚠️ CRITICAL: Artifact Update Requirements

Workflow Flow

┌─────────────────────────────────────────────────────┐
│  MODE DETECTION ← MANDATORY FIRST STEP              │
│  Analyze task → Choose Full (4+ files) or Lite      │
│  Full Mode: Create .gw/{branch}/ artifacts NOW      │
└─────────────────────────────────────────────────────┘
    ↓
Phase 0: Validation ← MANDATORY
    ↓ (user confirms)
Phase 1: Planning
    ⛔ Full Mode: POPULATE plan.md + task.md (not empty!)
    ↓ (plan validated)
Phase 2: Worktree Setup ← MANDATORY (with smart detection)
    ↓ (worktree created)
Phase 3: Implementation
    📝 Full Mode: UPDATE task.md at milestones (every 2-3 files)
    ↓ (code complete)
Phase 4: Testing ← iterate until passing
    📝 Full Mode: LOG each test iteration in task.md
    ↓ (all tests pass)
Phase 5: Documentation
    ↓ (docs complete)
Phase 6: PR Creation
    ⛔ Full Mode: CREATE walkthrough.md + SHOW to user
    ↓ (draft PR delivered)
Phase 7: Cleanup (optional)

Smart Worktree Detection

Before creating a new worktree, the workflow checks if the current context matches the task:

Fast Iteration Loop (Phase 4)

Based on the Ralph Wiggum pattern:

while not all_tests_pass:
    1. Run tests
    2. If pass: done
    3. If fail: analyze → fix → commit → continue
    4. Safety: warn at 10 iterations, stop at 20

Troubleshooting Quick Reference

Related Skills

• git-worktree-workflows - Worktree fundamentals
• gw-config-management - Configure auto-copy and hooks

References

Detailed examples and scenarios (loaded on-demand):

• Complete Workflow Example
• Error Recovery Scenarios
• Iterative Refinement Example

Research Sources

• Google Antigravity Artifacts - Three-artifact pattern
• Ralph Wiggum AI Coding Loops - Iteration pattern
• Addy Osmani's LLM Workflow - Fast feedback loops
• Claude Code Worktree Support - Best practices