natural-workflow

What this skill does

# 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:plan`, `/ccpm:work`, or `/ccpm:done`, 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:verify 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:**

```bash
# 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

```bash
# 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

```bash
# 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: Succes