natural-workflow

name	natural-workflow
description	Guide users through CCPM's streamlined 6-command workflow (plan/work/sync/commit/verify/done). Auto-activates when users ask about starting tasks, committing changes, or completing work. Provides step-by-step guidance for the complete development lifecycle.
activation-triggers	["How do I start working on a task","How do I commit my changes","I'm done with my work","How do I save my progress","What's the workflow","Create and plan a task","How do I verify my changes","Create a pull request","Complete a task","What commands should I use","Walk me through the process","How do I use CCPM"]

Natural Workflow Skill

Welcome to CCPM's natural workflow guide! This skill teaches you the 6-command lifecycle that takes you from task creation to completion.

Why Natural Workflow?

CCPM's natural workflow commands (plan, work, sync, commit, verify, done) are designed to feel intuitive and conversational, following the natural progression of development work:

1. Plan the work
2. Work on implementation
3. Sync progress to your team
4. Commit code changes
5. Verify quality
6. Done - complete and create PR

Instead of remembering complex command hierarchies like /ccpm:planning:create, /ccpm:implementation:start, or /ccpm:complete:finalize, you use simple verbs that match how you think about work.

The 6 Commands

1. /ccpm:plan - Create or Update Task Plans

The starting point for any work. This command intelligently detects what you want to do and helps you plan it.

What it does:

• Creates a new Linear task with a comprehensive implementation plan
• Plans an existing task that doesn't have a plan yet
• Updates an existing plan when requirements change

3 Modes:

# CREATE - New task
/ccpm:plan "Add user authentication"
/ccpm:plan "Fix login button" my-project JIRA-123

# PLAN - Plan existing task
/ccpm:plan PSN-27

# UPDATE - Change the plan
/ccpm:plan PSN-27 "Also add email notifications"

Behind the scenes:

• Auto-detects your project context
• Gathers research from Jira, Confluence, and codebase
• Generates implementation checklist (5-10 specific subtasks)
• Identifies files to modify
• Estimates complexity (low/medium/high)
• Saves everything to Linear

Next command: /ccpm:work

---

2. /ccpm:work - Start or Resume Implementation

Begin coding or resume work on an in-progress task.

What it does:

• Starts implementation if task is planned but not yet started
• Shows progress and next action if work is in progress
• Prevents accidental work on completed tasks

Usage:

# Auto-detect from branch name
/ccpm:work
# Works with branches like: feature/PSN-27-add-auth

# Explicit issue ID
/ccpm:work PSN-27

START mode (fresh task):

• Updates status to "In Progress"
• Analyzes codebase with smart agents
• Creates implementation plan in Linear
• Shows you what to do next

RESUME mode (continue work):

• Shows current progress (% complete)
• Lists remaining checklist items
• Suggests next action
• Shows quick command shortcuts

Next command: /ccpm:sync or /ccpm:commit

---

3. /ccpm:sync - Save Progress to Linear

Keep your team updated by syncing your progress to Linear.

What it does:

• Detects what you've changed in git
• Auto-marks checklist items as complete
• Adds progress comment to Linear
• Gives you a clear summary of work done

Usage:

# Auto-detect issue from branch
/ccpm:sync

# With custom summary
/ccpm:sync PSN-27 "Completed authentication endpoints"

# Auto-detect with summary
/ccpm:sync "Finished UI components"

Interactive mode:

• Shows all uncommitted changes
• AI analyzes your code changes against checklist items
• Suggests which items you completed
• Asks you to confirm (or manually select items)

Quick sync mode:

• If you provide a summary, skips the interactive part
• Just adds a comment with your summary
• Fast and simple

Next command: /ccpm:commit

---

4. /ccpm:commit - Create Conventional Git Commits

Make clean, meaningful git commits that follow best practices.

What it does:

• Auto-detects commit type (feat/fix/docs/etc) from your changes
• Generates meaningful commit message from issue context
• Links commits to Linear issues
• Follows conventional commits format

Usage:

# Auto-detect everything
/ccpm:commit

# With explicit message
/ccpm:commit "Add JWT token validation"

# Full conventional format
/ccpm:commit "fix(PSN-27): resolve login handler"

Smart detection:

• Extracts issue ID from your branch name
• Fetches issue title from Linear
• Analyzes changed files to determine commit type
• Generates professional commit message

Confirmation:

