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

Status Progression - Flow Examples

This file contains custom flow examples and tag-based selection patterns. Load this when users ask about workflow possibilities or custom flow creation.

Flows in Default Config (Starter Examples)

IF the user hasn't customized their config, these flows exist:

Task Flows

default_flow:

- backlog            # Task in backlog, needs prioritization
- pending            # Task ready, waiting to start
- in-progress        # Actively being worked on
- testing            # Implementation complete, running tests
- completed          # Task complete

bug_fix_flow:

- pending            # Bug reported, ready to fix (skip backlog for urgency)
- in-progress        # Fixing bug
- testing            # Testing fix
- completed          # Bug fixed

documentation_flow:

- pending
- in-progress
- in-review          # Documentation review (no code testing needed)
- completed

hotfix_flow:

- pending
- in-progress
- completed          # Emergency fixes, skip backlog and review

with_review:

- backlog
- pending
- in-progress
- in-review          # Awaiting code review
- testing            # Review approved, testing
- completed

Feature Flows

default_flow:

- draft              # Initial draft, rough ideas
- planning           # Define requirements, break into tasks
- in-development     # Active implementation
- testing            # All tasks complete, running tests
- validating         # Tests passed, final validation
- completed          # Feature complete and validated

rapid_prototype_flow:

- draft
- in-development     # Skip planning and testing for quick experiments
- completed

with_review_flow:

- draft
- planning
- in-development
- testing
- validating
- pending-review     # Awaiting human approval
- completed

Project Flows

default_flow:

- planning           # Define scope and features
- in-development     # Active development
- completed          # Project finished
- archived           # Archive for history

---

Example Custom Flows (What Users COULD Create)

These DON'T exist by default - they show what's possible when users customize their config.

1. Research Task Flow

Use case: Research tasks, spikes, investigations that don't need testing

research_task_flow:
  - pending
  - in-progress
  - completed         # No testing needed for research

flow_mappings:
  - tags: [research, spike, investigation]
    flow: research_task_flow

Why this works:

• Research is exploratory, doesn't produce testable code
• Skips testing gate entirely
• Faster completion for non-code work

Example tasks:

• "Research authentication libraries"
• "Investigate performance bottleneck"
• "Spike: Feasibility of real-time sync"

2. Compliance Review Flow

Use case: Regulated features requiring legal/compliance approval

compliance_review_flow:
  - draft
  - planning
  - in-development
  - testing
  - validating
  - pending-review    # Legal/compliance review gate
  - completed

flow_mappings:
  - tags: [compliance, regulated, audit, hipaa, gdpr]
    flow: compliance_review_flow

Why this works:

• Adds formal approval gate before completion
• Required for regulated industries (healthcare, finance)
• Ensures compliance sign-off is documented

Example features:

• "HIPAA-compliant patient data storage"
• "GDPR data export API"
• "SOC 2 audit logging"

3. Experiment Flow

Use case: Experiments designed to fail fast without formal process

experiment_flow:
  - pending
  - in-progress
  - cancelled         # Most experiments fail - that's OK!
  # OR
  - completed         # Some succeed

# No testing or review required - experiments are exploratory

flow_mappings:
  - tags: [experiment, try, explore]
    flow: experiment_flow

Why this works:

• Experiments are meant to fail fast
• No formal testing/review overhead
• Terminal states: cancelled (expected) or completed (rare success)

Example tasks:

• "Experiment: Can we use WebAssembly for this?"
• "Try implementing with GraphQL instead"
• "Explore alternative caching strategy"

4. Staged Rollout Flow

Use case: Gradual deployment with validation gates

staged_rollout_flow:
  - draft
  - planning
  - in-development
  - testing
  - validating
  - deployed          # Custom intermediate status (if added to enum)
  - completed

flow_mappings:
  - tags: [gradual-rollout, canary, phased-deploy]
    flow: staged_rollout_flow

Why this works:

• Adds explicit "deployed" state between validating and completed
• Allows tracking deployment progress separately
• Useful for canary deployments, feature flags

Note: Requires adding "deployed" status to FEATURE enum (not in default)

Example features:

• "New recommendation algorithm (canary rollout)"
• "Payment provider migration (phased)"

5. Multi-Stage Review Flow

Use case: Features requiring multiple approval stages (design, security, business)

multi_review_flow:
  - draft
  - planning
  - in-review          # Design review
  - in-development
  - testing
  - validating
  - pending-review     # Security/business review
  - completed

flow_mappings:
  - tags: [high-risk, security-critical, business-critical]
    flow: multi_review_flow

Why this works:

• Two review gates: after planning (design) and before completion (security/business)
• Catches issues early with design review
• Final validation before production

Example features:

• "New authentication method"
• "Payment processing changes"
• "Data retention policy implementation"

6. Simple Task Flow (Minimal Overhead)

Use case: Trivial tasks that don't need backlog or testing

simple_task_flow:
  - pending
  - in-progress
  - completed

flow_mappings:
  - tags: [trivial, simple, quick-fix]
    flow: simple_task_flow

Why this works:

• Minimal workflow for tiny changes
• Skips backlog (not worth prioritizing)
• Skips testing (too small to warrant formal testing)

Example tasks:

• "Update copyright year"
• "Fix typo in error message"
• "Add tooltip to button"

---

Tag-Based Flow Selection

