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:

bash

# 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	Throughout implementation
`plan.md`	Implementation strategy, file list	After Phase 1 analysis
`walkthrough.md`	Final summary for PR	Phase 6 only

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

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:

bash

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

bash

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

bash

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

bash

gw --version
gw --help

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

bash

# 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, create `.gw/{branch}/task.md` and `plan.md`
2. Worktree	`gw add feat/feature-name`
3. Implementation	Code in worktree, update `task.md` on changes
4. Testing	`npm test` , iterate until all pass, log in `task.md`
5. Documentation	Update README, CHANGELOG
6. PR Creation	Generate `walkthrough.md` , `gh pr create --draft`
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).
Track progress with artifacts: Update
```
.gw/{branch}/task.md
```
as you work.
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.
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.

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: write to plan.md, Lite: mental plan)
    ↓ (plan validated)
Phase 2: Worktree Setup ← MANDATORY (with smart detection)
    ↓ (worktree created)
Phase 3: Implementation (Full: update task.md, Lite: just code)
    ↓ (code complete)
Phase 4: Testing ← iterate until passing
    ↓ (all tests pass)
Phase 5: Documentation
    ↓ (docs complete)
Phase 6: PR Creation (Full: generate walkthrough.md)
    ↓ (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

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

autonomous-workflow

NPX Install

Tags

SKILL.md Content

Autonomous Workflow

⚠️ CRITICAL: Before Starting ANY Work

Step 1: Detect Workflow Mode (MANDATORY)

Step 2: Create Artifact Files (Full Mode ONLY)

Step 3: Announce Mode Selection

Prerequisites: gw CLI Installation

If gw is NOT installed

Rules

Templates

Quick Reference

Full Mode (4+ files, complex changes)

Lite Mode (1-3 files, simple changes)

Workflow Modes

Key Principles

Artifact System

Workflow Flow

Smart Worktree Detection

Fast Iteration Loop (Phase 4)

Troubleshooting Quick Reference

Related Skills

References

Research Sources