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:

Mode	Criteria	Artifacts Required
Full	4+ files OR complex/architectural	YES - MANDATORY
Lite	1-3 files AND simple/straightforward	No

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

File	Purpose	When to Update
`task.md`	Dynamic checklist, decisions, blockers	At milestones (every 2-3 files)
`plan.md`	Implementation strategy, file list	After Phase 1 analysis
`walkthrough.md`	Final summary for PR	Phase 6 (MANDATORY)

⛔ 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:

Trigger	Update Action
Logical milestone (2-3 files)	Batch update Completed items
Phase transition	Update Status section, move items
Decision made	Add row to Decisions Log
Test iteration (fail→fix→rerun)	Log result in Test Iterations
Blocker encountered	Update Blockers section

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."

"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

Rule	Description
overview	HIGH - Workflow phases, when to use, expected outcomes
smart-worktree-detection	CRITICAL - Fuzzy match task to current worktree, prompt to continue or create new
phase-0-validation	CRITICAL - MANDATORY - Validate requirements before any work
phase-1-planning	HIGH - Deep codebase analysis and implementation planning
phase-2-worktree	CRITICAL - MANDATORY - Create isolated worktree with `gw add`
phase-3-implementation	HIGH - Incremental implementation with continuous validation
phase-4-testing	CRITICAL - Fast iteration loop until tests pass (Ralph Wiggum pattern)
phase-5-documentation	MEDIUM - Update README, CHANGELOG, API docs
phase-6-pr-creation	HIGH - Create draft PR, deliver results
phase-7-cleanup	LOW - Optional worktree removal after merge
decision-framework	HIGH - Branch naming, test strategy, iteration decisions
error-recovery	HIGH - Recovery procedures for common errors
safety-guardrails	CRITICAL - Validation checkpoints, resource limits, rollback
parallel-coordination	HIGH - Multi-agent coordination, handoff protocol
artifacts-overview	HIGH - Three-artifact pattern (Task, Plan, Walkthrough), file locations
task-tracking	HIGH - Dynamic task updates throughout workflow
walkthrough-generation	MEDIUM - Final summary generation at Phase 6

Templates

Structured templates for consistent artifact generation:

Template	Purpose
task.template.md	Dynamic task checklist
plan.template.md	Implementation plan
walkthrough.template.md	Final summary

Quick Reference

Full Mode (4+ files, complex changes)

Phase	Command/Action
0. Validation	Ask clarifying questions, get user confirmation
1. Planning	Analyze codebase, POPULATE `.gw/{branch}/task.md` and `plan.md`
2. Worktree	`gw add feat/feature-name`
3. Implementation	Code in worktree, UPDATE `task.md` at milestones
4. Testing	`npm test`, LOG each iteration in `task.md`
5. Documentation	Update README, CHANGELOG
6. PR Creation	CREATE `walkthrough.md`, `gh pr create --draft`, SHOW walkthrough to user
7. Cleanup	`gw remove feat/feature-name` (after merge)

Lite Mode (1-3 files, simple changes)

Phase	Command/Action
0. Validation	Quick clarification if needed
1. Planning	Brief mental plan (no artifact files)
2. Worktree	`gw add fix/bug-name` (optional for trivial)
3. Implementation	Code directly, commit when done
4. Testing	`npm test`, fix any failures
5. PR Creation	`gh pr create --draft`

Workflow Modes

Mode	Files Changed	Artifacts	Use When
Lite	1-3 files	No	Simple fixes, small enhancements
Full	4+ files	Yes	Features, refactors, complex changes

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

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

Artifact	File	Created	Purpose
Task	`task.md`	Phase 1	Dynamic checklist, decisions, discoveries
Plan	`plan.md`	Phase 1	Implementation strategy
Walkthrough	`walkthrough.md`	Phase 6	Final summary for PR

Files are gitignored and grouped by branch for easy browsing.

⚠️ CRITICAL: Artifact Update Requirements

Artifact	Update Frequency	Blocking Gate
`plan.md`	Once in Phase 1	⛔ Must be POPULATED (not empty) before Phase 2
`task.md`	At milestones (every 2-3 files)	⛔ Must reflect completed work at phase transitions
`walkthrough.md`	Once in Phase 6	⛔ Must be CREATED AND SHOWN to user before completion

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:

Scenario	Action
On main/master	Always create new worktree
Worktree name matches task keywords	Prompt user to continue or create new
No keyword match	Create new worktree

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

Issue	Check	Recovery
Wrong worktree	`gw list`, `pwd`	`gw cd <correct-branch>`
gw command not found	`which gw`	`npm install -g @gw-tools/gw`
Secrets missing	`cat .gw/config.json`	`gw sync <branch> .env`
Agent stuck in loop	`task.md` iteration history	Try alternative approach, ask user
Tests keep failing	`task.md` test results	Focus on ONE failure, escalate at 7+
Agent hallucinated cmd	Error message	See error-recovery
plan.md empty	`cat .gw/{branch}/plan.md`	STOP, populate plan.md before proceeding
task.md not updated	`cat .gw/{branch}/task.md`	Update immediately with all completed work
walkthrough.md missing	`ls .gw/{branch}/`	Create before announcing completion

Related Skills

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

References

Detailed examples and scenarios (loaded on-demand):

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

autonomous-workflow