autonomous-execution

Autonomous Execution

This skill provides patterns for executing projects autonomously while maintaining quality and knowing when to stop and ask for help.

Prerequisites for Autonomous Execution

Before starting autonomous work, verify:

Project Readiness

• Tech Plan exists - Architecture and sequencing documented
• Tasks Document exists - Granular tasks with acceptance criteria
• Success criteria defined - Clear "done" definition
• Tests exist - Automated validation available
• Quality gates configured - Pre-commit hooks, CI checks

Documentation Readiness

• Project docs available - CLAUDE.md, relevant docs
• Troubleshooting guide exists - Common issues documented
• Stop conditions clear - When to pause and ask

Execution Patterns

Pattern 1: Task-by-Task Execution

When to use: Standard execution for most projects

Process:

1. Read task - Understand requirements and acceptance criteria
2. Plan approach - Identify implementation strategy
3. Implement - Write code following project standards
4. Self-validate - Run tests, check acceptance criteria
5. Update status - Mark task complete, update progress
6. Proceed to next - Move to next task

Validation Checkpoints:

• After each task: Run relevant test suite
• After each phase: Run full test suite
• Before completion: Complete quality gate checklist

Pattern 2: Phase-by-Phase Execution

When to use: Projects with clear phases (migrations, refactors)

Process:

1. Complete all tasks in current phase
2. Run phase-specific validation
3. Verify quality gates pass
4. Document learnings
5. Proceed to next phase only after validation

Pattern 3: Incremental Validation

When to use: Large projects or risky changes

Process:

1. Make small, focused change
2. Validate immediately
3. Commit only if validation passes
4. Repeat with next small change

Checkpoint Integration (Mandatory)

Write session checkpoints — context compaction is inevitable in long runs, not an edge case:

• Write checkpoints every 3 completed tasks — this is not optional
• Write to docs/checkpoints/latest.md
• Include: current task, decisions made, next steps, hot files
• Also write before stopping for any reason (blockers, session end, user interrupt)
• Why: Context compaction destroys working memory. Checkpoints are the only mechanism that preserves decisions and rationale across compaction events. Treat them as mandatory infrastructure, not a nice-to-have.

See the session-checkpoint skill for the full checkpoint format.

Worktree Isolation

When running multiple independent tasks, consider whether to use git worktrees for isolation:

Scenario	Recommendation	Reason
Sequential tasks in one subsystem	Stay on branch	Low isolation benefit, worktree overhead not worth it
Independent tasks across 2+ subsystems	Parallel worktrees	Tasks can't interfere with each other, enables parallel agents
Background maintenance tasks (lint fixes, doc updates)	Always use worktree	Keeps primary branch clean for feature work
Risky or experimental changes	Use worktree	Easy to discard without affecting main work

When NOT to use worktrees:

• Tasks that depend on each other's output
• Tasks that modify shared state (same config files, same database schema)
• When the project is small enough that all tasks touch the same files

Self-Validation Strategies

Task-Level Validation

After completing each task:

1. Run relevant tests:

   • Unit tests for logic changes
   • Integration tests for API/service changes
   • E2E tests for user-facing changes

2. Check acceptance criteria:

   • Review each criterion
   • Verify all can be marked complete
   • Document any deviations

3. Run quality checks:

   • Type checking
   • Linting
   • Build verification

4. Update task status:

   • Mark acceptance criteria complete
   • Add completion notes
   • Update status to "Complete"

Phase-Level Validation

After completing each phase:

1. Run phase-specific validation (if script exists)
2. Run full test suite multiple times (catch flakiness)
3. Verify all quality gates pass
4. Document any learnings or issues

Stop Conditions

CRITICAL: Stop and ask for help when encountering:

Immediate Stop (Blockers)

Condition	Action
Tests fail 3+ times	Stop, document issue
Architectural decision needed	Stop, ask for guidance
External dependency blocked	Stop, report blocker
Quality gate failure (can't fix)	Stop, seek help
Ambiguous requirements	Stop, ask for clarification
Same tool fails 2+ times	Switch strategy, don't brute-force
Unsure about platform capability	Say "I'm not sure, let me verify" — don't state as fact

Pause and Evaluate

Condition	Action
Unexpected complexity	Assess scope, consider asking
Breaking changes detected	Evaluate impact, may need input
Performance regression	Investigate, may need guidance
Security concerns	Always ask before proceeding

How to Stop Gracefully

When stopping:

1. Document current state:

   • What was attempted
   • What failed
   • What was learned

2. Update task status:

   • Mark as "Blocked" or "In Progress"
   • Add blocker notes

3. Create summary:

   • Brief description of issue
   • What was tried
   • What's needed to proceed

Quality Gates

Pre-Commit Gates

Before each commit, discover and run project-specific validation (from CLAUDE.md / package.json):

• Discover: ci:local > test:verify > test:pre-push > individual commands
• If composite script exists (e.g., npm run ci:local): run it instead of individual commands
• Run with explicit Bash timeout (300000ms) if validation takes >2 minutes

At minimum verify:

• No skipped tests (.skip)
• No focused tests (.only)
• Linting passes
• Type checking passes
• Unit tests pass

Pre-Phase Gates

Before proceeding to next phase:

• All phase tasks complete
• Phase validation passes
• Full test suite passes
• All pre-commit gates pass

Pre-Completion Gates

Before marking project complete:

• All tasks complete
• All acceptance criteria met
• All tests passing
• No regressions
• Documentation updated

Progress Tracking

After Each Task

1. Mark acceptance criteria checkboxes
2. Add completion notes
3. Update task status
4. Update "Current Focus" to next task

Metrics to Track

• Completion percentage (tasks done / total)
• Phase completion status
• Test coverage (maintain or improve)
• Quality gate status

Troubleshooting Common Issues

Tests Fail After Changes

1. Review test output for specific failures
2. Check if changes broke test assumptions
3. Verify test data/fixtures are correct
4. Run tests in isolation
5. Check if dependencies changed

Quality Gates Block Commit

1. Read error message carefully
2. Fix the specific issue
3. Re-run checks locally
4. Don't bypass - fix root cause

Unclear Acceptance Criteria

1. Review task description and context
2. Check tech plan for guidance
3. Review similar completed tasks
4. Stop and ask if still unclear

Best Practices

Code Quality

• Follow project standards and existing patterns
• Write tests when possible
• Keep changes small and focused
• Document decisions in completion notes

Validation

• Validate early and often
• Run full suite regularly
• Don't proceed if gates fail
• Verify acceptance criteria are actually met

Progress Management

• Update status after every task
• Document learnings as you go
• Track blockers explicitly
• Celebrate completed tasks

Communication

• Write clear completion notes
• Ask when stuck (don't waste time)
• Share learnings
• Be transparent about deviations

Integration with Playbook

This skill supports:

• /playbook:work - Primary execution command
• /playbook:tasks - Task document management
• /playbook:learnings - Post-execution capture

Success Criteria

Autonomous execution is successful when:

• All tasks complete
• All tests passing
• Quality gates pass
• No regressions
• Documentation updated
• Ready for review

---

Autonomous execution requires discipline: validate often, stop when uncertain, document everything.