• Shows exactly what will be committed
• Lets you edit the message if needed
• Creates commit with all proper formatting

Output:

✅ Commit created successfully!
Commit: feat(PSN-27): Add user authentication
Next steps:
  /ccpm:sync        # Sync progress to Linear
  /ccpm:work        # Continue working
  git push          # Push to remote

Next command: /ccpm:verify

---

5. /ccpm:verify - Run Quality Checks and Verification

Before completing, make sure everything is production-ready.

What it does:

• Runs automated quality checks (linting, tests, build)
• Performs final code review and verification
• Identifies issues that need fixing
• Confirms work meets acceptance criteria

Usage:

# Auto-detect from branch
/ccpm:verify

# Explicit issue ID
/ccpm:verify PSN-27

Sequential checks:

1. Linting - Code style and format
2. Tests - Unit and integration tests pass
3. Build - Project builds successfully
4. Code Review - Final quality assessment
5. Verification - Acceptance criteria met

If issues found:

• Shows exactly what failed
• Suggests fixes
• Use /ccpm:verification:fix PSN-27 to get help fixing
• Run /ccpm:verify again once fixed

All clear?

• Shows "Ready for completion"
• Suggests: /ccpm:done PSN-27

Next command: /ccpm:done

---

6. /ccpm:done - Finalize and Create PR

Complete your work and get it ready for merge.

What it does:

• Creates GitHub pull request automatically
• Updates Linear status to "Done"
• Optionally syncs with Jira/Slack (with confirmation)
• Cleans up and summarizes the work

Usage:

# Auto-detect from branch
/ccpm:done

# Explicit issue ID
/ccpm:done PSN-27

Pre-flight checks:

1. ✅ On feature branch (not main/master)
2. ✅ All changes committed
3. ✅ Branch pushed to remote
4. ✅ Verification passed

PR Creation:

• Generates PR title from issue
• Creates description with checklist
• Links to related issues
• Sets reviewers if configured

Linear Update:

• Moves issue to "Done"
• Adds completion comment
• Closes task lifecycle

External Sync (if configured):

• Shows what will be posted to Slack/Jira
• Asks for explicit confirmation
• Only posts after you approve

Next: Your work is merged and complete!

---

Complete Workflow Examples

Example 1: Simple Feature (3 Commands)

Scenario: Adding a simple UI component

# 1. Create and plan
/ccpm:plan "Add dark mode toggle to settings"

# ... review the plan ...
# ✅ 4 subtasks
# 📁 2 files to modify
# ⚡ Complexity: Low

# 2. Start working
git checkout -b feature/PSN-30-dark-mode
/ccpm:work PSN-30

# ... write code, make commits ...
git commit -m "feat(PSN-30): add dark mode toggle"

# 3. Complete
/ccpm:verify PSN-30
/ccpm:done PSN-30

# ✅ PR created and ready for review!

Time spent on CCPM: ~2 minutes total Token usage: ~15k (vs 40k+ with manual approaches)

---

Example 2: Complex Feature with Changes (6 Commands)

Scenario: Adding user authentication with email notifications

# 1. Plan the work
/ccpm:plan "Add JWT authentication with email"
# Creates PSN-31 with 8 subtasks

# 2. Start implementation
git checkout -b duongdev/PSN-31-auth
/ccpm:work PSN-31

# ... write auth endpoints ...

# 3. Sync progress
/ccpm:sync PSN-31
# Shows: 3 files modified, +240 lines
# Marks checklist items complete

# 4. Continue implementation
# ... add email notifications ...

# 5. Commit changes
/ccpm:commit PSN-31
# Auto-generates: feat(PSN-31): Add JWT authentication

# 6. Fix a checklist requirement
# Realize: "Need to add password reset"
/ccpm:plan PSN-31 "Also add password reset flow"
# Updates plan, shows impact

# 7. Sync final changes
/ccpm:sync PSN-31 "Completed auth with password reset"

# 8. Verify everything
/ccpm:verify PSN-31
# ✅ Tests: 24/24 passing
# ✅ Linting: Clean
# ✅ Build: Success

# 9. Complete
/ccpm:done PSN-31
# PR created: "Add JWT authentication with email"
# Linear: Moved to Done

Workflow flexibility:

• Updated plan mid-way when requirements changed
• Synced progress multiple times
• Made meaningful commits throughout
• Verified quality before completion

