Progress Tracking

Plan Analysis Workflow

Read plans directory: Glob ./plans/*/plan.md to discover all plans
Parse YAML frontmatter: Extract status, priority, effort, branch, tags
Scan phase files: Count [x] (done) vs [ ] (remaining) in each phase
Reconcile completed tasks: Ensure all completed task metadata is reflected in phase files (backfill stale earlier phases first)
Calculate progress: completed / total * 100 per plan
Cross-reference: Compare plan tasks against actual implementation

Status Update Protocol

CLI-First Status Updates (Preferred)

Use ck plan CLI commands for deterministic, format-safe status changes:

# Mark phase completed
ck plan check <phase-id>

# Mark phase in-progress
ck plan check <phase-id> --start

# Revert phase to pending
ck plan uncheck <phase-id>

# Add new phase or sub-phase
ck plan add-phase "Phase Name" [--after <id>]

CLI automatically updates both plan.md table AND phase file frontmatter. Plan-level status auto-computed: all completed → completed, any in-progress → in-progress.

Fallback: If ck CLI is not available, edit plan.md directly — only change the Status column cell, preserve table structure exactly.

Plan-Level Status

Update plan.md frontmatter status field:

Condition	Status
No phases started	`pending`
Any phase in progress	`in-progress`
All phases complete	`completed`

Phase-Level Status

Each phase-XX-*.md tracks with checkboxes:

[ ] = pending
[x] = completed
Count ratio for progress percentage

Task-Level Status

Claude Tasks (session-scoped): pending → in_progress → completed

Reconciliation Rule

If a later phase is marked done while earlier phases still contain stale unchecked completed items, backfill earlier phases in the same sync pass before final status reporting.

Verification Checklist

When verifying task completeness:

Acceptance criteria met? — Check against plan requirements
Code quality validated? — code-reviewer agent report available?
Tests passing? — tester agent report confirms 100% pass?
Documentation updated? — docs match implementation?
No regressions? — Existing functionality intact?

Report Generation

Status Summary Template

## Project Status: [Date]

### Active Plans
| Plan | Progress | Priority | Status | Branch |
|------|----------|----------|--------|--------|
| [name] | [X]% | P[N] | [status] | [branch] |

### Completed This Session
- [x] [description]

### Blockers & Risks
- [ ] [description] — [mitigation]

### Next Steps
1. [Priority action]
2. [Follow-up]

Detailed Report Template

## [Plan Name] - Detailed Status

### Achievements
- Completed features, resolved issues, delivered value

### Testing Status
- Components needing validation, test scenarios, quality gates

### Risk Assessment
- Potential blockers, technical debt, mitigation strategies

### Recommendations
- Prioritized next steps, resource needs, timeline projections

Metrics to Track

Phase completion % — How much of each phase is done
Blocker count — Open blockers preventing progress
Dependency chain health — Any circular or stale dependencies
Time since last update — Identify stale plans needing attention
Test coverage — Per-feature test pass rates

3.4 KiB Raw Permalink Blame History