### Quick Reference - Start Issue

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Begin working on a specific GitHub issue by referencing its number.

```natural language
"start working on issue 42"
```

--------------------------------

### Clone CCPM Repository

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Clone the CCPM repository to your local machine to begin installation.

```bash
git clone https://github.com/automazeio/ccpm.git
```

--------------------------------

### Natural Language Trigger Examples

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Examples of natural language commands to trigger CCPM functionalities, such as planning, structuring, syncing, and executing tasks.

```markdown
"I want to build a notification system — push, email, and in-app"
```

```markdown
"parse the notification-system PRD"
```

```markdown
"break down the notification-system epic into tasks"
```

```markdown
"sync the notification-system epic to GitHub"
```

```markdown
"start working on issue 42"
```

```markdown
"standup" / "what's blocked" / "what's next"
```

--------------------------------

### Install CCPM for Factory / Droid

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Symlink the CCPM skill into your .factory/skills directory for use with Factory or Droid harnesses.

```bash
# Symlink into your skills directory
ln -s /path/to/ccpm/skill/ccpm ~/.factory/skills/ccpm
```

--------------------------------

### Interactive Workflow Examples

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Demonstrates typical user interactions and the expected CCPM responses throughout the project management lifecycle, from initial requests to daily standups.

```text
"I want to build a notification system — where do we start?"
→ Guided brainstorming + PRD creation

"break down the notification-system epic"
→ Parallelizable task files with dependencies

"sync the notification-system epic to GitHub"
→ Epic issue + sub-issues + worktree

"start working on issue 42"
→ Parallel stream analysis + multiple agents launched

"what's our standup for today?"
→ Instant report from project files
```

--------------------------------

### Handle GitHub CLI Failures

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

This pattern demonstrates how to execute a GitHub CLI command and provide a helpful message if it fails, guiding the user to authenticate.

```bash
gh <command> || echo "❌ GitHub CLI failed. Run: gh auth login"
```

--------------------------------

### Prerequisites for CCPM

Source: https://context7.com/automazeio/ccpm/llms.txt

Commands to authenticate the GitHub CLI and optionally install the gh-sub-issue extension for enhanced issue linking.

```bash
gh auth login
```

```bash
gh extension install yahsan2/gh-sub-issue
```

--------------------------------

### Show Next Available Tasks (Priority Queue)

Source: https://context7.com/automazeio/ccpm/llms.txt

This script displays the next tasks that are ready to be started, indicating which ones can run in parallel. It summarizes the number of ready tasks.

```bash
bash skill/ccpm/references/scripts/next.sh
```

--------------------------------

### Run Project Status Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Execute the status script to get an overview of the project's current state. This is a deterministic operation.

```bash
bash references/scripts/status.sh
```

--------------------------------

### Install CCPM for Claude Code

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Create a skills directory in your project root and symlink or copy the CCPM skill for use with Claude Code.

```bash
ln -s /path/to/ccpm/skill/ccpm .claude/skills/ccpm
```

--------------------------------

### Get GitHub Issue Details

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Use the GitHub CLI to fetch issue details like title, body, and labels for analysis.

```bash
gh issue view <N> --json title,body,labels
```

--------------------------------

### Install gh-sub-issue Extension

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Command to install the `gh-sub-issue` GitHub CLI extension, which is used by CCPM for managing parent-child relationships between issues. Falls back to task lists if not installed.

```bash
gh extension install yahsan2/gh-sub-issue
```

--------------------------------

### Start Working on an Issue with Parallel Agents

Source: https://context7.com/automazeio/ccpm/llms.txt

This conceptual representation shows how task agents are launched for parallel work streams of an issue. It includes a prompt for a 'general-purpose' subagent, detailing its task, scope, files, and instructions for committing and updating progress.

```yaml
# The agent launches Task agents — conceptual representation:
Task:
  description: "Issue #1235 Stream A — FCM Client"
  subagent_type: "general-purpose"
  prompt: |
    You are working on Issue #1235 in the epic worktree at: ../epic-notification-system/

    Your stream: FCM Client
    Your scope — files to modify:
      - src/services/push/fcm.ts
      - src/types/push.ts

    Instructions:
    1. Read full task from: .claude/epics/notification-system/1235.md
    2. Read analysis from: .claude/epics/notification-system/1235-analysis.md
    3. Work ONLY in your assigned files
    4. Commit frequently: "Issue #1235: <specific change>"
    5. Update progress in: .claude/epics/notification-system/updates/1235/stream-A.md
    6. Never use --force on git operations

    Complete your stream's work and mark status: completed when done.
```

--------------------------------

### Check Git Status

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Verify that there are no uncommitted changes in the repository before starting a full epic.

```bash
git status --porcelain
```

--------------------------------

### PRD Frontmatter Schema

Source: https://context7.com/automazeio/ccpm/llms.txt

Example frontmatter for a Product Requirements Document (PRD) file, including metadata like name, description, status, and creation timestamp.