---

Example 3: Bug Fix (Abbreviated Workflow)

Scenario: Fixing a login button that doesn't respond to clicks

# 1. Plan quick fix
/ccpm:plan "Fix login button click handler" my-app JIRA-456

# 2. Start and complete in one session
/ccpm:work PSN-32
# ... locate the bug ...
# ... fix it ...

# 3. Commit the fix
/ccpm:commit "fix: resolve login button click handler"

# 4. Verify
/ccpm:verify PSN-32
# ✅ No regression tests
# ✅ Build passes
# ✅ Fix verified

# 5. Complete
/ccpm:done PSN-32

Quick turnaround: 15 minutes total workflow

---

Auto-Detection Features

Git Branch Detection

All 6 commands can auto-detect your current issue from your git branch name:

# These branch names all work:
git checkout -b feature/PSN-27-add-auth
git checkout -b duongdev/PSN-27-add-auth
git checkout -b PSN-27-authentication

# Then these work without the issue ID:
/ccpm:work          # Auto-detects PSN-27
/ccpm:sync          # Auto-detects PSN-27
/ccpm:commit        # Auto-detects PSN-27
/ccpm:verify        # Auto-detects PSN-27
/ccpm:done          # Auto-detects PSN-27

Smart Context from Linear

Commands automatically fetch information from Linear:

• Issue title → Used in commit messages, PR titles, and summaries
• Implementation checklist → Updated as you sync progress
• Team/project → Used for proper organization
• Status → Updated automatically at each step

Code Analysis

When you run /ccpm:sync, the system:

• Analyzes your git changes
• Matches files modified against checklist items
• Suggests which items you completed
• Pre-selects high-confidence matches

---

Best Practices

When to Sync

Sync frequently during long tasks:

• After implementing each major feature
• Before switching to a different task
• When taking a break
• Multiple times per day

# Don't wait until the end
/ccpm:sync "Completed JWT endpoints"
# ... more work ...
/ccpm:sync "Added token refresh logic"
# ... more work ...
/ccpm:sync "Implemented logout"

Branch Naming for Auto-Detection

Use a consistent pattern:

# Good - includes issue ID clearly
feature/PSN-27-add-auth
duongdev/PSN-27-add-auth
PSN-27

# Also works
PSN-27-authentication
feature-PSN-27

Commit Frequency

Commit often, sync progress:

# Three small commits
git commit -m "feat(PSN-27): add auth endpoints"
git commit -m "feat(PSN-27): add JWT validation"
git commit -m "feat(PSN-27): add login form"

# One sync to update checklist
/ccpm:sync "Completed auth implementation"

Plan Updates During Implementation

If requirements change, update the plan:

# Original plan: Basic email notifications
/ccpm:plan PSN-31

# ... midway through, discover: Need SMS too
/ccpm:plan PSN-31 "Also add SMS notifications"

# System shows impact, you decide
# Continue with updated scope or simplify

Before /ccpm:done

Ensure three things:

1. All committed - No uncommitted changes
2. Branch pushed - Your feature branch on remote
3. Verification passed - /ccpm:verify shows green

---

When to Use Each Command

Use /ccpm:plan

• Starting a new task
• Requirements changed mid-project
• Need to break down complex work
• Setting up clear checklist

Use /ccpm:work

• Beginning implementation
• Resuming after a break
• Checking what's next in checklist
• Setting up proper context

Use /ccpm:sync

• After completing a significant piece
• Multiple times during long tasks
• When switching to different work
• Before taking a break

Use /ccpm:commit

• Every meaningful set of changes
• After testing locally
• When ready to push
• Before verification

Use /ccpm:verify

• Before declaring work complete
• When you think all checklist items done
• Before creating PR
• To catch issues early

Use /ccpm:done

• All checks passing
• Ready for code review
• Team needs to see your PR
• Task should be marked complete

---

Integration with Other CCPM Commands

For More Detailed Control

If you need more control than natural workflow provides:

# Instead of:
/ccpm:plan "title"

# Use detailed version:
/ccpm:planning:create "title" project-id jira-ticket

# Instead of:
/ccpm:work PSN-29

# Use:
/ccpm:implementation:start PSN-29

# Instead of:
/ccpm:sync PSN-29

# Use:
/ccpm:implementation:sync PSN-29 "detailed summary"

