Collaborative Progress Management

Multi-person project coordination using structured markdown files.

Core Files

Maintain three core files in project root:

code

project/
├── PLAN.md       # Development plan
├── RISKS.md      # Risk control
└── PROGRESS.md   # Progress tracking

PLAN.md - Development Plan

Records overall project planning and task breakdown.

Template

markdown

# Development Plan

## Project Overview

**Project**: [Project name]
**Goal**: [One-sentence goal]
**Start Date**: YYYY-MM-DD
**Target Date**: YYYY-MM-DD

## Milestones

### M1: [Milestone name] - Target: YYYY-MM-DD

| Task ID | Task | Priority | Estimate | Dependencies |
|---------|------|----------|----------|--------------|
| T001 | [Task description] | P0 | 2d | - |
| T002 | [Task description] | P1 | 1d | T001 |

### M2: [Milestone name] - Target: YYYY-MM-DD

| Task ID | Task | Priority | Estimate | Dependencies |
|---------|------|----------|----------|--------------|
| T003 | [Task description] | P0 | 3d | T001, T002 |

## Out of Scope

- [Items explicitly not doing]
- [Features deferred to next version]

## Technical Decisions

| Decision | Choice | Rationale | Date |
|----------|--------|-----------|------|
| [Decision point] | [Choice] | [Reason] | YYYY-MM-DD |

RISKS.md - Risk Control

Identify, assess, and track project risks.

Template

markdown

# Risk Management

## Active Risks

| Risk ID | Description | Impact | Probability | Mitigation | Owner | Status |
|---------|-------------|--------|-------------|------------|-------|--------|
| R001 | [Risk description] | High/Med/Low | High/Med/Low | [Mitigation plan] | @name | Open |
| R002 | [Risk description] | Med | Low | [Mitigation plan] | @name | Monitoring |

## Risk Matrix

Impact ↑ │ Low Prob │ Med Prob │ High Prob ───────┼───────────┼───────────┼─────────── High │ Monitor │ Mitigate │ CRITICAL Med │ Accept │ Monitor │ Mitigate Low │ Accept │ Accept │ Monitor

code


## Resolved Risks

| Risk ID | Description | Resolution | Resolved Date |
|---------|-------------|------------|---------------|
| R000 | [Resolved risk] | [How resolved] | YYYY-MM-DD |

## Blockers

Current blockers (need immediate attention):

- [ ] [Blocker description] - Owner: @name - Since: YYYY-MM-DD

PROGRESS.md - Progress Tracking

Real-time task status and team collaboration records.

Template

markdown

# Progress Tracking

## Current Sprint: [Sprint Name] (YYYY-MM-DD ~ YYYY-MM-DD)

### Task Board

#### 🔴 Blocked
| Task ID | Task | Owner | Blocker | Since |
|---------|------|-------|---------|-------|

#### 🟡 In Progress
| Task ID | Task | Owner | Branch | Started | ETA | Progress |
|---------|------|-------|--------|---------|-----|----------|
| T001 | [Task desc] | @alice | feat/xxx | 01-20 | 01-22 | 60% - core logic done |
| T002 | [Task desc] | @bob | fix/yyy | 01-21 | 01-21 | 80% - pending test |

#### 🟢 Ready for Review
| Task ID | Task | Owner | PR | Reviewer |
|---------|------|-------|----|---------|
| T003 | [Task desc] | @alice | #123 | @bob |

#### ✅ Done (This Sprint)
| Task ID | Task | Owner | Completed | PR |
|---------|------|-------|-----------|-----|
| T000 | [Task desc] | @bob | 01-19 | #120 |

### Daily Updates

#### YYYY-MM-DD

**@alice**
- T001: Completed API design, started core implementation
- Found R003 risk, logged in RISKS.md

**@bob**
- T002: Fixed edge case bug, preparing PR
- Starting T004 tomorrow

---

## Task Claiming Rules

1. **Claim task**: Add row to In Progress table with Owner and Branch
2. **Update progress**: Update Progress column and Daily Updates daily
3. **Complete task**: Move to Ready for Review or Done

Independent Workspace Setup (Multi-Agent)

When multiple agents work on the same codebase simultaneously, each agent MUST create an isolated workspace to prevent conflicts.

Why Worktree?

Git worktree allows multiple working directories from a single repository. Each agent works in its own directory with its own branch, enabling true parallel development without stepping on each other's toes.

Naming Convention

Use poetic, evocative names that give each agent a distinct identity:

Worktree directories (in parent folder):

code

../worktree_of_wandering_cloud/
../worktree_of_silent_river/
../worktree_of_autumn_leaf/
../worktree_of_morning_dew/
../worktree_of_distant_thunder/

Branch names (matching the identity):

code

agent/wandering-cloud/feat-xxx
agent/silent-river/fix-yyy
agent/autumn-leaf/refactor-zzz

Setup Before Work

bash

# 1. Ensure main branch is up-to-date (CRITICAL: always pull latest first)
git checkout main && git pull

