Autonomous Workflow - Complete Feature Delivery

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

•Workflow Overview
•Phase 0: Validation & Questions (MANDATORY)
•Phase 1: Task Intake & Planning
•Phase 2: Worktree Setup
•Phase 3: Implementation
•Phase 4: Testing & Iteration
•Phase 5: Documentation
•Phase 6: PR Creation & Delivery
•Phase 7: Cleanup (Optional)
•Decision Framework
•Error Recovery Procedures
•Safety Guardrails

1. Workflow Overview

What This Skill Does

This skill enables autonomous execution of complete feature development workflows:

•Validates requirements through upfront questions
•Plans implementation based on deep codebase analysis
•Creates isolated environment using gw add
•Implements features following existing patterns
•Tests iteratively until all tests pass
•Documents changes in relevant files
•Delivers draft PR ready for human review

When to Use This Skill

Use this skill when:

•User requests autonomous feature implementation
•Task has clear deliverable (feature, fix, refactor)
•Project uses gw-tools for worktree management
•Tests are available to validate correctness

Do NOT use this skill when:

•User wants to code alongside you (use interactive mode)
•Task is exploratory research without clear deliverable
•Project doesn't use Git or worktrees
•Changes affect critical production code without tests

Expected Outcomes

Successful execution produces:

•✅ Isolated worktree with complete implementation
•✅ All tests passing (existing + new if applicable)
•✅ Documentation updated (README, CHANGELOG, API docs)
•✅ Draft PR with comprehensive description
•✅ Clean commit history with conventional commits

If unable to complete:

•⚠️ Partial implementation committed with notes
•⚠️ Clear explanation of blockers encountered
•⚠️ Recommendations for next steps

Autonomy Model

This workflow operates with high autonomy after validation:

•Phase 0 (Validation): Interactive - ask clarifying questions
•Phase 1-6: Autonomous - execute with continuous self-validation
•Decision points: Use decision framework, iterate until correct
•Blockers: Report and deliver partial work with notes

2. Phase 0: Validation & Questions (MANDATORY)

🔴 CRITICAL: ALWAYS START HERE

This phase is MANDATORY. Never skip directly to implementation.

Objectives

•Understand requirements completely - No assumptions
•Identify ambiguities - Surface edge cases early
•Validate scope - Confirm what's in/out of scope
•Clarify acceptance criteria - Define "done"
•Get explicit confirmation - User approves understanding

Procedure

markdown

## Step 1: Parse User Request

