workflow-state-tracking

name	workflow-state-tracking
description	Tracks and visualizes CCPM workflow state transitions (IDEA → PLANNED → IMPLEMENTING → VERIFYING → VERIFIED → COMPLETE). Prevents invalid state transitions and suggests appropriate next actions. Auto-activates when users ask about task status, "where am I in the workflow", "what should I do next", or "can I do this now".
allowed-tools	["Task","Read"]

Workflow State Tracking

This skill provides real-time visibility into your CCPM workflow progress, prevents invalid state transitions, and guides you toward task completion through intelligent next action suggestions.

State Machine Overview

CCPM uses a structured 8-state workflow that progresses from concept to completion. Understanding these states helps you know exactly where you are and what to do next.

The 8 Workflow States

IDEA (💡)
  ↓
PLANNED (📋)
  ↓
IMPLEMENTING (🚀) ←→ BLOCKED (🚫)
  ↓
VERIFYING (🔍)
  ↓
VERIFIED (✅)
  ↓
COMPLETE (🎉)

CANCELLED (❌) - Terminal, can branch from any state

State Definitions

State	Phase	Description	Linear Status	Progress
IDEA	Ideation	Initial concept, not yet planned	Backlog	0%
PLANNED	Planning	Requirements gathered, plan created	Planned, Todo	25%
IMPLEMENTING	Implementation	Active development in progress	In Progress, In Development	50%
BLOCKED	Implementation	Cannot proceed due to blocker	Blocked	50%
VERIFYING	Verification	Quality checks and review in progress	In Review, Testing	75%
VERIFIED	Verification	Verified and ready to finalize	Verified, Approved	90%
COMPLETE	Completion	Task finalized and closed	Done, Completed	100%
CANCELLED	Cancelled	Task cancelled or abandoned	Cancelled, Archived	0%

State Properties

• Terminal States: COMPLETE and CANCELLED (no transitions out)
• Blocking States: BLOCKED (prevents progression to VERIFYING)
• Gating States: VERIFIED (required before COMPLETE)
• Reversible States: IMPLEMENTING can return to PLANNED if re-planning needed

State Detection

When you ask "Where am I?", this skill detects your current state by checking:

1. Linear Custom Fields

Most accurate: Reads CCPM custom fields directly from Linear issue

- ccpmPhase: Current state (IDEA, PLANNED, etc.)
- ccpmLastCommand: Last CCPM command executed
- ccpmLastUpdate: Timestamp of last update
- ccpmAutoTransitions: Whether state auto-updates

2. Linear Status Inference (Fallback)

If custom fields missing, infers from Linear status:

• "Backlog" → IDEA
• "Planned", "Todo", "Ready" → PLANNED
• "In Progress", "In Development" → IMPLEMENTING
• "Blocked" → BLOCKED
• "In Review", "Testing" → VERIFYING
• "Verified", "Approved" → VERIFIED
• "Done", "Completed" → COMPLETE
• "Cancelled", "Archived" → CANCELLED

3. Checklist Completion Analysis

Analyzes implementation checklist progress:

• 0-25% complete → Early IMPLEMENTING
• 50-75% complete → Mid IMPLEMENTING
• 80-99% complete → Near VERIFYING
• 100% complete → Ready to VERIFY

4. Git State Detection

Checks for uncommitted changes:

• Changes detected → Still IMPLEMENTING
• No changes → Ready for VERIFYING

Valid Transitions

Each state has specific allowed transitions. Attempting an invalid transition will be prevented with helpful suggestions.

Transition Matrix

IDEA        → PLANNED, CANCELLED
PLANNED     → IMPLEMENTING, IDEA, CANCELLED
IMPLEMENTING → VERIFYING, PLANNED, BLOCKED
BLOCKED     → IMPLEMENTING, CANCELLED
VERIFYING   → VERIFIED, IMPLEMENTING
VERIFIED    → COMPLETE, IMPLEMENTING
COMPLETE    → (terminal - no transitions)
CANCELLED   → (terminal - no transitions)

Confidence Levels

Each transition has a confidence score (0-100) indicating how certain the system is:

• 95%: High confidence (plan ready to implement)
• 85%: Good confidence (checks passing)
• 70%: Medium confidence (re-planning during implementation)
• 50%: Low confidence (requires explicit user confirmation)

Invalid Transition Prevention

The skill prevents invalid workflows and provides helpful corrections:

Common Invalid Transitions

❌ IDEA → IMPLEMENTING (skip planning)
   Suggestion: Run /ccpm:plan first

❌ IDEA → VERIFYING (skip planning + implementation)
   Suggestion: Follow workflow: IDEA → PLANNED → IMPLEMENTING → VERIFYING

❌ PLANNED → VERIFYING (skip implementation)
   Suggestion: Run /ccpm:work to start implementation

❌ IMPLEMENTING → COMPLETE (skip verification)
   Suggestion: Run /ccpm:verify first

❌ VERIFYING → COMPLETE (skip verified state)
   Suggestion: Fix issues and re-verify, then transition to VERIFIED

❌ COMPLETE → IMPLEMENTING (reopen completed task)
   Suggestion: Create new issue for follow-up work