The get_next_status tool automatically selects workflows based on tags IF the user has flow_mappings configured.

How Tag Matching Works

// get_next_status reads user's config and matches tags
recommendation = get_next_status(
  containerId="task-uuid",
  containerType="task"
)

// Tool checks task tags → matches flow_mappings → returns appropriate flow
// If tags: [bug, backend] → uses bug_fix_flow (IF that mapping exists in config)
// If tags: [research] → uses research_task_flow (IF user created that flow)
// If no match → uses default_flow

Default Tag Mappings (IF User Hasn't Changed Config)

Task mappings:

flow_mappings:
  - tags: [bug, bugfix, fix]
    flow: bug_fix_flow
  - tags: [documentation, docs]
    flow: documentation_flow
  - tags: [hotfix, emergency, critical]
    flow: hotfix_flow
  - tags: [needs-review, code-review]
    flow: with_review

Feature mappings:

flow_mappings:
  - tags: [prototype, poc, spike]
    flow: rapid_prototype_flow
  - tags: [needs-review, stakeholder-approval]
    flow: with_review_flow

Custom Tag Mapping Examples

User's custom config could have:

# Tasks
flow_mappings:
  - tags: [research, spike]
    flow: research_task_flow        # Custom flow user created
  - tags: [compliance]
    flow: compliance_review_flow    # Another custom flow
  - tags: [experiment]
    flow: experiment_flow
  - tags: [trivial]
    flow: simple_task_flow

# Features
flow_mappings:
  - tags: [gradual-rollout, canary]
    flow: staged_rollout_flow
  - tags: [high-risk, security-critical]
    flow: multi_review_flow

Checking User's Actual Mappings

Always verify what the user has configured:

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

// Get task flow mappings
taskMappings = config.status_progression.tasks.flow_mappings
// Show user THEIR mappings, not assumed defaults

// Get feature flow mappings
featureMappings = config.status_progression.features.flow_mappings

// Tell user what's configured:
"Your task flow mappings:
- Tags [bug, bugfix, fix] → bug_fix_flow
- Tags [research] → research_task_flow  (custom!)
- Tags [experiment] → experiment_flow   (custom!)
- Default: default_flow"

Tag Matching Priority

When a task/feature has multiple tags, the first matching mapping wins:

flow_mappings:
  - tags: [hotfix, emergency, critical]
    flow: hotfix_flow               # Priority 1
  - tags: [bug, bugfix, fix]
    flow: bug_fix_flow              # Priority 2
  - tags: [needs-review]
    flow: with_review               # Priority 3

Example: Task with tags [hotfix, bug]

• Matches mapping 1 (hotfix) → uses hotfix_flow
• Does NOT use bug_fix_flow (even though "bug" tag is present)

Best practice: Order mappings from most specific to least specific.

---

Creating Custom Flows - Best Practices

1. Start with a Use Case

Ask:

• What makes this workflow different from default?
• What gates can I skip? (backlog, testing, review)
• What gates do I need to add? (compliance, multi-stage review)

2. Keep Flows Linear

Do:

research_task_flow:
  - pending
  - in-progress
  - completed

Don't:

research_task_flow:
  - pending
  - in-progress
  - in-progress    # ❌ Duplicates don't work with enforce_sequential
  - completed

Why: With enforce_sequential: true, duplicate statuses break validation. Use backward movement instead.

3. Use Backward Movement for Iterations

Instead of duplicating statuses, enable backward movement:

status_validation:
  allow_backward: true  # Enable this

Then flow becomes:

with_review:
  - pending
  - in-progress
  - in-review
  - testing
  - completed

# Iteration: in-review → in-progress (backward) → in-review (forward)
# Unlimited iterations without duplicate statuses

4. Tag Conventions

Use consistent tag patterns:

• Workflow type: research, experiment, compliance
• Urgency: hotfix, emergency, critical
• Process: needs-review, stakeholder-approval
• Domain: backend, frontend, database

Combine tags for specificity:

• Task with [bug, backend] → bug fix flow, backend specialist
• Task with [research, frontend] → research flow, frontend context

5. Document Your Custom Flows

Add comments to config.yaml:

# Research task flow - for spikes and investigations that don't produce testable code
# Created: 2024-01-15
# Use for: Technical research, library evaluations, architecture spikes
research_task_flow:
  - pending
  - in-progress
  - completed

---

When to Create a Custom Flow

Create custom flow when:

• ✅ Default flow has unnecessary gates for specific work types (research doesn't need testing)
• ✅ Need additional approval gates (compliance review, multi-stage approval)
• ✅ Want faster path for specific scenarios (hotfix skips backlog and review)
• ✅ Pattern repeats frequently (if you keep skipping same gates, formalize it)

Don't create custom flow when:

• ❌ One-off exception (use emergency transitions instead)
• ❌ Only difference is number of iterations (use backward movement)
• ❌ Can be handled by tags alone (tags don't require new flow)

---

Summary

Progressive Loading Pattern:

1. User asks: "What custom flows can I create?"
2. You load this file
3. Show relevant examples based on their context
4. Guide them to update their config.yaml

Remember:

• All examples here are POSSIBILITIES, not defaults
• Users must add flows to their config.yaml
• Always check user's actual config before referencing flows
• Use tag mappings to automatically route to appropriate flows