Conventions — File Formats, Paths & Rules

Read this before doing any file operations across all phases.

---

Directory Structure

.claude/
├── prds/
│   └── <feature-name>.md          # Product requirement documents
├── epics/
│   ├── <feature-name>/
│   │   ├── epic.md                # Technical epic
│   │   ├── .md                 # Task files (named by GitHub issue number after sync)
│   │   ├── -analysis.md        # Parallel work stream analysis
│   │   ├── github-mapping.md      # Issue number → URL mapping
│   │   ├── execution-status.md    # Active agents tracker
│   │   └── updates/
│   │       └── <issue_N>/
│   │           ├── stream-A.md    # Per-agent progress
│   │           ├── progress.md    # Overall issue progress
│   │           └── execution.md  # Execution state
│   └── archived/
│       └── <feature-name>/        # Completed epics
└── context/                       # Project context docs (separate system)

---

Frontmatter Schemas

PRD (.claude/prds/<name>.md)

---
name: <feature-name>        # kebab-case, matches filename
description: <one-liner>    # used in lists and summaries
status: backlog | active | completed
created:          # date -u +"%Y-%m-%dT%H:%M:%SZ"
---

Epic (.claude/epics/<name>/epic.md)

---
name: <feature-name>
status: backlog | in-progress | completed
created: 
updated: 
progress: 0%                # recalculated when tasks close
prd: .claude/prds/<name>.md
github: https://github.com/<owner>/<repo>/issues/  # set on sync
---

Task (.claude/epics/<name>/.md)

---
name: 
status: open | in-progress | closed
created: 
updated: 
github: https://github.com/<owner>/<repo>/issues/  # set on sync
depends_on: []              # issue numbers this must wait for
parallel: true              # can run concurrently with non-conflicting tasks
conflicts_with: []          # issue numbers that touch the same files
---

Progress (.claude/epics/<name>/updates//progress.md)

---
issue: 
started: 
last_sync: 
completion: 0%
---

---

Datetime Rule

Always get real current datetime from the system — never use placeholder text:

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

---

Frontmatter Update Pattern

When updating a single frontmatter field in an existing file:

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

When stripping frontmatter to get body content for GitHub:

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

---

GitHub Operations

Repository Safety Check (run before any write operation)

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$||')

Authentication

Don't pre-check authentication. Run the gh command and handle failure:

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

Getting Issue Numbers

# From a task file's github field:
grep 'github:' <file> | grep -oE '[0-9]+$'

---

Git / Worktree Conventions

• One branch per epic: epic/<name>
• Worktrees live at ../epic-<name>/ (sibling to project root)
• Always start branches from an up-to-date main:

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

• Commit format inside epics: Issue #: <description>
• Never use --force in any git operation

---

Naming Conventions

• Feature names: kebab-case, lowercase, letters/numbers/hyphens, starts with a letter
• Task files before sync: 001.md, 002.md, ... (sequential)
• Task files after sync: renamed to GitHub issue number (e.g., 1234.md)
• Labels applied on sync: epic, epic:<name>, feature (for epics); task, epic:<name> (for tasks)

---

Epic Progress Calculation

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 epic frontmatter when any task closes.