Pre-Condition Checks

Before allowing transitions, the skill validates pre-conditions:

Transition to PLANNED requires:

• ✓ Implementation checklist exists in issue description
• ✓ Basic requirements documented

Transition to IMPLEMENTING requires:

• ✓ Plan exists (checklist section)
• ✓ Linear status allows (not in terminal state)

Transition to VERIFYING requires:

• ✓ Checklist 100% complete (or bypassed)
• ✓ No uncommitted git changes
• ✓ Code review initiated

Transition to VERIFIED requires:

• ✓ All quality checks passing
• ✓ Code review approved
• ✓ No security issues

Transition to COMPLETE requires:

• ✓ In VERIFIED state
• ✓ PR merged
• ✓ All checks passed

State Visualization

Progress Indicator

Visual representation of task completion:

IDEA:         [░░░░░░░░░░] 0%
PLANNED:      [██░░░░░░░░] 25%
IMPLEMENTING: [████████░░] 50%
VERIFYING:    [██████████░] 75%
VERIFIED:     [███████████░] 90%
COMPLETE:     [████████████] 100%

Current State Display

When checking status, you see:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 Workflow State
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🚀 Phase: IMPLEMENTING
📋 Status: In Progress
⚙️  Last Command: /ccpm:work
🕐 Last Update: Nov 21, 2025 2:30 PM

📍 Next Actions:
  • Transition to VERIFYING
  • Transition to PLANNED (re-plan)
  • Transition to BLOCKED (if blocker found)

💡 Suggested: /ccpm:sync
   Save progress to Linear
   Confidence: 70%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

State Flow Diagram

START
  ↓
💡 IDEA (Plan your task)
  └─→ /ccpm:plan
      ↓
📋 PLANNED (Ready to start)
  ├─→ /ccpm:work
  │   ↓
🚀 IMPLEMENTING (In progress)
  │   ├─→ /ccpm:sync (save progress)
  │   ├─→ /ccpm:commit (commit changes)
  │   ├─→ /ccpm:verify (check completion)
  │   │   ↓
  │   └─→ 🚫 BLOCKED (if blocker found)
  │       └─→ /ccpm:verify
  │           ↓ (issue resolved)
  │           └─→ 🚀 IMPLEMENTING
  │
  └─→ /ccpm:verify (when checklist complete)
      ↓
🔍 VERIFYING (Quality checks)
  ├─→ /ccpm:verify (continue checks)
  │   ↓ (all checks pass)
  │   ↓
✅ VERIFIED (Ready to finalize)
  └─→ /ccpm:done (create PR + complete)
      ↓
🎉 COMPLETE (Done!)

Next Action Suggestions

Based on your current state, the skill suggests the best command to execute:

IDEA State

Current: 💡 IDEA
Question: What should I do next?

Suggested: /ccpm:plan "Task title" <project>
Description: Create implementation plan
Confidence: 90%
Reasoning: Task needs planning before implementation

PLANNED State

Current: 📋 PLANNED
Question: What should I do next?

Suggested: /ccpm:work
Description: Start implementation
Confidence: 90%
Reasoning: Plan is ready, begin development

IMPLEMENTING State (Early)

Current: 🚀 IMPLEMENTING (25% complete)
Question: What should I do next?

Suggested: /ccpm:sync
Description: Save progress to Linear
Confidence: 70%
Reasoning: Document what you've done so far

IMPLEMENTING State (Complete)

Current: 🚀 IMPLEMENTING (100% complete)
Question: What should I do next?

Suggested: /ccpm:verify
Description: Run quality checks
Confidence: 85%
Reasoning: Checklist complete, verify before completion

BLOCKED State

Current: 🚫 BLOCKED
Question: What should I do next?

Suggested: /ccpm:verify
Description: Diagnose and fix blocker
Confidence: 80%
Reasoning: Address blocking issue to continue

VERIFYING State

Current: 🔍 VERIFYING
Question: What should I do next?

Suggested: /ccpm:verify
Description: Continue verification process
Confidence: 80%
Reasoning: Complete all quality checks

VERIFIED State

Current: ✅ VERIFIED
Question: What should I do next?

Suggested: /ccpm:done
Description: Finalize and create PR
Confidence: 95%
Reasoning: Verification passed, ready to complete

COMPLETE State

Current: 🎉 COMPLETE
Status: Task is finished!
No further action needed.

Command-State Mapping

Understanding which commands cause which state transitions:

Command	From State	To State	Confidence
/ccpm:plan	IDEA	PLANNED	95%
/ccpm:plan	PLANNED	PLANNED	- (updates)
/ccpm:work	PLANNED	IMPLEMENTING	95%
/ccpm:sync	IMPLEMENTING	IMPLEMENTING	- (progress update)
/ccpm:commit	IMPLEMENTING	IMPLEMENTING	- (git commit)
/ccpm:verify	IMPLEMENTING	VERIFYING	85%
/ccpm:verify	VERIFYING	VERIFIED	85% (if checks pass)
/ccpm:verify	VERIFYING	IMPLEMENTING	100% (if checks fail)
/ccpm:done	VERIFIED	COMPLETE	95%
/ccpm:verify	BLOCKED	IMPLEMENTING	85%