```yaml
---
name: notification-system
description: Multi-channel notification delivery — push, email, in-app
status: backlog
created: 2026-03-18T09:00:00Z
---

# PRD: notification-system

## Executive Summary
## Problem Statement
## User Stories
## Functional Requirements
## Non-Functional Requirements
## Success Criteria
## Constraints & Assumptions
## Out of Scope
## Dependencies

```

--------------------------------

### Create Task Files Batch

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/structure.md

Use this Task tool configuration to create batches of task files for an epic. Specify the epic name, the tasks to create, and the save location. The prompt guides the agent on the required format and output.

```yaml
Task:
  description: "Create task files batch N"
  subagent_type: "general-purpose"
  prompt: |
    Create task files for epic: <name>
    Tasks to create: [list 3-4 tasks]
    Save to: .claude/epics/<name>/001.md, 002.md, etc.
    Follow the task file format exactly.
    Return: list of files created.
```

--------------------------------

### Task Frontmatter Schema

Source: https://context7.com/automazeio/ccpm/llms.txt

Example frontmatter for a task file generated from an epic, including name, status, timestamps, GitHub issue link, dependencies, and parallelization flags.

```yaml
---
name: Push Notification Service
status: open
created: 2026-03-18T09:10:00Z
updated: 2026-03-18T09:10:00Z
github: (will be set on sync)
depends_on: []
parallel: true
conflicts_with: []
---

# Task: Push Notification Service

## Description
Implement the FCM/APNs push notification delivery service.

```

--------------------------------

### Epic Frontmatter Schema

Source: https://context7.com/automazeio/ccpm/llms.txt

Example frontmatter for a Technical Epic file, detailing metadata such as name, status, creation/update times, associated PRD, and GitHub issue link.

```yaml
---
name: notification-system
status: backlog
created: 2026-03-18T09:05:00Z
updated: 2026-03-18T09:05:00Z
progress: 0%
prd: .claude/prds/notification-system.md
github: (will be set on sync)
---

# Epic: notification-system

## Overview
## Architecture Decisions
## Technical Approach
### Frontend Components
### Backend Services
### Infrastructure
## Implementation Strategy
## Task Breakdown Preview
## Dependencies
## Success Criteria (Technical)
## Estimated Effort

```

--------------------------------

### Display Project Status

Source: https://context7.com/automazeio/ccpm/llms.txt

Run this script to get a summary of the project's current status, including counts of PRDs, epics, and tasks (open, closed, total).

```bash
bash skill/ccpm/references/scripts/status.sh
```

--------------------------------

### Get PRD Status Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Retrieve the status of Product Requirement Documents (PRDs) by running the prd-status script. This is a deterministic operation.

```bash
bash references/scripts/prd-status.sh
```

--------------------------------

### Get Epic Status Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Check the status of a particular epic by running the epic-status script with the epic's name. This is a deterministic operation.

```bash
bash references/scripts/epic-status.sh <name>
```

--------------------------------

### Strip Frontmatter to Get Body Content

Source: https://context7.com/automazeio/ccpm/llms.txt

This `sed` command removes frontmatter from a file, extracting only the body content. This is useful for sync operations where only the main content is needed.

```bash
sed '1,/^---$/d; 1,/^---$/d' .claude/epics/notification-system/epic.md > /tmp/body.md
```

--------------------------------

### Strip Frontmatter to Get Body Content

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

This command removes the frontmatter (delimited by '---') from a file, outputting only the body content. Useful for preparing content for systems like GitHub.

```bash
sed '1,/^---$/d; 1,/^---$/d' <file> > /tmp/body.md
```

--------------------------------

### Get Current UTC Datetime

Source: https://context7.com/automazeio/ccpm/llms.txt

This command captures the current date and time in UTC format, ensuring accurate timestamps for operations. It's recommended to use this over placeholder text.

```bash
current_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
```

--------------------------------

### Analyze Issue for Parallel Work Streams

Source: https://context7.com/automazeio/ccpm/llms.txt

This YAML file defines the analysis of an issue for parallelization. It includes estimated hours, parallelization factor, and breaks down the issue into independent work streams with their scope, files, start times, and estimated hours.

```yaml
# .claude/epics/notification-system/1235-analysis.md
---
issue: 1235
title: Push Notification Service
analyzed: 2026-03-18T09:30:00Z
estimated_hours: 14
parallelization_factor: 2.8
---

# Parallel Work Analysis: Issue #1235

## Parallel Streams

### Stream A: FCM Client
**Scope**: Google FCM integration
**Files**: src/services/push/fcm.ts, src/types/push.ts
**Can Start**: immediately
**Estimated Hours**: 4
**Dependencies**: none

### Stream B: APNs Client
**Scope**: Apple APNs integration
**Files**: src/services/push/apns.ts
**Can Start**: immediately
**Estimated Hours**: 4
**Dependencies**: none

### Stream C: Push Service Facade + Tests
**Scope**: Unified service interface and test suite
**Files**: src/services/push/index.ts, tests/push.test.ts
**Can Start**: after Stream A and B
**Dependencies**: Stream A, Stream B

## Expected Timeline
- With parallel execution: 9h wall time
- Without: 14h
- Efficiency gain: 36%
```