# 2. Generate a poetic identity (or choose one)
AGENT_NAME="wandering-cloud"  # Be creative: moonlit-path, frozen-pine, etc.

# 3. Create worktree in parent directory (from latest main)
git worktree add "../worktree_of_${AGENT_NAME}" -b "agent/${AGENT_NAME}/workspace"

# 4. Enter your isolated workspace
cd "../worktree_of_${AGENT_NAME}"

# 5. Push workspace branch to remote immediately (establish tracking)
git push -u origin "agent/${AGENT_NAME}/workspace"

# 6. Create feature branch for your task
git checkout -b "agent/${AGENT_NAME}/feat-your-task"

# 7. Push feature branch to remote (ALWAYS push local branches to remote)
git push -u origin "agent/${AGENT_NAME}/feat-your-task"

# Now ready to start work!

Pre-Work Checklist

Before starting any task, ensure:

• Main branch pulled to latest (git pull on main)
• Worktree created from latest main
• Workspace branch pushed to remote
• Feature branch created and pushed to remote
• BRANCH_PROGRESS.md created and pushed

Workspace Structure

code

parent_directory/
├── main_repo/                      # Original repository
├── worktree_of_wandering_cloud/    # Agent 1's workspace
├── worktree_of_silent_river/       # Agent 2's workspace
└── worktree_of_autumn_leaf/        # Agent 3's workspace

Cleanup After Work

bash

# After PR is merged, clean up your worktree
cd ../main_repo
git worktree remove "../worktree_of_${AGENT_NAME}"
git branch -d "agent/${AGENT_NAME}/workspace"

Benefits

•No file conflicts: Each agent edits files in a separate directory
•Independent staging: Commits don't interfere with each other
•Clean separation: Easy to track which agent did what
•Parallel PRs: Multiple PRs can be prepared simultaneously

Distributed Progress Tracking

Since main branch is typically protected (requires PR), each branch maintains its own BRANCH_PROGRESS.md. Team progress is aggregated by querying all remote branches.

Branch Progress File Template

Each branch maintains BRANCH_PROGRESS.md in project root:

markdown

# Branch Progress

**Branch**: feat/xxx
**Task ID**: T001
**Owner**: @yourname
**Started**: YYYY-MM-DD
**Status**: In Progress

## Progress Log

### YYYY-MM-DD
- 0% - Starting work

Git Workflow (Protected Main)

Starting Work

bash

# 1. Pull latest main (CRITICAL)
git checkout main && git pull

# 2. Create feature branch and push immediately
git checkout -b feat/xxx
git push -u origin feat/xxx

# 3. Create BRANCH_PROGRESS.md and commit
git add BRANCH_PROGRESS.md
git commit -m "progress: claim T001 - [brief description]"
git push

During Work

bash

# Update progress in your branch (no need to touch main)
# Edit BRANCH_PROGRESS.md - add new entry to Progress Log
git add BRANCH_PROGRESS.md
git commit -m "progress: T001 update - [brief status]"
git push

Creating PR

bash

# Update BRANCH_PROGRESS.md: Status -> Ready for Review
git add BRANCH_PROGRESS.md
git commit -m "progress: T001 ready for review"
git push
gh pr create

Query Team Progress

Use the provided script to aggregate progress from all branches:

bash

# Summary table view
./scripts/team-progress.sh

# Detailed view with full progress logs
./scripts/team-progress.sh --detail

Script location: .claude/skills/collaborative-progress/scripts/team-progress.sh

Commit Message Convention

Progress-related commits (in your feature branch) use progress: prefix:

code

progress: claim T001 - user auth module
progress: T001 update - 60% complete, API design done
progress: T001 ready for review
progress: T001 blocked - waiting for API spec

Quick Actions

Initialize Project Progress Management

bash

# Create three core files
touch PLAN.md RISKS.md PROGRESS.md

# Initialize with templates (Claude assisted)

Daily Standup Checklist

• Check Blocked tasks in PROGRESS.md
• Update In Progress task progress
• Review Active Risks in RISKS.md
• Sync Daily Updates

Weekly Review Checklist

• Archive this week's Done tasks
• Evaluate risk status in RISKS.md
• Update Milestones progress in PLAN.md
• Plan next week's tasks

Best Practices

•Atomic updates: Update one task status at a time
•Branch-local progress: Keep progress updates in your branch's BRANCH_PROGRESS.md, never push directly to main
•Clear descriptions: Progress log should state what's done, not just percentage
•Front-load risks: Log risks immediately when discovered
•Pull before work: Always git pull on main before creating worktree or branch
•Push branches immediately: Push every new branch to remote right after creation
•Regular progress commits: Push progress updates frequently so team can query your status

Integration with First-Principles

Use together with first-principles-pm:

•Question: Does each task in PLAN.md really need to exist?
•Delete: Remove unnecessary tasks from PLAN.md
•Simplify: Merge similar tasks, reduce coordination overhead
•Accelerate: Use PROGRESS.md to quickly identify blockers
•Automate: Consider automating progress updates (CI/CD integration)