gh-jpicklyk-task-orchestrator-claude-plugins-task-orchestrator/skills/status-progression/SKILL.md

---
skill: status-progression
description: Navigate status workflows with user's config. Use when asked "What's next?", "Can I move to X?", or "Why did this fail?". Delegates to get_next_status tool, interprets StatusValidator errors, explains forward/backward/emergency patterns. Lightweight coordinator - validates nothing, explains everything.
---

# Status Progression Skill

**Role:** Workflow interpreter and guide. Helps users navigate their custom status workflows by delegating to tools and explaining results.

**Complementary Architecture:**
- **get_next_status tool** - Reads config, analyzes state, recommends next status (read-only)
- **StatusValidator** - Validates transitions at write-time, enforces rules, checks prerequisites (write-time)
- **This Skill** - Interprets recommendations and errors, explains user's config rules (guidance)

## When to Use This Skill

**Activate for:**
- "What status comes next?"
- "Can I move to testing/completed/etc?"
- "Why did my status change fail?"
- "Am I ready to complete this?"
- "What's my workflow?"
- "How do backward transitions work?"

## Core Responsibilities

1. **Delegate to get_next_status** - Let the tool analyze state and recommend next status
2. **Read user's config** - Load `status_validation` rules to explain what's possible
3. **Interpret errors** - Explain StatusValidator error messages in context of user's config
4. **Guide transitions** - Explain forward, backward, and emergency movements

## Tools Available

- `Read` - Load `.taskorchestrator/config.yaml` (status_validation section only)
- `get_next_status` - Intelligent status recommendations (delegates to MCP tool)
- `query_workflow_state` - Complete workflow state with cascade events (**NEW**)
- `query_container` - Check entity state (status, tags) when interpreting errors

**Critical:** This skill does NOT validate transitions. StatusValidator handles that automatically at write-time. This skill interprets results and explains user's workflow rules.

## Workflow Patterns: Forward, Backward, and Emergency

### Pattern 1: Forward Progression (Happy Path)

**When:** Moving through normal workflow sequence

**Example:**
```javascript
// User asks: "What's next?"
recommendation = get_next_status(containerId="task-uuid", containerType="task")

// Guide user:
"You're at: in-progress
Next step: testing

Your bug_fix_flow: pending → in-progress → testing → completed
StatusValidator will verify prerequisites when you transition."
```

**Why forward?** Normal progression toward completion.

### Pattern 2: Backward Movement (Rework/Iteration)

**When:** Need to fix issues, iterate on work, or respond to changes

**Example:**
```javascript
// User asks: "Can I move back to in-progress from in-review?"
config = Read(".taskorchestrator/config.yaml")

if (config.status_validation.allow_backward == true) {
  "✅ Yes! Your config allows backward movement.

  in-review → in-progress (backward to implement changes)

  Why: Code review requested changes, found a bug, requirements changed
  Then re-submit: in-progress → in-review"
}
```

**Why backward?** Iterative development - fix issues and retry without restarting from scratch.

**For detailed review iteration patterns:**
Read `./config-reference.md`

### Pattern 3: Emergency Transitions (Blockers/Cancellations)

**When:** Unexpected blockers, priority changes, or cancellations

**Example:**
```javascript
// User asks: "Task is blocked by external API, what do I do?"
config = Read(".taskorchestrator/config.yaml")

emergencyStatuses = config.status_progression.tasks.emergency_transitions
// Returns: [blocked, on-hold, cancelled, deferred]

"✅ Use emergency transition to: blocked
in-progress → blocked (emergency - can happen from any state)

Why emergency transitions exist:
- blocked: External dependency or technical issue
- on-hold: Priority shift, paused temporarily
- cancelled: Task no longer needed
- deferred: Postponed indefinitely"
```

**Why emergency?** Real-world interruptions don't follow linear workflows.

## Quick Action Patterns

### Action 1: What's Next?

**User:** "What status comes next?"

**Workflow:**
```javascript
// Delegate to tool
recommendation = get_next_status(containerId="task-uuid", containerType="task")
```