--------------------------------

### Initialize Project

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/track.md

Initializes the project if the .claude/ directory does not exist.

```bash
bash references/scripts/init.sh
```

--------------------------------

### Initialize CCPM Project

Source: https://context7.com/automazeio/ccpm/llms.txt

Script to initialize a new project with CCPM, checking for prerequisites like the GitHub CLI and creating necessary directories and labels.

```bash
bash skill/ccpm/references/scripts/init.sh
```

--------------------------------

### Get Current UTC Datetime

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

Always use this command to get the current UTC datetime for timestamps. Ensures consistency across operations.

```bash
date -u +"%Y-%m-%dT%H:%M:%SZ"
```

--------------------------------

### Quick Reference - What's Next

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Inquire about the next recommended tasks or priorities.

```natural language
"what should I work on next"
```

--------------------------------

### Quick Reference - Plan Feature

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Initiate the planning phase for a new feature by stating the intent to build or create a PRD.

```natural language
"I want to build X" or "create a PRD for X"
```

--------------------------------

### Quick Reference - Sync Epic to GitHub

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Synchronize a technical epic and its associated tasks to GitHub as issues.

```natural language
"push the X epic to GitHub"
```

--------------------------------

### Create Update Directory for Issue Streams

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Prepare the directory structure for tracking updates and progress of individual streams within an issue.

```bash
mkdir -p .claude/epics/<epic>/updates/<N>
current_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
```

--------------------------------

### Search Project Files

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/track.md

Searches local task files, PRDs, and epics for a given query term.

```bash
bash references/scripts/search.sh "<query>"
```

--------------------------------

### Run Tracking Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/track.md

General command to run tracking scripts. Ensure you are in the project root directory.

```bash
bash <skill_path>/references/scripts/<script>.sh [args]
```

```bash
bash ccpm/scripts/pm/<script>.sh [args]
```

--------------------------------

### List All Project Epics

Source: https://context7.com/automazeio/ccpm/llms.txt

Use this script to list all epics in the project, categorized by their status (Planning, In Progress, Completed). It provides details on task counts and completion percentages.

```bash
bash skill/ccpm/references/scripts/epic-list.sh
```

--------------------------------

### Create Parallel Work Analysis File

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Generate a markdown file to document the analysis of parallel work streams for a GitHub issue.

```markdown
---
issue: <N>
title: <title>
analyzed: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
estimated_hours: <total>
parallelization_factor: <1.0-5.0>
---

# Parallel Work Analysis: Issue #<N>

## Overview

## Parallel Streams

### Stream A: <Name>
**Scope**: 
**Files**: 
**Can Start**: immediately
**Estimated Hours**: 
**Dependencies**: none

### Stream B: <Name>
**Scope**: 
**Files**: 
**Can Start**: after Stream A
**Dependencies**: Stream A

## Coordination Points
### Shared Files
### Sequential Requirements

## Conflict Risk Assessment

## Parallelization Strategy

## Expected Timeline
- With parallel execution: <max_stream_hours>h wall time
- Without: <sum_all_hours>h
- Efficiency gain: <pct>%

```

--------------------------------

### Quick Reference - Parse PRD to Epic

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Convert a Product Requirement Document (PRD) into a technical epic.

```natural language
"turn the X PRD into an epic"
```

--------------------------------

### Create Execution Status File

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Generate a markdown file to provide an overview of the execution status for all streams of an issue, including active, queued, and completed streams.

```markdown
## Active Streams
- Stream A: <name> — Started <time>
- Stream B: <name> — Started <time>

## Queued
- Stream C: <name> — Waiting on Stream A

## Completed
(none yet)

```

--------------------------------

### Quick Reference - Check Status

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Request a general status update for the project or initiate a standup report.

```natural language
"what's our status" / "standup"
```

--------------------------------

### Clone and Link CCPM Skill

Source: https://context7.com/automazeio/ccpm/llms.txt

Instructions for cloning the CCPM repository and linking the skill to your project for use with Claude Code or Factory/Droid.

```bash
git clone https://github.com/automazeio/ccpm.git
```

```bash
ln -s /path/to/ccpm/skill/ccpm .claude/skills/ccpm
```

```bash
ln -s /path/to/ccpm/skill/ccpm ~/.factory/skills/ccpm
```

--------------------------------

### View Original Issue Details

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

Use this command to retrieve the title, body, and labels of an original GitHub issue. This is the first step in reporting a bug against an existing issue to gather necessary context.

```bash
gh issue view <original_N> --json title,body,labels
```

--------------------------------

### Show In-Progress Items Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

View a list of all items currently in progress by running the in-progress script. This is a deterministic operation.

```bash
bash references/scripts/in-progress.sh
```

--------------------------------

### CCPM Local Project Structure

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Illustrates the directory structure for CCPM project files within the `.claude/` directory in the project root. This includes storage for PRDs, epics, and agent progress tracking.