# Instead of:
/ccpm:done PSN-29

# Use:
/ccpm:complete:finalize PSN-29

Natural workflow versions are optimized for the common path. Detailed versions provide more options.

Utilities and Monitoring

Check your progress anytime:

# View current status
/ccpm:utils:status PSN-29

# See what's next
/ccpm:utils:dependencies PSN-29

# View project progress
/ccpm:utils:report my-project

# Get insights
/ccpm:utils:insights PSN-29

---

Error Scenarios and Recovery

Issue Not Found

❌ Error fetching issue: Issue not found

Suggestions:
  - Verify the issue ID is correct (format: PROJ-123)
  - Check you have access to this Linear team
  - Ensure the issue hasn't been deleted

Fix: Double-check the issue ID and team access

Branch Detection Failed

❌ Could not detect issue ID from branch

Current branch: main

Usage: /ccpm:work [ISSUE-ID]
Example: /ccpm:work PSN-29

Fix: Either:

• Rename your branch to include issue ID
• Provide issue ID explicitly: /ccpm:work PSN-29

Uncommitted Changes

⚠️  You have uncommitted changes

Please commit first:
  /ccpm:commit

Fix: Run /ccpm:commit to stage and commit your changes

Verification Failed

❌ Tests failed: 2 failures in __tests__/auth.test.ts

Use `/ccpm:verification:fix PSN-29` to get help

Fix:

• Review the failure
• Fix the code
• Run tests locally
• Run /ccpm:verify again

---

Common Workflows by Project Type

Web Application (React/Node)

/ccpm:plan "Add user dashboard page"
git checkout -b feature/PSN-40-dashboard
/ccpm:work PSN-40

# ... implement React components ...
npm test                    # Test locally
/ccpm:commit               # Commit with auto-format
/ccpm:sync "UI complete"   # Update checklist

# ... implement backend API ...
/ccpm:sync "API endpoints done"
npm test && npm run build   # Verify locally
/ccpm:verify PSN-40        # Run CCPM verification
/ccpm:done PSN-40         # Create PR

API/Backend Service

/ccpm:plan "Add user authentication endpoint"
git checkout -b feature/PSN-41-auth-api
/ccpm:work PSN-41

# ... implement endpoint ...
/ccpm:commit "feat: add JWT authentication"
/ccpm:sync "Auth endpoints complete"

# ... add tests ...
/ccpm:commit "test: add auth endpoint tests"
/ccpm:verify PSN-41
/ccpm:done PSN-41

Documentation/Config

/ccpm:plan "Update API documentation"
git checkout -b feature/PSN-42-docs
/ccpm:work PSN-42

# ... update markdown files ...
/ccpm:commit "docs: update API docs"
/ccpm:verify PSN-42    # Builds docs, validates
/ccpm:done PSN-42     # Simpler verification for docs

---

Tips for Success

1. Plan first - Taking 5 minutes to plan saves 30 minutes of rework
2. Sync regularly - Don't wait until done; update progress throughout
3. Use meaningful commits - Small, focused commits are easier to review
4. Check before verifying - Run tests locally before /ccpm:verify
5. Read error messages - They tell you exactly what's needed
6. Take advantage of auto-detection - Use good branch naming to save typing
7. Ask for help - Run commands again or use detailed versions if stuck

---

Next Steps

Ready to start? Pick an approach:

If you have a task to start:

/ccpm:plan "your task description"

If you're already working on something:

/ccpm:work          # Auto-detect from branch

If you just finished some work:

/ccpm:sync          # Save progress
/ccpm:verify        # Check quality
/ccpm:done         # Complete

If you need help:

/ccpm:utils:status PSN-29
/ccpm:utils:help

---

Summary

The natural workflow is designed to be intuitive, efficient, and powerful:

Command	Purpose	Time	Tokens
/ccpm:plan	Create & plan task	1-2 min	~2.5k
/ccpm:work	Start implementation	30 sec	~5k
/ccpm:sync	Update progress	1 min	~2.1k
/ccpm:commit	Make git commit	30 sec	~1.5k
/ccpm:verify	Quality checks	1-2 min	~2.8k
/ccpm:done	Complete & PR	1 min	~2.1k

Total typical workflow: 5-10 minutes, ~16k tokens (vs 40-50 minutes, 50k+ tokens with manual approaches)

Happy shipping! 🚀