state-machine

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) ```typescript 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) ```typescript 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) ```typescript 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 ```typescript 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 ```typescript // 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 ```typescript // 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 ```typescript // 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