```tree
.claude/
├── prds/                     # Product requirement documents
├── epics/ 
│   └── <feature>/
│       ├── epic.md           # Technical epic
│       ├── <N>.md            # Task files (named by GitHub issue number after sync)
│       ├── <N>-analysis.md   # Parallel work stream analysis
│       └── updates/          # Agent progress tracking
└── (archived epics)
```

--------------------------------

### Quick Reference - Merge Epic

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Finalize and merge a completed epic.

```natural language
"merge the X epic"
```

--------------------------------

### Assign Issue and Add Label

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Use the GitHub CLI to assign the current user to an issue and add an 'in-progress' label.

```bash
gh issue edit <N> --add-assignee @me --add-label "in-progress"
```

--------------------------------

### Create Stream Progress File

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Generate a markdown file to track the progress and status of a specific work stream for an issue.

```markdown
---
issue: <N>
stream: <stream_name>
started: <datetime>
status: in_progress
---
## Scope
## Progress
- Starting implementation

```

--------------------------------

### Run Standup Report Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Generate a standup report by running the dedicated bash script. This is a deterministic operation for tracking daily progress.

```bash
bash references/scripts/standup.sh
```

--------------------------------

### Generate Daily Standup Report

Source: https://context7.com/automazeio/ccpm/llms.txt

This script generates a daily standup report, detailing today's activity, currently in-progress issues, and next available tasks. It also includes quick stats.

```bash
bash skill/ccpm/references/scripts/standup.sh
```

--------------------------------

### Task File Format

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/structure.md

Defines the standard structure for individual task files within an epic. Includes metadata like name, status, creation/update timestamps, GitHub sync status, dependencies, and parallelization flags. Also outlines the main content sections for the task.

```markdown
---
name: <Task Title>
status: open
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
updated: <same as created>
github: (will be set on sync)
depends_on: []
parallel: true
conflicts_with: []
---

# Task: <Task Title>

## Description

## Acceptance Criteria
- [ ]

## Technical Details

## Dependencies

## Effort Estimate
- Size: XS/S/M/L/XL
- Hours: N

## Definition of Done
- [ ] Code implemented
- [ ] Tests written and passing
- [ ] Code reviewed

```

--------------------------------

### CCPM Workflow Diagram

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Illustrates the sequential flow of the CCPM project management workflow, from initial PRD creation to parallel execution.

```mermaid
graph LR
    A[PRD Creation] --> B[Epic Planning]
    B --> C[Task Decomposition]
    C --> D[GitHub Sync]
    D --> E[Parallel Execution]
```

--------------------------------

### Quick Reference - Decompose Epic

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Break down a technical epic into smaller, manageable tasks.

```natural language
"break down the X epic into tasks"
```

--------------------------------

### Identify Blocked Tasks

Source: https://context7.com/automazeio/ccpm/llms.txt

Run this script to identify tasks that are currently blocked. It shows which tasks are blocked, by which other tasks, and what they are waiting for.

```bash
bash skill/ccpm/references/scripts/blocked.sh
```

--------------------------------

### Create Epic Branch and Worktree

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

This sequence of commands ensures the local main branch is up-to-date, then creates a new worktree and a corresponding Git branch for an epic.

```bash
git checkout main && git pull origin main
git worktree add ../epic-<name> -b epic/<name>
```

--------------------------------

### View GitHub Issue

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Check if a GitHub issue exists and retrieve its state, title, labels, and body.

```bash
gh issue view <N> --json state,title,labels,body
```

--------------------------------

### Search Across All Project Files

Source: https://context7.com/automazeio/ccpm/llms.txt

This script searches for a given keyword across all project files, including PRDs, Epics, and Tasks. It reports the number of matches per category and the total number of files with matches.

```bash
bash skill/ccpm/references/scripts/search.sh "stripe"
```

--------------------------------

### Update Frontmatter with GitHub URL and Date

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This script updates the `github:` and `updated:` fields in local task and epic files. It constructs the GitHub URL and formats the current date in UTC. A backup file is created and then removed.

```bash
current_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Update github: and updated: fields in epic.md and each task file
github_url="https://github.com/$REPO/issues/<number>"
sed -i.bak "/^github:/c\github: $github_url" <file>
sed -i.bak "/^updated:/c\updated: $current_date" <file>
rm <file>.bak
```

--------------------------------

### PRD Frontmatter and Structure

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/plan.md

Use this markdown structure for creating a Product Requirements Document (PRD). Ensure all fields are filled and adhere to the specified format.

```markdown
---
name: <feature-name>
description: <one-line summary>
status: backlog
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
---

# PRD: <feature-name>

## Executive Summary
## Problem Statement
## User Stories
## Functional Requirements
## Non-Functional Requirements
## Success Criteria
## Constraints & Assumptions
## Out of Scope
## Dependencies

```

--------------------------------

### List PRDs Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Generate a list of all Product Requirement Documents (PRDs) by executing the prd-list script. This is a deterministic operation.

