autonomous-workflow（自主工作流程）

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

plan.md is the single source of truth. It must be comprehensive enough that a new Claude session can execute from it alone without the original conversation.

DO NOT create artifact files on the main branch.

Step 3: Announce Mode Selection

State your mode selection explicitly:

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

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

Verify installation:

gw --version
gw --help

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

gw init
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

Auto-Trigger Setup (Recommended)

Install the agent and routing rule so Claude auto-triggers on phrases like *"independently"*, *"in isolation"*.

Option A: Global (personal use — works in all projects)

mkdir -p ~/.claude/agents && \
  ln -sf ~/.claude/skills/autonomous-workflow/templates/agent.template.md \
     ~/.claude/agents/autonomous-workflow.md

Then add the routing rule per-project:

mkdir -p .claude/rules && \
  ln -sf ~/.claude/skills/autonomous-workflow/templates/routing-rule.template.md \
     .claude/rules/autonomous-workflow-routing.md

Option B: Project-level (team use — committable to git, customizable)

mkdir -p .claude/agents .claude/rules && \
  ln -sf ~/.claude/skills/autonomous-workflow/templates/agent.template.md \
     .claude/agents/autonomous-workflow.md && \
  ln -sf ~/.claude/skills/autonomous-workflow/templates/routing-rule.template.md \
     .claude/rules/autonomous-workflow-routing.md

To customize the agent for a specific project, copy instead of symlink and edit directly. See routing-rule.template.md and agent.template.md for details.

Quick Reference

Full Mode (4+ files, complex changes)

Lite Mode (1-3 files, simple changes)

Key Principles

1. Detect workflow mode FIRST: Determine Full vs Lite before any other action.
2. plan.md is the single source of truth: Must be comprehensive enough for a new session to execute alone.
3. Always validate first (Phase 0): Never skip directly to implementation.
4. Always create worktree (Phase 2): Isolation is mandatory.
5. Verify after editing: Run fast checks after each change, full suite before PR.
6. Iterate until correct: No artificial iteration limits (Ralph Wiggum pattern).
7. CREATE walkthrough.md AND SHOW IT at Phase 6: MANDATORY for Full Mode.
8. Stop and ask when blocked: Don't guess on ambiguity.

Artifact System

The workflow produces two artifacts in .gw/{branch-name}/:

Files are gitignored and grouped by branch for easy browsing.

All timestamps in artifact frontmatter MUST use full ISO 8601 with time: YYYY-MM-DDTHH:MM:SSZ (e.g. 2026-03-07T14:30:00Z).

Workflow Flow

Phase 0: Validation <- MANDATORY
    | (user confirms)
Phase 1: Planning (prepare content IN CONVERSATION, no files yet)
    | (plan validated)
Phase 2: Worktree Setup <- MANDATORY
    | Full Mode: CREATE & POPULATE plan.md INSIDE worktree
    | (worktree created, plan.md populated)
Phase 3: Implementation
    | Verify after editing. Update Progress Log at milestones.
    | (code complete)
Phase 4: Testing <- iterate until passing
    | (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 - Artifact pattern
• Ralph Wiggum AI Coding Loops - Iteration pattern
• Addy Osmani's LLM Workflow - Fast feedback loops
• Claude Code Worktree Support - Best practices