**Response:**
```
Next: testing

Your position: in-progress [YOU ARE HERE]
Flow: pending → in-progress → testing → completed
Using: bug_fix_flow (matched your tags: [bug, backend])

To transition:
manage_container(operation="setStatus", containerType="task", id="...", status="testing")
```

### Action 2: Try Transition (Let StatusValidator Check)

**User:** "Can I mark this complete?"

**Workflow:**
```javascript
// Don't manually validate - delegate to get_next_status
recommendation = get_next_status(containerId="task-uuid", containerType="task")

// Guide user to try it
"get_next_status recommends: completed

Try it! StatusValidator will check prerequisites automatically:
manage_container(operation=\"setStatus\", containerType=\"task\", id=\"...\", status=\"completed\")

If prerequisites aren't met, StatusValidator will explain what's missing.
I'll help interpret any errors."
```

**Key:** Let StatusValidator do validation. This skill interprets results.

### Action 3: Interpret StatusValidator Error

**User gets error:** "Cannot skip statuses. Must transition through: in-progress"

**Workflow:**
```javascript
// Read user's config to explain the rule
config = Read(".taskorchestrator/config.yaml")

"StatusValidator blocked this because YOUR config has:
  enforce_sequential: true

You tried: pending → testing (skipped in-progress)

Your options:
1. Follow sequential flow: pending → in-progress → testing
2. Change your config: Set enforce_sequential: false in config.yaml

Recommended next step:
manage_container(operation=\"setStatus\", containerType=\"task\", id=\"...\", status=\"in-progress\")"
```

**For detailed error interpretation patterns:**
Read `./validation-errors.md`

### Action 4: Check Complete Workflow State (NEW)

**User asks:** "Show me everything about this task's workflow"

**Workflow:**
```javascript
// Get comprehensive workflow state
workflowState = query_workflow_state(
  containerType="task",
  id="task-uuid"
)

// Explain complete state
"📊 Workflow State:

Current: ${workflowState.currentStatus}
Active Flow: ${workflowState.activeFlow}

✅ Allowed Next Steps:
${workflowState.allowedTransitions.map(s => `  → ${s}`).join('\n')}

⚠️ Cascade Events Detected:
${workflowState.detectedEvents.map(e => `  • ${e.event}: ${e.reason}`).join('\n')}

📋 Prerequisites for Each Transition:
${Object.entries(workflowState.prerequisites).map(([status, prereq]) =>
  `  ${status}: ${prereq.met ? '✅' : '❌'} ${prereq.blockingReasons.join(', ')}`
).join('\n')}"
```

**Benefits:**
- Single call gets complete workflow context
- Shows all allowed transitions from config
- Detects cascade events automatically
- Validates prerequisites for each option
- Works with user's custom workflows

### Action 5: Phase 3 Handoff (Tasks Ready to Execute)

**Scenario:** Feature has tasks created and ready to execute, but feature status is still "planning" or "draft"

**User asks:** "Progress feature to in-development before executing tasks"

**Workflow:**
```javascript
// Check feature status
feature = query_container(operation="get", containerType="feature", id=featureId)

if (feature.status == "planning" || feature.status == "draft") {
  // Get recommendation
  recommendation = get_next_status(containerId=featureId, containerType="feature")

  // Explain the cascade event and use recommendation
  "✅ Feature ready to progress from: ${feature.status}
  Recommended next status: ${recommendation.recommendedStatus}
  Active flow: ${recommendation.activeFlow}

  Cascade Event: tasks_ready_to_execute
  Trigger: Tasks created and ready for specialist execution

  Why this matters:
  - Feature status must reflect current development phase
  - Config determines execution phase status name (not hardcoded)
  - Your workflow uses: ${recommendation.activeFlow}

  To progress:
  manage_container(operation=\"setStatus\", containerType=\"feature\", id=\"${featureId}\", status=\"${recommendation.recommendedStatus}\")

  Then delegate to Task Orchestration Skill for parallel execution."
}
```