```bash
bash references/scripts/prd-list.sh
```

--------------------------------

### Repository Safety Check Before GitHub Write

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

Run this script before any GitHub write operation to ensure you are not syncing to the CCPM template repository. It checks the origin URL and exits if it matches. Update the remote URL if necessary.

```bash
remote_url=$(git remote get-url origin 2>/dev/null || echo "")
if [[ "$remote_url" == *"automazeio/ccpm"* ]]; then
  echo "❌ Cannot sync to the CCPM template repository."
  echo "Update remote: git remote set-url origin https://github.com/YOUR/REPO.git"
  exit 1
fi
REPO=$(echo "$remote_url" | sed 's|.*github.com[:/]|' | sed 's|\.git$||')
```

--------------------------------

### Sync Epic and Tasks to GitHub Issues

Source: https://context7.com/automazeio/ccpm/llms.txt

This process synchronizes an epic and its associated tasks to GitHub Issues. It includes creating the epic issue, sub-issues for tasks, renaming local files to match GitHub issue numbers, updating frontmatter, and setting up a Git worktree for parallel development.

```bash
# Natural language trigger:
"sync the notification-system epic to GitHub"
"push the notification-system epic to GitHub"

# The agent runs these operations internally:

# Step 1 — Repository safety check (prevents accidental writes to the CCPM template repo)
remote_url=$(git remote get-url origin 2>/dev/null || echo "")
if [[ "$remote_url" == *"automazeio/ccpm"* ]]; then
  echo "❌ Cannot sync to the CCPM template repository."
  exit 1
fi
REPO=$(echo "$remote_url" | sed 's|.*github.com[:/]||' | sed 's|\.git$||')

# Step 2 — Create the epic issue
sed '1,/^---$/d; 1,/^---$/d' .claude/epics/notification-system/epic.md > /tmp/epic-body.md
epic_number=$(gh issue create \
  --repo "$REPO" \
  --title "Epic: notification-system" \
  --body-file /tmp/epic-body.md \
  --label "epic,epic:notification-system,feature" \
  --json number -q .number)

# Step 3 — Create a sub-issue for each task
sed '1,/^---$/d; 1,/^---$/d' .claude/epics/notification-system/001.md > /tmp/task-body.md
task_number=$(gh issue create \
  --repo "$REPO" \
  --title "Push Notification Service" \
  --body-file /tmp/task-body.md \
  --label "task,epic:notification-system" \
  --json number -q .number)
# With gh-sub-issue extension: gh sub-issue create --parent $epic_number ...

# Step 4 — Rename local files to match GitHub issue numbers
mv .claude/epics/notification-system/001.md .claude/epics/notification-system/1235.md

# Step 5 — Update github: frontmatter field
sed -i.bak "/^github:/c\github: https://github.com/$REPO/issues/$task_number" \
  .claude/epics/notification-system/1235.md
rm .claude/epics/notification-system/1235.md.bak

# Step 6 — Create dedicated worktree for parallel work
git checkout main && git pull origin main
git worktree add ../epic-notification-system -b epic/notification-system

# Output:
# ✅ Synced epic notification-system to GitHub
#   Epic: #1234
#   Tasks: 4 sub-issues (#1235–#1238)
#   Worktree: ../epic-notification-system

```

--------------------------------

### Update Task File References

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This script demonstrates how to update task file references by using `sed` to replace old sequential numbers with new issue numbers and then renaming the file. It creates a backup before modification.

```bash
# Build old→new mapping, then for each task file:
sed -i.bak "s/\b001\b/<new_num_1>/g" <file>  # repeat for each mapping
mv 001.md <new_num>.md
```

--------------------------------

### Post Progress Update to GitHub Issue

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This command posts a formatted progress update to a GitHub issue. The body of the comment is read from a temporary file containing structured sections for completed work, notes, and next steps.

```bash
gh issue comment <N> --body-file /tmp/update-comment.md
```

--------------------------------

### Create Task Sub-Issue on GitHub

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This command creates a task sub-issue on GitHub. It strips frontmatter from the task file, creates the issue, and labels it. An alternative using the `gh-sub-issue` extension is commented out.

```bash
sed '1,/^---$/d; 1,/^---$/d' <task_file> > /tmp/task-body.md
task_number=$(gh issue create \
  --repo "$REPO" \
  --title "<task_name>" \
  --body-file /tmp/task-body.md \
  --label "task,epic:<name>" \
  --json number -q .number)
# or with sub-issues:
# gh sub-issue create --parent $epic_number ...
```

--------------------------------

### Quick Reference - Report Bug

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Report a bug discovered during testing or development, linking it to a specific issue.

```natural language
"found a bug in issue 42" / "testing issue 42 revealed X"
```

--------------------------------

### Show Blocked Items Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

List all items that are currently blocked by running the blocked script. This is a deterministic operation.

```bash
bash references/scripts/blocked.sh
```

--------------------------------

