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: Plan Artifact Content (Full Mode ONLY)
For Full Mode, you will need these artifacts. Do NOT create the files yet — they must be created inside the worktree after Phase 2, not on the main branch.
| File | Purpose | Created | When to Update |
| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| task.md | Dynamic checklist, decisions, blockers | After Phase 2 | At milestones (every 2-3 files) |
| plan.md | Comprehensive implementation strategy (ALL discussion context, decisions, requirements, technical design) | After Phase 2 | After Phase 1 analysis (must be verbose — captures full Phase 0 discussion) |
| walkthrough.md | Final summary for PR | Phase 6 | Phase 6 (MANDATORY) |
⚠️ Artifact files are created and populated inside the worktree at the end of Phase 2. Phase 1 planning happens in conversation.
⛔ DO NOT create artifact files on the main branch.
⚠️ 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."
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
| 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, detect mode |
| 1. Planning | Analyze codebase, PREPARE plan content in conversation (ALL sections, verbose — capture every detail from Phase 0 discussion) |
| 2. Worktree | gw add feat/feature-name, then CREATE & POPULATE .gw/{branch}/task.md and plan.md inside worktree |
| 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 AFTER worktree setup (Full Mode):
.gw/{branch}/task.mdandplan.mdare MANDATORY — created inside the worktree, never on main. - 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 2 (end) | Dynamic checklist, decisions, discoveries |
| Plan | plan.md | Phase 2 (end) | Implementation strategy |
| Walkthrough | walkthrough.md | Phase 6 | Final summary for PR |
Files are gitignored and grouped by branch for easy browsing.
⚠️ All timestamps in artifact frontmatter (created:), status fields (Last Updated:), and metadata.json MUST use full ISO 8601 with time: YYYY-MM-DDTHH:MM:SSZ (e.g. 2026-03-07T14:30:00Z). Never use date-only formats.
⚠️ CRITICAL: Artifact Update Requirements
| Artifact | Update Frequency | Blocking Gate |
| ---------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
| plan.md | Created & populated at end of Phase 2 | ⛔ Must be COMPREHENSIVELY POPULATED (all sections filled, verbose) before Phase 3 |
| 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 │
│ ⚠️ Do NOT create artifact files yet │
└─────────────────────────────────────────────────────┘
↓
Phase 0: Validation ← MANDATORY
↓ (user confirms)
Phase 1: Planning (prepare content IN CONVERSATION, no files yet)
↓ (plan validated)
Phase 2: Worktree Setup ← MANDATORY (with smart detection)
⛔ Full Mode: CREATE & POPULATE artifacts INSIDE worktree
↓ (worktree created, artifacts populated)
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