**When this applies:**
- After Phase 2 (task breakdown) completes
- Before Phase 3 (task execution) begins
- When resuming paused feature work with pending tasks

**Why critical:**
- Prevents feature from jumping directly to completion (skips execution phase)
- Enables proper cascade event detection (tasks_ready_to_execute)
- Ensures workflow state reflects reality (config-driven status progression)
- Required for StatusValidator prerequisite checks
- Respects user's custom workflow (not hardcoded to specific status names)

## Understanding User-Defined Flows

**Critical:** Flows are defined by the USER in their config.yaml. Don't assume any specific flows exist.

**Check user's actual flows:**
```javascript
config = Read(".taskorchestrator/config.yaml")
taskFlows = Object.keys(config.status_progression.tasks).filter(key => key.endsWith('_flow'))
// Tell user: "Your config has these task flows: [list]"
```

**Default config has** (IF user hasn't customized):
- Tasks: `default_flow`, `bug_fix_flow`, `documentation_flow`, `hotfix_flow`, `with_review`
- Features: `default_flow`, `rapid_prototype_flow`, `with_review_flow`
- Projects: `default_flow`

**For custom flow examples (research, compliance, experiments, etc.):**
Read `./examples.md`

**For tag-based flow selection details:**
Read `./examples.md`

## What to Read from Config

**Read selectively** - only load sections needed to explain user's rules:

```javascript
config = Read(".taskorchestrator/config.yaml")

// Section 1: Validation rules (always useful)
validationRules = config.status_validation
// - enforce_sequential: Can skip statuses?
// - allow_backward: Can move backwards?
// - allow_emergency: Can jump to blocked/cancelled?
// - validate_prerequisites: Does StatusValidator check requirements?

// Section 2: Entity-specific flows (when explaining workflows)
taskFlows = config.status_progression.tasks
emergencyStatuses = config.status_progression.tasks.emergency_transitions
terminalStatuses = config.status_progression.tasks.terminal_statuses
```

**For detailed config structure reference:**
Read `./config-reference.md`

## Best Practices

1. **Always delegate to get_next_status** - Let the tool analyze state and recommend
2. **Read config selectively** - Load only status_validation and relevant flows
3. **Never duplicate validation** - StatusValidator checks prerequisites, not this skill
4. **Explain user's specific config** - Don't assume default flows exist
5. **Interpret, don't predict** - Explain errors after they happen, don't try to predict them
6. **Use progressive loading** - Load supporting files (examples.md, validation-errors.md, config-reference.md) only when needed
7. **Emphasize user control** - Flows are defined by user, not hardcoded by system

## Supporting Files

**Load on demand for specific scenarios:**

- **./examples.md** - Custom flow examples, tag-based selection patterns
  - Load when: User asks about custom flows, workflow possibilities, tag routing

- **./validation-errors.md** - Common errors, prerequisite failures, fix patterns
  - Load when: StatusValidator error occurs, user asks about validation rules

- **./config-reference.md** - Detailed config structure, backward movement, integration
  - Load when: User asks about configuration, how to customize workflows

## Key Reminders

**Your Role (Lightweight Coordination):**
- ✅ Delegate to get_next_status for all recommendations
- ✅ Read config.status_validation to explain user's rules
- ✅ Interpret StatusValidator errors with context
- ✅ Show forward/backward/emergency patterns with WHY explanations
- ✅ Reference user's ACTUAL config, not assumed defaults
- ✅ Load supporting files only when needed (progressive loading)

**What You DON'T Do:**
- ❌ Don't manually validate transitions (StatusValidator's job)
- ❌ Don't check prerequisites before transitions (StatusValidator's job)
- ❌ Don't duplicate logic from get_next_status (delegate to tool)
- ❌ Don't assume specific flows exist (user-defined, could be customized)
- ❌ Don't load all supporting files upfront (use progressive loading)

**Complementary Roles:**
- **get_next_status** reads config, analyzes tags, recommends (read-only)
- **StatusValidator** enforces rules, checks prerequisites (write-time)
- **You** interpret results, explain possibilities (guidance)