### List All Epics Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Retrieve a list of all epics by executing the epic-list script. This is a deterministic operation for project overview.

```bash
bash references/scripts/epic-list.sh
```

--------------------------------

### Create Epic Issue on GitHub

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This command creates an epic issue on GitHub by stripping frontmatter from the local epic file and using `gh issue create`. It labels the issue and outputs its number.

```bash
sed '1,/^---$/d; 1,/^---$/d' .claude/epics/<name>/epic.md > /tmp/epic-body.md
epic_number=$(gh issue create \
  --repo "$REPO" \
  --title "Epic: <name>" \
  --body-file /tmp/epic-body.md \
  --label "epic,epic:<name>,feature" \
  --json number -q .number)
```

--------------------------------

### Update Single Frontmatter Field

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

Use this command to update a specific field in a file's frontmatter. Creates a backup file (.bak) before modification.

```bash
sed -i.bak "/^<field>:/c\\<field>: <value>" <file>
rm <file>.bak
```

--------------------------------

### Epic Summary Format

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/structure.md

Appends a summary to the epic file after tasks are created. Lists created tasks with their titles and parallelization status, along with counts for total, parallel, and sequential tasks, and the estimated total effort.

```markdown
## Tasks Created
- [ ] 001.md - <Title> (parallel: true/false)
- [ ] 002.md - <Title> (parallel: true/false)

Total tasks: N
Parallel tasks: N
Sequential tasks: N
Estimated total effort: N hours

```

--------------------------------

### Bug Report Markdown Template

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This is a template for creating a local markdown file for a bug report. It includes fields for context, description, steps to reproduce, expected vs actual behavior, acceptance criteria, and effort estimate. The `bug_for` field links it to the original issue.

```markdown
---
name: Bug: <short description>
status: open
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
updated: <same>
github: (will be set on sync)
depends_on: []
parallel: false
conflicts_with: []
bug_for: <original_N>
---

# Bug: <short description>

## Context
Found while working on / testing issue #<original_N>: <original title>

## Description
<what's broken>

## Steps to Reproduce
<steps>

## Expected vs Actual
- Expected: 
- Actual: 

## Acceptance Criteria
- [ ] Bug is fixed
- [ ] Original issue #<original_N> behaviour is unaffected

## Effort Estimate
- Size: XS/S

```

--------------------------------

### Show Epic Details Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Display detailed information about a specific epic by providing its name to the epic-show script. This is a deterministic operation.

```bash
bash references/scripts/epic-show.sh <name>
```

--------------------------------

### Validate Project State Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Validate the overall state of the project by running the validate script. This is a deterministic operation.

```bash
bash references/scripts/validate.sh
```

--------------------------------

### Agent Coordination Rules for Commits

Source: https://context7.com/automazeio/ccpm/llms.txt

This bash snippet outlines the agent coordination rule for committing work within a worktree, specifying the format for commit messages to ensure clarity and traceability.

```bash
# Agent coordination rules inside the worktree:
# - Each agent commits with: git commit -m "Issue #1235: add FCM token refresh logic"
```

--------------------------------

### CCPM Naming Conventions

Source: https://context7.com/automazeio/ccpm/llms.txt

Outlines the standard naming conventions used within the CCPM project for features, tasks, branches, worktrees, commits, and labels.

```text
Feature names:    kebab-case — user-auth, payment-v2, notification-system
Task files:       001.md, 002.md, ... (before sync) → 1234.md (after sync, GitHub issue number)
Epic branch:      epic/<feature-name>
Worktree path:    ../epic-<feature-name>/  (sibling to project root)
Commit format:    Issue #<N>: <description>
Labels (epic):    epic, epic:<name>, feature
Labels (task):    task, epic:<name>
Labels (bug):     bug, epic:<name>
```

--------------------------------

### Post Progress Update to GitHub Issue

Source: https://context7.com/automazeio/ccpm/llms.txt

This script gathers update files from a specified directory and posts a structured progress comment to a GitHub issue. The comment includes completed and in-progress work, acceptance criteria status, and any blockers.

```bash
# Natural language trigger:
"sync progress on issue 1235"
"post an update for issue 1235"

# The agent formats and posts:
gh issue comment 1235 --body-file /tmp/update-comment.md

# Comment format:
# ## 🔄 Progress Update - 2026-03-18
#
# ### ✅ Completed Work
# - FCM client setup done
#
# ### 🔄 In Progress
# - APNs integration
#
# ### 📊 Acceptance Criteria Status
# - [x] FCM integration complete
# - [ ] APNs integration complete
#
# ### ⚠️ Blockers
# None
#
# ---
# *Progress: 50% | Synced at 2026-03-18T14:30:00Z*

```

--------------------------------

### CCPM Skill Structure

Source: https://github.com/automazeio/ccpm/blob/main/README.md

Defines the directory structure for CCPM skills, including entry points, reference files for different stages of development (planning, execution, tracking), and bash scripts for deterministic operations.