Integration with Commands

State Auto-Update

These commands automatically update your workflow state in Linear:

• Planning commands: plan, planning:create, planning:plan, planning:update
• Implementation commands: work, implementation:start, implementation:sync
• Verification commands: verify, verification:check, verification:verify
• Completion commands: done, complete:finalize

Manual State Override

For edge cases, you can manually override state:

Task(linear-operations): `
operation: update_issue_state
params:
  issue_id: "PSN-29"
  phase: "IMPLEMENTING"
  reason: "Manual override due to external blocker"
context:
  command: "workflow-state-tracking:manual-override"
`

Blocked State Handling

When a blocker is detected, workflow transitions to BLOCKED:

Detecting Blockers

Blockers automatically detected by:
• Pre-condition validation failures
• Security audit failures
• Code review failures marked as blocking
• External dependency issues
• Permission/environment issues

Resolving Blockers

When BLOCKED:
1. Suggested command: /ccpm:verify
2. Diagnose the specific issue
3. Take corrective action
4. Re-run verification
5. Transition back to IMPLEMENTING

Example:

🚫 BLOCKED: Security audit detected vulnerabilities

Blocker Details:
  • SQL injection risk in user input handler
  • Missing CSRF token validation
  • Hardcoded API key in config

Suggestions:
  1. Fix: Parameterize database queries
  2. Fix: Add CSRF token middleware
  3. Fix: Move API key to environment variable

Status: /ccpm:verify

State Machine Queries

You can ask the skill for workflow information:

"Where am I?"

Returns current state with progress indicators and suggestions

"What can I do next?"

Shows valid transitions from current state

"Can I run this command now?"

Checks if command is allowed in current state

"What's blocking me?"

Shows any blockers preventing progression

"How much progress?"

Displays checklist completion percentage and phase progress

"Show me the workflow"

Visualizes the complete state machine and your position

Integration Example

Using State Tracking in a Workflow

Step 1: Check where you are
User: "Where am I in the workflow?"
Skill: "You're in PLANNING state. Your plan was created 2 hours ago."

Step 2: Get next suggestion
User: "What should I do next?"
Skill: "Suggested: /ccpm:work (90% confidence)"

Step 3: Start implementation
User: "/ccpm:work"
System: Transitions PLANNING → IMPLEMENTING

Step 4: Work on task
User: [Does actual implementation]

Step 5: Periodic sync
User: "/ccpm:sync"
System: Saves progress (stays in IMPLEMENTING)

Step 6: Check progress
User: "How much is done?"
Skill: "Checklist 85% complete. Nearly ready to verify."

Step 7: Finalize and verify
User: "/ccpm:verify"
System: Transitions IMPLEMENTING → VERIFYING

Step 8: All checks pass
System: Transitions VERIFYING → VERIFIED

Step 9: Finalize
User: "/ccpm:done"
System: Transitions VERIFIED → COMPLETE

Best Practices

Do's

• ✅ Check your state before starting work
• ✅ Follow suggested next actions
• ✅ Validate transitions before attempting them
• ✅ Sync progress regularly during implementation
• ✅ Ask for clarification if a transition is blocked

Don'ts

• ❌ Skip verification (IMPLEMENTING → COMPLETE)
• ❌ Re-open completed tasks (manually revert COMPLETE)
• ❌ Ignore blockers (resolve before continuing)
• ❌ Work without a plan (plan first)
• ❌ Force invalid transitions (follow state machine rules)

Troubleshooting

State Misalignment

If displayed state doesn't match reality:

1. Check Linear custom fields: ccpmPhase field
2. Fall back to Linear status inference
3. Analyze checklist completion
4. Check git status for uncommitted changes

If still misaligned:
  /ccpm:work PSN-29 (detailed state diagnostics)

Stuck in BLOCKED State

1. Identify blocker: /ccpm:work
2. Diagnose issue: /ccpm:verify
3. Fix root cause
4. Re-verify: /ccpm:verify
5. Return to IMPLEMENTING: Automatic on successful verification

Premature State Transition

If transitioned too early (e.g., PLANNING → VERIFYING):

1. Use /ccpm:plan to re-plan if needed
2. Or transition back to IMPLEMENTING: /ccpm:work
3. Complete actual implementation
4. Then proceed with verification

State Not Persisting

1. Check Linear write permissions
2. Verify custom fields exist: linear custom fields setup
3. Check Jira sync if using Jira integration
4. Review Linear comments for transition history

Related Documentation

• State Machine Definition
• Workflow Commands
• CCPM Workflow Guide
• Project Status Reports

Quick Reference

Phase Emojis

• 💡 IDEA
• 📋 PLANNED
• 🚀 IMPLEMENTING
• 🚫 BLOCKED
• 🔍 VERIFYING
• ✅ VERIFIED
• 🎉 COMPLETE
• ❌ CANCELLED

State Check Command

/ccpm:work <issue-id>

Workflow Visualization

/ccpm:work <issue-id>

Progress Report

/ccpm:sync <project>