init

.opencode/skills/project-management/references/progress-tracking.md

@@ -0,0 +1,120 @@
+# Progress Tracking
+
+## Plan Analysis Workflow
+
+1. **Read plans directory:** Glob `./plans/*/plan.md` to discover all plans
+2. **Parse YAML frontmatter:** Extract status, priority, effort, branch, tags
+3. **Scan phase files:** Count `[x]` (done) vs `[ ]` (remaining) in each phase
+4. **Reconcile completed tasks:** Ensure all completed task metadata is reflected in phase files (backfill stale earlier phases first)
+5. **Calculate progress:** `completed / total * 100` per plan
+6. **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:
+
+```bash
+# 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:
+
+1. **Acceptance criteria met?** — Check against plan requirements
+2. **Code quality validated?** — code-reviewer agent report available?
+3. **Tests passing?** — tester agent report confirms 100% pass?
+4. **Documentation updated?** — docs match implementation?
+5. **No regressions?** — Existing functionality intact?
+
+## Report Generation
+
+### Status Summary Template
+
+```markdown
+## 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
+
+```markdown
+## [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