```tree
skill/ccpm/
├── SKILL.md                  # Entry point — detects intent, routes to reference
└── references/
    ├── plan.md               # PRD writing + parsing to epic
    ├── structure.md          # Epic decomposition into tasks
    ├── sync.md               # GitHub sync, progress comments, close, merge
    ├── execute.md            # Issue analysis + parallel agent launch
    ├── track.md              # Status, standup, search, next, blocked
    ├── conventions.md        # File formats, frontmatter schemas, git rules
    └── scripts/              # Bash scripts for deterministic operations
        ├── status.sh
        ├── standup.sh
        ├── epic-list.sh
        ├── search.sh
        └── ...               # 14 scripts total
```

--------------------------------

### Complete and Sync Epic Workflow

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This script automates the process of completing an epic. It includes running tests, merging the epic branch into main, cleaning up local and remote branches, archiving epic data, and closing related GitHub issues.

```bash
cd ../epic-<name>
# detect and run: npm test / pytest / cargo test / go test / etc.
git checkout main && git pull origin main
git merge epic/<name> --no-ff -m "Merge epic: <name>"
git push origin main
git worktree remove ../epic-<name>
git branch -d epic/<name>
git push origin --delete epic/<name>
mkdir -p .claude/epics/archived/
mv .claude/epics/<name> .claude/epics/archived/
epic_issue=$(grep 'github:' .claude/epics/archived/<name>/epic.md | grep -oE '[0-9]+$')
gh issue close $epic_issue -c "Epic completed and merged to main"
```

--------------------------------

### Create Linked GitHub Issue for Bug Report

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This command creates a new GitHub issue for a bug report. It uses a predefined markdown template for the body and links it to the original issue and epic. The --json flag is used to output only the new issue number.

```bash
gh issue create \
  --repo "$REPO" \
  --title "Bug: <short description>" \
  --body "$(cat /tmp/bug-body.md)" \
  --label "bug,epic:<epic_name>" \
  --json number -q .number
```

--------------------------------

### Search Issues/Tasks Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Search for specific issues or tasks using a query with the search script. This is a deterministic operation.

```bash
bash references/scripts/search.sh <query>
```

--------------------------------

### Report Bug Against Completed Issue

Source: https://context7.com/automazeio/ccpm/llms.txt

This command creates a new GitHub issue to report a bug, linking it to a previous issue and including detailed context, description, steps to reproduce, and acceptance criteria. It uses the GitHub CLI and outputs the new issue number.

```bash
# The agent creates .claude/epics/notification-system/bug-1235-push-token-refresh.md
# and runs:
gh issue create \
  --repo "$REPO" \
  --title "Bug: push token not refreshed on expiry" \
  --body "Fixes / follow-up to #1235

## Context
Found while testing issue #1235: Push Notification Service

## Description
FCM tokens that have expired are not refreshed before retry — delivery silently fails.

## Steps to Reproduce
1. Let FCM token expire (or mock expiry)
2. Trigger a push notification
3. Observe: delivery fails, no retry, no error logged

## Expected vs Actual
- Expected: token refreshed automatically, notification delivered
- Actual: stale token used, silent failure

## Acceptance Criteria
- [ ] Bug is fixed
- [ ] Original issue #1235 behaviour is unaffected

## Effort Estimate
- Size: XS" \
  --label "bug,epic:notification-system" \
  --json number -q .number
```

--------------------------------

### Technical Epic Frontmatter and Structure

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/plan.md

This markdown structure is used for creating a technical epic from a PRD. It includes fields for status, creation date, and links to the PRD and GitHub.

```markdown
---
name: <feature-name>
status: backlog
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
progress: 0%
prd: .claude/prds/<name>.md
github: (will be set on sync)
---

# Epic: <feature-name>

## Overview
## Architecture Decisions
## Technical Approach
### Frontend Components
### Backend Services
### Infrastructure
## Implementation Strategy
## Task Breakdown Preview
## Dependencies
## Success Criteria (Technical)
## Estimated Effort

```

--------------------------------

### Check for Epic Branch

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Verify the existence of the Git branch for a specific epic.

```bash
git branch -a | grep "epic/<name>"
```

--------------------------------

### Update GitHub Issue and Assign Labels

Source: https://context7.com/automazeio/ccpm/llms.txt

Use this command to update a GitHub issue by adding an assignee and a label. It's typically used to mark an issue as 'in-progress'.

```bash
gh issue edit 1235 --add-assignee @me --add-label "in-progress"
```

--------------------------------

### Calculate Epic Progress

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

This script calculates the completion percentage of an epic based on the number of closed tasks relative to the total number of tasks. It assumes task files are named numerically.

```bash
total=$(ls .claude/epics/<name>/[0-9]*.md 2>/dev/null | wc -l)
closed=$(grep -l '^status: closed' .claude/epics/<name>/[0-9]*.md 2>/dev/null | wc -l)
progress=$((closed * 100 / total))
```

--------------------------------

### Update Frontmatter Field with sed

Source: https://context7.com/automazeio/ccpm/llms.txt