Read the user's request carefully. Identify:
- Primary feature/fix being requested
- Mentioned technologies, files, or patterns
- Implied requirements (what's assumed but not stated)
- Missing information (what's unclear)

## Step 2: Analyze Codebase Context

Before asking questions, understand the project:
- Project structure (monorepo? single app?)
- Technology stack (framework, language, tools)
- Testing setup (unit, integration, e2e?)
- Documentation patterns (where docs live)
- Existing similar features (patterns to follow)

Use tools: nx_workspace, nx_project_details, Read, Glob, Grep

## Step 3: Formulate Clarifying Questions

Ask about:

**Requirements clarity:**
- "Should X feature also handle Y scenario?"
- "What should happen when Z edge case occurs?"

**Scope boundaries:**
- "Should this include tests/docs/migrations?"
- "Are we updating existing feature or adding new?"

**Technical decisions:**
- "Prefer approach A (simpler) or B (more flexible)?"
- "Follow pattern X from file.ts or pattern Y from other.ts?"

**Acceptance criteria:**
- "How will we know this is complete?"
- "What tests should pass?"

## Step 4: Present Understanding for Validation

Summarize your understanding:

"Based on your request, I understand:
1. Goal: [primary objective]
2. Scope: [what's included/excluded]
3. Approach: [technical approach]
4. Tests: [validation strategy]
5. Docs: [documentation updates]

Questions before proceeding:
- [Question 1]
- [Question 2]
- [Question 3]

Does this match your intent?"

## Step 5: Get Explicit Confirmation

Wait for user response. Do NOT proceed until:
- ✅ All questions answered
- ✅ Understanding validated
- ✅ Scope confirmed
- ✅ User explicitly says "proceed" or equivalent

If user clarifies/corrects:
- Update your understanding
- Re-validate if significant changes
- Confirm again before proceeding

Example: Validation in Action

markdown

User: "Add dark mode toggle to the app"

Agent (Phase 0):
"Let me understand this requirement before implementation.

Current analysis:
- Project: Next.js app with Tailwind CSS
- Existing: Light theme only
- Location: No theme infrastructure found

Clarifying questions:

1. **Scope**: Should dark mode apply globally or per-page?
2. **Persistence**: Save user preference (localStorage/cookie)?
3. **Default**: System preference or manual toggle?
4. **Components**: All pages or specific sections?
5. **Approach**: Prefer Tailwind dark: classes or CSS variables?
6. **Toggle UI**: Where should the toggle appear (navbar/settings)?

My proposed approach:
- Add theme context provider
- Use Tailwind dark: classes
- Save preference to localStorage
- System preference as default
- Toggle in navbar

Does this match your vision? Any preferences on the questions above?"

[Wait for user confirmation before proceeding to Phase 1]

Validation Checklist

Before leaving Phase 0:

• User request fully understood
• All ambiguities clarified
• Scope explicitly confirmed
• Acceptance criteria defined
• Technical approach validated
• User gave explicit "proceed" signal

If any checkbox is unchecked, DO NOT proceed to Phase 1.

3. Phase 1: Task Intake & Planning

Objectives

•Deep codebase analysis - Understand existing patterns thoroughly
•Implementation strategy - Plan detailed approach
•File identification - Know exactly what to change
•Self-validation - Review plan against requirements

Procedure

markdown

## Step 1: Analyze Codebase (Deep Dive)

### Project Structure
- Identify relevant directories/modules
- Map dependencies between components
- Locate configuration files

Tools: nx_workspace, nx_project_details, Glob

### Existing Patterns
- Find similar features already implemented
- Study code style, naming conventions
- Understand error handling patterns
- Review testing patterns

Tools: Grep (search for patterns), Read (study implementations)

### Technology Stack
- Framework version and features
- Build tools and configuration
- Testing framework and conventions
- Documentation format

### Dependencies
- Required packages already installed?
- Need to add new dependencies?
- Version compatibility considerations

## Step 2: Create Implementation Plan

Document your plan:

**Changes Required:**
1. File: `path/to/file1.ts`
   - Add: [specific additions]
   - Modify: [specific changes]
   - Reason: [why this change]

2. File: `path/to/file2.ts`
   - Add: [specific additions]
   - Reason: [why this change]

3. New file: `path/to/file3.ts`
   - Purpose: [what this does]
   - Exports: [public API]

**Testing Strategy:**
- Unit tests: [what to test]
- Integration tests: [if applicable]
- Manual validation: [if applicable]

**Documentation Updates:**
- README.md: [what to add/change]
- API docs: [if applicable]
- CHANGELOG: [entry to add]

**Risks & Mitigations:**
- Risk: [potential issue]
  Mitigation: [how to handle]

## Step 3: Self-Validation (Review Your Plan)

Ask yourself:

**Completeness:**
- Does this plan achieve all requirements from Phase 0?
- Are edge cases from user questions addressed?
- Is anything missing?

**Correctness:**
- Does this follow existing project patterns?
- Are dependencies and imports correct?
- Will this integrate cleanly?

**Testability:**
- Can this be validated with tests?
- Are test cases comprehensive?

**Maintainability:**
- Is this approach simple enough?
- Does it follow project conventions?
- Will other developers understand this?

## Step 4: Iteration Checkpoint

If self-validation reveals issues:
1. Refine the plan
2. Re-validate
3. Iterate until plan is solid

**Do NOT proceed to Phase 2 until plan is validated.**

## Step 5: Present Plan Summary (Optional)

For complex tasks, briefly summarize plan:

"Implementation plan:
- Modifying 3 files: [list]
- Adding 1 file: [list]
- Tests: [strategy]
- Docs: [updates]

Proceeding with Phase 2: Worktree setup."

Planning Checklist

4. Phase 2: Worktree Setup

Objectives

•Generate appropriate branch name - Follow conventions
•Create isolated worktree - Execute gw add
•Install dependencies - Ensure environment ready
•Validate setup - Confirm everything works

Procedure

markdown

## Step 1: Generate Branch Name

Use decision framework (see Section 10):

**Pattern:** `<type>/<short-description>`

Types:
- `feat/` - New feature
- `fix/` - Bug fix
- `refactor/` - Code restructuring
- `docs/` - Documentation only
- `chore/` - Tooling, dependencies
- `test/` - Adding/fixing tests

Example: `feat/dark-mode-toggle`

## Step 2: Create Worktree

Execute:
```bash
gw add <branch-name>

Validation:

•Command succeeded?
•Worktree appears in gw list?
•Files present in new directory?

If fails, see Error Recovery (Section 11).

Step 3: Navigate to Worktree

bash

gw cd <branch-name>

Validation:

•pwd shows correct directory?
•.git symlink points to correct location?

Step 4: Install Dependencies

Check if dependencies need installation:

•Does package.json exist?
•Is post-add hook configured?

If manual install needed:

bash

npm install
# or
pnpm install
# or
yarn install

Validation:

•node_modules/ directory exists?
•Key dependencies present?
•No installation errors?

Step 5: Verify Environment

Run basic checks:

bash

# TypeScript project
npm run build  # or tsc --noEmit

# Linting
npm run lint

# Tests (quick smoke test)
npm test -- --listTests  # Just list, don't run yet

Validation:

•No immediate errors?
•Build system works?
•Test framework found?

Step 6: Sync Configuration (If Needed)

If project uses autoCopyFiles:

bash

gw sync <branch-name>

Validation:

•.env copied (if configured)?
•Other config files synced?

code


### Setup Checklist

- [ ] Branch name follows conventions
- [ ] Worktree created successfully
- [ ] Dependencies installed
- [ ] Environment builds/compiles
- [ ] Configuration files synced
- [ ] Ready to implement

---

## 5. Phase 3: Implementation

### Objectives

1. **Follow existing patterns** - Consistency with codebase
2. **Implement incrementally** - Small, focused changes
3. **Validate continuously** - Self-check at every step
4. **Commit logically** - Meaningful commit messages

### Procedure

```markdown
## Step 1: Start with Foundation

Implement in logical order:
1. Types/interfaces (if TypeScript)
2. Core logic/functions
3. UI components (if applicable)
4. Integration/glue code
5. Configuration updates

## Step 2: Implement One Change at a Time

For each file change:

### Before Editing:
- Read existing file completely
- Understand current structure
- Identify insertion points
- Note existing patterns

### During Editing:
- Make focused change (one concern)
- Follow existing code style
- Maintain consistent formatting
- Add comments only if logic non-obvious
- Don't over-engineer

### After Editing:
**Immediate validation:**
```bash
# Does it compile?
npm run build  # or tsc --noEmit

# Does it pass linting?
npm run lint -- <file-path>

Self-review questions:

•Does this match existing patterns?
•Is naming consistent with codebase?
•Are imports organized correctly?
•Did I introduce any obvious bugs?
•Is this the simplest solution?

Iterate if needed:

•Validation failed? Fix immediately
•Code feels wrong? Refine before proceeding
•Don't accumulate technical debt

Step 3: Commit Incrementally

After each logical unit of work:

bash

git add <changed-files>
git commit -m "<type>(<scope>): <description>"

Conventional commit format:

•feat(ui): add dark mode toggle button
•feat(theme): implement theme context provider
•test(theme): add theme toggle unit tests
•docs(readme): document dark mode feature

Commit guidelines:

•One logical change per commit
•Clear, descriptive messages
•Reference issues if applicable
•Keep commits atomic (can be reverted independently)

Step 4: Continuous Self-Validation

After every 2-3 files changed:

Checkpoint validation:

bash

# Full build
npm run build

# All lint rules
npm run lint

# Quick test run (if fast)
npm test -- --coverage=false --maxWorkers=1

Self-assessment:

•Is implementation on track?
•Any deviations from plan?
•Need to adjust approach?

Iteration decision: If validation reveals issues:

•Stop and analyze root cause
•Fix the underlying problem
•Re-validate
•Continue only when solid

Step 5: Integration Check

After all implementation changes:

Final integration validation:

•All files compile together?
•No TypeScript/lint errors?
•Imports resolve correctly?
•No circular dependencies?

Manual testing (if applicable):

•Start dev server
•Test feature manually
•Try edge cases from Phase 0
•Verify user requirements met

Step 6: Pre-Testing Commit

Commit all implementation work:

bash

git add .
git commit -m "feat(scope): implement <feature-name>

- Detail 1
- Detail 2
- Detail 3"

Now ready for formal testing (Phase 4).

code


### Implementation Checklist

- [ ] All planned files modified
- [ ] Code follows existing patterns
- [ ] Builds/compiles successfully
- [ ] Linting passes
- [ ] Commits are logical and clear
- [ ] Self-reviewed all changes
- [ ] Ready for testing

---

## 6. Phase 4: Testing & Iteration

### Objectives

1. **Run comprehensive tests** - Validate correctness
2. **Iterate aggressively** - Fix failures until passing
3. **Add new tests** - Cover new functionality
4. **Validate thoroughly** - Ensure quality

### Procedure

```markdown
## Step 1: Determine Test Strategy

Based on changes:

**Code changes require:**
- Unit tests for new functions/components
- Integration tests if multiple modules interact
- Regression tests for bug fixes

**UI changes require:**
- Component tests
- Visual regression tests (if available)
- Manual browser testing

**API changes require:**
- Endpoint tests
- Contract tests
- Error case coverage

## Step 2: Run Existing Tests

```bash
# Run full test suite
npm test

# Or specific tests if large codebase
npm test -- --testPathPattern="relevant"

Expected outcomes:

•✅ All existing tests pass (no regressions)
•❌ Some tests fail (expected if changing behavior)

Step 3: Analyze Test Failures

For each failure:

Understand the Failure:

•Read error message completely
•Identify which assertion failed
•Understand what was expected vs actual
•Trace back to root cause

Categorize:

•Expected failure - Behavior intentionally changed → Update test to match new behavior
•Regression - Broke existing functionality → Fix implementation to preserve behavior
•Test infrastructure - Test setup issue → Fix test configuration

Prioritize:

•Critical failures first (core functionality)
•Edge cases later
•Flaky tests last (may be test issue)

Step 4: Iterate Until Tests Pass

Iteration loop (no hard limit):

Iteration 1:

•Fix most obvious issues
•Re-run tests
•Validate: Did failures decrease?

Iteration 2:

If still failing:

•Re-analyze root cause (was first fix superficial?)
•Try different approach
•Re-run tests
•Validate: Getting closer?

Iteration 3+:

Keep iterating:

•Consider alternative implementation
•Review original plan (was approach wrong?)
•Simplify if over-complicated
•Ask: What would make tests pass?

Continue until:

•✅ All tests passing, OR
•⚠️ Identified blocker requiring user input

Self-validation questions:

•Are tests actually validating requirements?
•Are we testing the right things?
•Do tests cover edge cases from Phase 0?

Step 5: Add New Tests (If Applicable)

If new functionality added:

typescript

// Example: Testing new feature
describe('DarkModeToggle', () => {
  it('should toggle theme when clicked', () => {
    // Test new functionality
  });

  it('should persist preference to localStorage', () => {
    // Test persistence
  });

  it('should respect system preference on first load', () => {
    // Test edge case
  });
});

New test requirements:

•Cover main functionality
•Cover edge cases discussed in Phase 0
•Follow existing test patterns
•Use same testing utilities

Validate new tests:

bash

# Run only new tests
npm test -- --testPathPattern="DarkModeToggle"

Self-check:

•Do new tests pass?
•Do they actually validate the feature?
•Are they maintainable?

Step 6: Manual Validation (If Applicable)

For UI changes, use agent-browser:

markdown

Objective: Validate dark mode toggle works correctly

Steps:
1. Start dev server (npm run dev)
2. Navigate to app (http://localhost:3000)
3. Locate dark mode toggle
4. Click toggle → verify theme changes
5. Refresh page → verify preference persisted
6. Test edge cases:
   - Different pages
   - Different components
   - System preference changes

Step 7: Final Validation

All tests passing?

Final checkpoint:

bash

# Clean test run
npm run test -- --coverage

# Check coverage (if requirements specified)
# Ensure new code has adequate coverage

Self-assessment:

•All requirements from Phase 0 validated?
•Edge cases tested?
•No regressions introduced?
•Tests are reliable (not flaky)?

Step 8: Commit Test Changes

bash

git add <test-files>
git commit -m "test(scope): add comprehensive tests for <feature>

- Unit tests for X
- Integration tests for Y
- Edge case coverage for Z"

code


### Testing Checklist

- [ ] Test strategy determined
- [ ] All existing tests pass
- [ ] Test failures analyzed and fixed
- [ ] New tests added (if applicable)
- [ ] Manual validation completed (if UI)
- [ ] Coverage adequate
- [ ] All requirements validated
- [ ] Ready for documentation

---

## 7. Phase 5: Documentation

### Objectives

1. **Identify documentation scope** - What needs updating
2. **Update relevant docs** - README, API docs, CHANGELOG
3. **Self-validate clarity** - Read as new user would
4. **Maintain style consistency** - Follow existing patterns

### Procedure

```markdown
## Step 1: Identify Documentation Needs

Based on changes:

**User-facing features:**
- README.md (usage examples)
- User guides
- Screenshots/demos

**API changes:**
- API documentation
- JSDoc/TSDoc comments
- OpenAPI/Swagger specs

**Configuration changes:**
- Config file documentation
- Environment variable docs
- Setup instructions

**Breaking changes:**
- CHANGELOG.md (highlight breaking changes)
- Migration guide

**All changes:**
- CHANGELOG.md entry

## Step 2: Update README (If Applicable)

Add usage examples:

```markdown
### Dark Mode

The app now supports dark mode! Toggle between light and dark themes:

#### Using the UI
Click the theme toggle in the navigation bar.

#### Programmatically
\```typescript
import { useTheme } from '@/contexts/ThemeContext';

function MyComponent() {
  const { theme, setTheme } = useTheme();

  // Toggle theme
  setTheme(theme === 'light' ? 'dark' : 'light');
}
\```

#### Default Behavior
- Respects system preference on first load
- Persists user preference to localStorage
- Falls back to light mode if preference unavailable

Validation:

•Read example as new user
•Is it clear how to use the feature?
•Are code examples correct?
•Is it easy to find?

Step 3: Update API Documentation (If Applicable)

Document new APIs:

typescript

/**
 * Theme context providing theme state and controls.
 *
 * @example
 * \```tsx
 * import { useTheme } from '@/contexts/ThemeContext';
 *
 * function MyComponent() {
 *   const { theme, setTheme } = useTheme();
 *   return <button onClick={() => setTheme('dark')}>Dark Mode</button>;
 * }
 * \```
 */
export function useTheme(): ThemeContextValue {
  // ...
}

Validation:

•Are all public APIs documented?
•Are examples realistic?
•Is return type clear?

Step 4: Update CHANGELOG

Add entry following project convention:

markdown

## [Unreleased]

### Added
- Dark mode toggle in navigation bar (#123)
  - Respects system preference
  - Persists user choice to localStorage
  - Applies theme globally

### Changed
- Theme context now exported from `@/contexts/ThemeContext`

### Fixed
- N/A

Validation:

•Entry describes user-facing changes?
•Includes relevant issue/PR numbers?
•Follows existing CHANGELOG format?

Step 5: Update Other Documentation

Check for other docs needing updates:

•Configuration guides
•Architecture docs
•Team runbooks
•Troubleshooting guides

Step 6: Self-Validation (Read as New User)

Critical: Read your own documentation with fresh eyes:

Clarity check:

•Can I understand this without context?
•Are examples self-contained?
•Is technical jargon explained?

Completeness check:

•Are all new features documented?
•Are edge cases explained?
•Are limitations mentioned?

Accuracy check:

•Do code examples actually work?
•Are paths/names correct?
•Is version info accurate?

Iteration if needed:

•Something confusing? Rewrite it
•Example unclear? Add more context
•Important detail missing? Add it

Step 7: Commit Documentation

bash

git add README.md CHANGELOG.md docs/
git commit -m "docs(feature): document dark mode toggle

- Add usage examples to README
- Update CHANGELOG with new feature
- Document theme context API"

code


### Documentation Checklist

- [ ] Documentation scope identified
- [ ] README updated (if applicable)
- [ ] API docs updated (if applicable)
- [ ] CHANGELOG entry added
- [ ] Code examples tested
- [ ] Self-validated for clarity
- [ ] Style consistent with project
- [ ] Ready for PR creation

---

## 8. Phase 6: PR Creation & Delivery

### Objectives

1. **Pre-flight validation** - Ensure everything ready
2. **Push to remote** - Backup work
3. **Generate PR description** - Comprehensive summary
4. **Create draft PR** - Ready for human review
5. **Report completion** - Deliver results to user

### Procedure

```markdown
## Step 1: Pre-Flight Validation

Final checks before delivery:

**All changes committed?**
```bash
git status  # Should show "nothing to commit, working tree clean"

All tests passing?

bash

npm test  # Full test suite

Builds successfully?

bash

npm run build  # Production build

Linting clean?

bash

npm run lint  # All lint rules

Documentation complete?

•README updated? ✓
•CHANGELOG updated? ✓
•API docs updated? ✓

If ANY check fails:

•Stop immediately
•Fix the issue
•Re-validate
•Only proceed when everything passes

Step 2: Push to Remote

bash

# Push branch to remote
git push -u origin <branch-name>

Validation:

•Push succeeded?
•Branch visible on GitHub/GitLab?

Step 3: Generate PR Description

Create comprehensive description:

markdown

## Summary
[High-level overview of what this PR does]

## Changes
- [User-facing change 1]
- [User-facing change 2]
- [Technical change 3]

## Implementation Details
- Modified `file1.ts`: [what and why]
- Added `file2.ts`: [purpose]
- Updated `docs/`: [documentation changes]

## Testing
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual testing completed
- [x] Edge cases validated

## Test Coverage
[Coverage stats if available]

## Screenshots (if UI changes)
[Attach screenshots or request user to add]

## Breaking Changes
[None / List breaking changes and migration path]

## Related Issues
Closes #[issue-number]

Self-review:

•Does this explain the PR clearly?
•Would a reviewer understand the context?
•Are all changes justified?

Step 4: Create Draft PR

Use GitHub CLI:

bash

gh pr create \
  --draft \
  --title "<type>(<scope>): <description>" \
  --body "$(cat <<'EOF'
[PR description from Step 3]
EOF
)"

Example:

bash

gh pr create \
  --draft \
  --title "feat(ui): add dark mode toggle" \
  --body "$(cat <<'EOF'
## Summary
Implements dark mode toggle with theme persistence and system preference support.

## Changes
- Added theme context provider
- Created dark mode toggle component
- Implemented localStorage persistence
- Added comprehensive tests
- Updated documentation

## Implementation Details
- `src/contexts/ThemeContext.tsx`: Theme state management
- `src/components/ThemeToggle.tsx`: Toggle UI component
- `tailwind.config.js`: Dark mode configuration
- Tests: Full coverage of theme logic

## Testing
- [x] 15 new unit tests (100% coverage)
- [x] Manual testing in Chrome, Firefox, Safari
- [x] System preference detection validated
- [x] Persistence across page reloads confirmed

## Screenshots
[Will add in PR review]
EOF
)"

Validation:

•PR created successfully?
•Shows as draft?
•Description rendered correctly?

Step 5: Report Completion to User

Deliver results:

markdown

✅ **Feature implementation complete!**

**Delivered:**
- Branch: `feat/dark-mode-toggle`
- Worktree: `/path/to/worktree`
- Draft PR: https://github.com/user/repo/pull/123

**Summary:**
- Implemented dark mode toggle with theme persistence
- All tests passing (15 new tests, 100% coverage)
- Documentation updated (README + CHANGELOG)
- Ready for your review

**Next steps:**
1. Review the draft PR
2. Add screenshots if desired
3. Mark as ready for review when satisfied
4. Merge when approved

**Worktree cleanup:**
Run `gw remove feat/dark-mode-toggle` after PR is merged.

Step 6: Preserve Worktree

Do NOT remove worktree yet - user may want to:

•Review changes locally
•Make adjustments
•Test manually
•Add screenshots

Worktree cleanup happens in Phase 7 (optional).

code


### Delivery Checklist

- [ ] Pre-flight validation passed
- [ ] All tests passing
- [ ] Branch pushed to remote
- [ ] PR description comprehensive
- [ ] Draft PR created
- [ ] PR link delivered to user
- [ ] Worktree preserved for review
- [ ] Workflow complete!

---

## 9. Phase 7: Cleanup (Optional)

### When to Use This Phase

**Run cleanup when:**
- PR has been merged
- PR has been closed/abandoned
- User explicitly requests cleanup
- Need to reclaim disk space

**Do NOT cleanup if:**
- PR still under review
- User hasn't reviewed changes yet
- Might need to iterate on PR

### Procedure

```markdown
## Step 1: Check PR Status

```bash
gh pr view <pr-number> --json state,mergedAt

Safe to cleanup if:

•State: MERGED
•State: CLOSED (and user confirms)

NOT safe if:

•State: OPEN
•User hasn't reviewed yet

Step 2: Confirm with User (If Uncertain)

"The PR for <feature> is <state>. Should I remove the worktree to clean up disk space?"

Wait for confirmation.

Step 3: Remove Worktree

bash

# Safe removal (ensures committed/pushed)
gw remove <branch-name>

Validation:

•Worktree removed from gw list?
•Directory deleted?
•Git administrative cleanup done?

Step 4: Navigate to Main

bash

gw cd main

Validation:

•In main worktree now?
•Can continue other work?

Step 5: Report Cleanup

"✅ Worktree cleaned up. Disk space reclaimed: ~X MB"

code


### Cleanup Checklist

- [ ] PR status checked
- [ ] Safe to remove worktree
- [ ] Worktree removed successfully
- [ ] Navigated to main
- [ ] User notified

---

## 10. Decision Framework

### Branch Naming Decisions

**Decision tree:**

Is this a new feature? ├─ Yes → feat/<feature-name> └─ No ↓

Is this fixing a bug? ├─ Yes → fix/<bug-description> └─ No ↓

Is this refactoring existing code? ├─ Yes → refactor/<scope> └─ No ↓

Is this documentation only? ├─ Yes → docs/<doc-name> └─ No ↓

Is this testing only? ├─ Yes → test/<test-scope> └─ No ↓

Is this tooling/dependencies? └─ Yes → chore/<tool-name>

code


**Examples:**
- `feat/dark-mode-toggle`
- `fix/login-validation-error`
- `refactor/api-client-structure`
- `docs/api-reference-update`
- `test/user-service-coverage`
- `chore/upgrade-typescript-5`

### Test Strategy Selection

**Decision tree:**

What changed?

Pure functions/utilities? → Unit tests (Jest/Vitest) → Coverage target: >80%

React components? → Component tests (Testing Library) → Test: rendering, interactions, props

API endpoints? → Integration tests (supertest) → Test: request/response, errors

Database operations? → Integration tests with test DB → Test: CRUD, transactions, constraints

UI interactions? → E2E tests (Playwright/Cypress) → Test: user flows, critical paths

Multiple systems interacting? → Integration tests → Test: data flow, error propagation

code


### Documentation Scope Determination

**Decision tree:**

What's the change?

New user-facing feature? ├─ README: Usage example ├─ CHANGELOG: Feature entry └─ User guide: Detailed walkthrough

New API/function? ├─ JSDoc/TSDoc: API documentation ├─ README: Quick example └─ API reference: Full details

Configuration change? ├─ Config docs: New options ├─ README: Updated setup └─ Migration guide (if breaking)

Bug fix? ├─ CHANGELOG: Fixed entry └─ Tests: Regression coverage

Internal refactoring? └─ CHANGELOG: Technical note (optional)

code


### Iteration vs Delivery Decision

**When to iterate:**

Tests failing? └─ Iterate (fix and retest)

Feature incomplete? └─ Iterate (finish implementation)

Requirements unclear after starting? └─ STOP and ask user (return to Phase 0)

Code doesn't follow patterns? └─ Iterate (refactor to match)

Documentation insufficient? └─ Iterate (improve docs)

code


**When to deliver partial work:**

Blocker requires user input? ├─ Commit what's done ├─ Document blocker ├─ Create draft PR with notes └─ Ask user for help

External dependency unavailable? ├─ Implement what's possible ├─ Document missing piece └─ Deliver with action items

Fundamental approach wrong? ├─ Stop implementation ├─ Explain issue to user └─ Request new direction

code


**Never stop for:**
- Test failures (iterate until passing)
- Lint errors (fix immediately)
- Unclear code (refactor until clear)
- Missing docs (write them)

---

## 11. Error Recovery Procedures

### Worktree Creation Failures

**Error:** `gw add` fails

**Diagnosis:**
```bash
# Check git status
git status

# Check worktree list
git worktree list

# Check if branch already exists
git branch --list <branch-name>

Recovery:

code

Branch already exists?
├─ Use different branch name
└─ Or: Use existing branch (gw cd <branch>)

Permission error?
├─ Check directory permissions
└─ Try with sudo (if appropriate)

Disk space issue?
├─ Run: df -h
├─ Clean up: gw prune --clean
└─ Retry after space freed

Git error?
├─ Read error message carefully
├─ Fix underlying git issue
└─ Retry worktree creation

Dependency Installation Failures

Error: npm install fails

Diagnosis:

bash

# Check node version
node --version

# Check package manager
which npm pnpm yarn

# Check network
ping registry.npmjs.org

# Read error output carefully

Recovery:

code

Network error?
├─ Check internet connection
├─ Try different registry
└─ Use cached dependencies

Version incompatibility?
├─ Check node version requirements
├─ Switch node version (nvm)
└─ Update package.json if needed

Lock file mismatch?
├─ Delete lock file
├─ Delete node_modules
└─ Reinstall fresh

Disk space?
├─ Clean npm cache: npm cache clean --force
└─ Free disk space

Test Failures During Iteration

Error: Tests fail after implementation

Diagnosis:

bash

# Run single failing test with verbose output
npm test -- --testPathPattern="failing-test" --verbose

# Check test coverage
npm test -- --coverage

# Read stack trace completely

Recovery approach:

markdown

## Iteration 1: Fix Obvious Issues
1. Read error message completely
2. Identify assertion that failed
3. Fix most likely cause
4. Rerun tests
5. Assess: Better or worse?

## Iteration 2: Deep Analysis
If still failing:
1. Add console.logs to understand state
2. Check assumptions about data/types
3. Verify mocks/stubs are correct
4. Fix root cause (not symptom)
5. Rerun tests

## Iteration 3: Alternative Approach
If still failing:
1. Question implementation approach
2. Review similar code in codebase
3. Consider simpler solution
4. Refactor if necessary
5. Rerun tests

## Iteration 4+: Systematic Debugging
1. Isolate minimal reproduction
2. Test each component independently
3. Verify test itself is correct
4. Consider test environment issues
5. Keep iterating until passing

## If Truly Stuck (rare):
1. Commit working code with failing test
2. Document exact failure and attempts
3. Ask user for guidance

Never give up after fixed iterations - iterate until tests pass or blocker identified.

Merge Conflicts

Error: Merge conflict when pushing/rebasing

Diagnosis:

bash

# Check conflict files
git status

# View conflicts
git diff

Recovery:

markdown

## Step 1: Understand Conflicts
- Read both versions (HEAD vs incoming)
- Understand intent of each change
- Determine correct resolution

## Step 2: Resolve Conflicts
```bash
# Open conflicted files
# Edit to resolve conflicts (remove markers)
# Keep both changes if both needed
# Choose one if mutually exclusive

Step 3: Test After Resolution

bash

# Ensure code still works
npm run build
npm test

Step 4: Complete Resolution

bash

git add <resolved-files>
git commit  # Or git rebase --continue

Step 5: Validate

•All conflicts resolved?
•Tests still pass?
•Code makes sense?

code


### Build Failures

**Error:** `npm run build` fails

**Diagnosis:**
```bash
# Read build output completely
npm run build 2>&1 | tee build.log

# Check TypeScript errors
npx tsc --noEmit

# Check for missing files

Recovery:

code

TypeScript error?
├─ Fix type issues
├─ Add missing types
└─ Update imports

Missing dependency?
├─ Install missing package
└─ Update imports

Path/import error?
├─ Check file locations
├─ Fix import paths
└─ Verify tsconfig paths

Config error?
├─ Review build config
├─ Check recent changes
└─ Restore working config

12. Safety Guardrails

Validation Checkpoints

Phase 0: Mandatory validation before any work

•✓ Requirements understood
•✓ User confirmed understanding

Phase 1: Plan validated before implementation

•✓ Plan matches requirements
•✓ Approach is sound

Phase 2: Environment validated before coding

•✓ Worktree created
•✓ Dependencies installed

Phase 3: Code validated during implementation

•✓ Builds after each file
•✓ Self-review before commit

Phase 4: Tests validated before delivery

•✓ All tests pass
•✓ Requirements verified

Phase 5: Documentation validated for clarity

•✓ Read as new user
•✓ Examples tested

Phase 6: Everything validated before PR

•✓ All checks passing
•✓ Complete and ready

Rollback Procedures

If need to undo work:

bash

# Undo uncommitted changes
git checkout .

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Return to starting point
git reset --hard origin/main

# Remove worktree entirely
gw remove <branch-name> --force

When to Stop and Ask

Stop autonomous execution and ask user when:

•
Requirements ambiguous mid-implementation
- •User's request wasn't clear enough
- •Edge case discovered not covered in Phase 0
- •Multiple valid approaches, unclear which to use
•
Fundamental blocker encountered
- •Required external service/API unavailable
- •Missing credentials/access
- •Architectural decision needed
•
Scope creep detected
- •Implementation expanding beyond original scope
- •Additional features seem necessary
- •Breaking changes not originally discussed
•
Tests reveal misunderstanding
- •Tests passing but not actually testing requirement
- •Requirements seem contradictory
- •Expected behavior unclear
•
Resource/time limits approaching
- •Already spent excessive time (>2 hours)
- •Many iterations without progress
- •Complexity greater than initially assessed

How to ask:

markdown

"⚠️ Pausing autonomous execution - need guidance.

**Situation:**
[Describe what happened]

**Issue:**
[Explain the blocker/ambiguity]

**Options I see:**
1. [Option A] - [pros/cons]
2. [Option B] - [pros/cons]
3. [Option C] - [pros/cons]

**My recommendation:**
[Which option and why]

**Question:**
[Specific question for user]

Should I proceed with [recommended option] or would you prefer [alternative]?"

Resource Limits

Soft limits (guidelines, not hard stops):

•Commits: ~3-10 per feature (logical grouping)
•Files changed: ~20 files max (if more, consider splitting)
•Time: ~1-2 hours (if longer, reassess approach)
•Iterations: No limit (iterate until correct)
•Tests added: Proportional to complexity

Hard limits (stop and ask):

•>50 files changed - Scope too large, split into multiple PRs
•>3 hours stuck - Fundamental issue, need user input
•>100 commits - Something wrong with approach
•Breaking existing tests - Don't disable tests, fix code or ask

Quality Gates

Before moving to next phase:

• Previous phase checklist complete
• Self-validation passed
• No blocking errors
• Clear to proceed

Before final delivery (Phase 6):

If any gate fails:

•Stop immediately
•Identify root cause
•Fix the issue
•Re-validate
•Only proceed when gate passes

Summary

This autonomous workflow enables complete feature delivery through:

•✅ Phase 0 (MANDATORY): Validate understanding upfront through questions
•📋 Phase 1: Deep analysis and planning
•🔧 Phase 2: Isolated environment setup
•💻 Phase 3: Incremental implementation with continuous validation
•🧪 Phase 4: Aggressive iteration until all tests pass
•📚 Phase 5: Clear, validated documentation
•🚀 Phase 6: Comprehensive PR delivery
•🧹 Phase 7: Safe cleanup when appropriate

Key principles:

•Always ask clarifying questions first (Phase 0)
•Validate continuously, not just at the end
•Iterate until correct, no artificial limits
•Self-review every change immediately
•Deliver quality, not just speed
•Stop and ask when truly blocked

Success metrics:

•✅ Requirements fully met
•✅ All tests passing
•✅ Documentation complete
•✅ Clean commit history
•✅ Draft PR ready for review

Additional Resources

Part of the gw-tools skills collection

Autonomous Workflow - Complete Feature Delivery

Table of Contents

1. Workflow Overview

What This Skill Does

When to Use This Skill

Expected Outcomes

Autonomy Model

2. Phase 0: Validation & Questions (MANDATORY)

🔴 CRITICAL: ALWAYS START HERE

Objectives

Procedure

Example: Validation in Action

Validation Checklist

3. Phase 1: Task Intake & Planning

Objectives

Procedure

Planning Checklist

4. Phase 2: Worktree Setup

Objectives

Procedure

Step 3: Navigate to Worktree

Step 4: Install Dependencies

Step 5: Verify Environment

Step 6: Sync Configuration (If Needed)

Iterate if needed:

Step 3: Commit Incrementally

Step 4: Continuous Self-Validation

Step 5: Integration Check

Step 6: Pre-Testing Commit

Step 3: Analyze Test Failures

Understand the Failure:

Categorize:

Prioritize:

Step 4: Iterate Until Tests Pass

Iteration 1:

Iteration 2:

Iteration 3+:

Step 5: Add New Tests (If Applicable)

Step 6: Manual Validation (If Applicable)

Step 7: Final Validation

Step 8: Commit Test Changes

Step 3: Update API Documentation (If Applicable)

Step 4: Update CHANGELOG

Step 5: Update Other Documentation

Step 6: Self-Validation (Read as New User)

Step 7: Commit Documentation

Step 2: Push to Remote

Step 3: Generate PR Description

Step 4: Create Draft PR

Step 5: Report Completion to User

Step 6: Preserve Worktree

Step 2: Confirm with User (If Uncertain)

Step 3: Remove Worktree

Step 4: Navigate to Main

Step 5: Report Cleanup

Dependency Installation Failures

Test Failures During Iteration

Merge Conflicts

Step 3: Test After Resolution

Step 4: Complete Resolution

Step 5: Validate

12. Safety Guardrails

Validation Checkpoints

Rollback Procedures

When to Stop and Ask

Resource Limits

Quality Gates

Summary

Additional Resources