plugin: autopilot updated: 2026-01-20

Task Lifecycle State Machine

Version: 0.1.0 Purpose: Manage task state transitions with validation gates Status: Phase 1

When to Use

Use this skill when you need to:

• Understand valid state transitions for tasks
• Implement validation gates before state changes
• Handle iteration loops (In Review -> In Progress)
• Manage escalation to blocked state
• Enforce iteration limits

States

Todo ──→ In Progress ──→ In Review ──→ Done
                 ↑           │
                 └───────────┘
                 (iteration)

In Progress ──→ Blocked (escalation)

State Definitions

State	Description	Entry Condition
Todo	Task queued for execution	Created with @autopilot label
In Progress	Task being executed	Passed start gate
In Review	Awaiting validation	Proof generated
Done	Task completed	Auto-approved or user approved
Blocked	Cannot proceed	Dependency issue or escalation

Transition Triggers

From	To	Trigger	Gate
Todo	In Progress	Label @autopilot added	Has acceptance criteria
In Progress	In Review	Work complete	Proof >= 80% confidence
In Review	Done	Confidence >= 95%	Auto-approval
In Review	Done	User approves	User feedback = APPROVAL
In Review	In Progress	Confidence < 80%	Validation failed
In Review	In Progress	User requests changes	Feedback = REQUESTED_CHANGES
In Progress	Blocked	Max iterations	Escalation
*	Blocked	Unresolvable blocker	Manual trigger

Validation Gates

Gate 1: Start Work (Todo -> In Progress)

async function canStartWork(issue: Issue): Promise<boolean> {
  const checks = [
    // Has acceptance criteria
    extractAcceptanceCriteria(issue.description).length > 0,

    // No blocking dependencies
    (await getBlockingIssues(issue)).length === 0,

    // Assigned to autopilot
    issue.assignee?.id === AUTOPILOT_BOT_USER_ID,
  ];

  return checks.every(c => c);
}

Gate 2: Submit for Review (In Progress -> In Review)

async function canSubmitForReview(proof: Proof): Promise<boolean> {
  const checks = [
    // All tests pass
    proof.testResults.passed === proof.testResults.total,

    // Build successful
    proof.buildSuccessful,

    // No lint errors
    proof.lintErrors === 0,

    // Has proof artifacts
    proof.screenshots.length > 0 || proof.deploymentUrl,
  ];

  return checks.every(c => c);
}

Gate 3: Complete (In Review -> Done)

async function canComplete(proof: Proof): Promise<{
  canProceed: boolean;
  autoApproved: boolean;
}> {
  if (proof.confidence >= 95) {
    return { canProceed: true, autoApproved: true };
  }

  if (proof.confidence >= 80) {
    return { canProceed: false, autoApproved: false };
    // Wait for user approval
  }

  return { canProceed: false, autoApproved: false };
  // Validation failed, should iterate
}

Iteration Limits

Loop Type	Max Iterations	Escalation
Execution retry	2	Block task
Feedback rounds	5	Manual intervention
Quality check fixes	2	Report to user

Implementation

class StateMachine {
  async transition(
    issueId: string,
    targetState: string,
    proof?: Proof
  ): Promise<void> {
    const issue = await linear.issue(issueId);
    const currentState = issue.state.name;

    // Validate transition
    const isValid = this.validateTransition(currentState, targetState, proof);

    if (!isValid) {
      throw new Error(`Invalid transition: ${currentState} -> ${targetState}`);
    }

    // Execute transition
    await linear.issueUpdate(issueId, {
      stateId: await this.getStateId(issue.team.id, targetState),
    });

    // Log transition
    await this.logTransition(issueId, currentState, targetState, proof);
  }

  private validateTransition(
    from: string,
    to: string,
    proof?: Proof
  ): boolean {
    const validTransitions: Record<string, string[]> = {
      'Todo': ['In Progress', 'Blocked'],
      'In Progress': ['In Review', 'Blocked'],
      'In Review': ['Done', 'In Progress'],
      'Blocked': ['Todo', 'In Progress'],
    };

    return validTransitions[from]?.includes(to) ?? false;
  }
}

State Transition Diagram

                    ┌─────────────────────────────┐
                    │                             │
                    ▼                             │
┌──────┐       ┌─────────────┐       ┌───────────┴───┐       ┌──────┐
│ Todo │ ────► │ In Progress │ ────► │   In Review   │ ────► │ Done │
└──────┘       └─────────────┘       └───────────────┘       └──────┘
    │               │                        │
    │               │                        │
    │               ▼                        │
    │          ┌─────────┐                   │
    └────────► │ Blocked │ ◄─────────────────┘
               └─────────┘

Examples

Example 1: Happy Path

// Task created
await transitionState(issueId, 'In Progress');  // Gate: Has acceptance criteria

// Work complete, proof generated
await transitionState(issueId, 'In Review');    // Gate: Proof >= 80%

// High confidence auto-approval
await transitionState(issueId, 'Done');         // Gate: Confidence >= 95%

Example 2: Iteration Loop

// First attempt
await transitionState(issueId, 'In Progress');
await transitionState(issueId, 'In Review');    // Confidence: 85%

// User requests changes
await transitionState(issueId, 'In Progress');  // Feedback: REQUESTED_CHANGES

// Second attempt
await transitionState(issueId, 'In Review');    // Confidence: 97%
await transitionState(issueId, 'Done');         // Auto-approved

Example 3: Escalation

// After 5 feedback rounds
if (iterationCount >= MAX_FEEDBACK_ROUNDS) {
  await transitionState(issueId, 'Blocked');
  await addComment(issueId, "Escalated: Max iterations reached");
}

Best Practices

• Always validate before transitioning
• Log all transitions for audit trail
• Include proof artifacts when transitioning to In Review
• Enforce iteration limits to prevent infinite loops
• Escalate gracefully rather than failing silently
• Comment on Linear when state changes for visibility