This command uses `sed` to update a specific frontmatter field (e.g., 'status') in a file without altering other content. It creates a backup before modification.

```bash
sed -i.bak "/^status:/c\status: in-progress" .claude/epics/notification-system/epic.md
rm .claude/epics/notification-system/epic.md.bak
```

--------------------------------

### Calculate Epic Progress

Source: https://context7.com/automazeio/ccpm/llms.txt

Calculates the completion percentage of an epic based on the number of closed tasks. Assumes task files are named numerically and located in a specific directory.

```bash
total=$(ls .claude/epics/notification-system/[0-9]*.md 2>/dev/null | wc -l)
closed=$(grep -l '^status: closed' .claude/epics/notification-system/[0-9]*.md 2>/dev/null | wc -l)
progress=$((closed * 100 / total))
```

--------------------------------

### Determine Next Tasks Script

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/SKILL.md

Identify the next set of tasks to be worked on by executing the next script. This is a deterministic operation.

```bash
bash references/scripts/next.sh
```

--------------------------------

### Validate Project State

Source: https://context7.com/automazeio/ccpm/llms.txt

This script performs a comprehensive validation of the project management system, checking directory structure, data integrity, reference validity, and frontmatter. It reports any errors or warnings.

```bash
bash skill/ccpm/references/scripts/validate.sh
```

--------------------------------

### Define Agent Task for Parallel Execution

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/execute.md

Configure a task for a sub-agent to execute a specific stream of work for a GitHub issue, including instructions for working in the epic worktree and updating progress.

```yaml
Task:
  description: "Issue #<N> Stream <X>"
  subagent_type: "general-purpose"
  prompt: |
    You are working on Issue #<N> in the epic worktree at: ../epic-<name>/
    
    Your stream: <stream_name>
    Your scope — files to modify: <file_patterns>
    Work to complete: <stream_description>
    
    Instructions:
    1. Read full task from: .claude/epics/<epic>/<N>.md
    2. Read analysis from: .claude/epics/<epic>/<N>-analysis.md
    3. Work ONLY in your assigned files
    4. Commit frequently: "Issue #<N>: <specific change>"
    5. Update progress in: .claude/epics/<epic>/updates/<N>/stream-<X>.md
    6. If you need to touch files outside your scope, note it in your progress file and wait
    7. Never use --force on git operations
    
    Complete your stream's work and mark status: completed when done.

```

--------------------------------

### Add Sync Marker to Local Files

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This markdown comment is added to local files after a sync operation to prevent duplicate comments from being posted to GitHub. It includes the timestamp of the sync.

```markdown
<!-- SYNCED: <datetime> -->
```

--------------------------------

### Close GitHub Issue and Update Epic

Source: https://context7.com/automazeio/ccpm/llms.txt

This process closes a GitHub issue, updates its local status, posts a completion comment, checks off the task in the parent epic issue, and recalculates the epic's overall progress.

```bash
# Natural language trigger:
"close issue 1235"
"mark issue 1235 as done"

# The agent runs:

# 1. Update local file status
sed -i.bak "/^status:/c\status: closed" .claude/epics/notification-system/1235.md
rm .claude/epics/notification-system/1235.md.bak

# 2. Post completion comment and close
echo "✅ Task completed — all acceptance criteria met." | gh issue comment 1235 --body-file -
gh issue close 1235

# 3. Check off task in epic issue body
gh issue view 1234 --json body -q .body > /tmp/epic-body.md
sed -i "s/- \[ \] #1235/- [x] #1235/" /tmp/epic-body.md
gh issue edit 1234 --body-file /tmp/epic-body.md

# 4. Recalculate epic progress
total=$(ls .claude/epics/notification-system/[0-9]*.md 2>/dev/null | wc -l)
closed=$(grep -l '^status: closed' .claude/epics/notification-system/[0-9]*.md 2>/dev/null | wc -l)
progress=$((closed * 100 / total))
sed -i.bak "/^progress:/c\progress: ${progress}%" .claude/epics/notification-system/epic.md

```

--------------------------------

### Check for gh-sub-issue Extension

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/sync.md

This script checks if the `yahsan2/gh-sub-issue` extension is available for use, setting a flag if it is.

```bash
if gh extension list | grep -q "yahsan2/gh-sub-issue"; then
  use_subissues=true
fi
```

--------------------------------

### Repository Safety Check

Source: https://github.com/automazeio/ccpm/blob/main/skill/ccpm/references/conventions.md

Before performing any write operations, this script checks if the current Git remote origin is the CCPM template repository. If it is, it prevents the operation and suggests updating the remote URL.

```bash
remote_url=$(git remote get-url origin 2>/dev/null || echo "")
if [[ "$remote_url" == *"automazeio/ccpm"* ]]; then
  echo "❌ Cannot write to the CCPM template repository."
  echo "Update remote: git remote set-url origin https://github.com/YOUR/REPO.git"
  exit 1
fi
REPO=$(echo "$remote_url" | sed 's|.*github.com[:/]|' | sed 's|\.git$||')
```