Ak Project Management

• Create tasks with metadata (phase, priority, effort, planDir, phaseFile)
• Track status: pending → in_progress → completed
• Manage dependencies with addBlockedBy / addBlocks
• Coordinate parallel agents with scoped ownership

2. Session Bridging (Hydration Pattern)

Load: references/hydration-workflow.md

Tasks are ephemeral. Plan files are persistent. The hydration pattern bridges them:

• Hydrate: Read plan [ ] items → TaskCreate per unchecked item
• Work: TaskUpdate tracks progress in real-time
• Sync-back: Reconcile all completed tasks against all phase files, update [ ] → [x], update YAML frontmatter status
• Resume: Next session re-hydrates from remaining [ ] items

3. Progress Tracking

Load: references/progress-tracking.md

• Scan ./plans/*/plan.md for active plans
• Parse YAML frontmatter for status, priority, effort
• Count [x] vs [ ] in phase files for completion %
• Cross-reference completed work against planned tasks
• Verify acceptance criteria met before marking complete

4. Documentation Coordination

Load: references/documentation-triggers.md

Trigger ./docs updates when:

• Phase status changes, major features complete
• API contracts change, architecture decisions made
• Security patches applied, breaking changes occur

Delegate to docs-manager subagent for actual updates.

5. Status Reporting

Load: references/reporting-patterns.md

Generate reports: session summaries, plan completion, multi-plan overviews.

• Use naming: {reports-path}/pm-{date}-{time}-{slug}.md
• Sacrifice grammar for brevity; use tables over prose
• List unresolved questions at end

Workflow

[Scan Plans] → [Hydrate Tasks] → [Track Progress] → [Update Status] → [Generate Report] → [Trigger Doc Updates]

1. TaskList() — check existing tasks first
2. If empty: hydrate from plan files (unchecked items)
3. During work: TaskUpdate as tasks progress
4. On completion: run full-plan sync-back (all phase files, including backfill for earlier phases), then update YAML frontmatter
5. Generate status report to reports directory
6. Delegate doc updates if changes warrant

Mandatory Sync-Back Guard

When updating plan status, NEVER mark only the currently active phase.

1. Sweep all phase-XX-*.md files under the target plan directory.
2. Reconcile every TaskUpdate(status: "completed") item to phase metadata (phase / phaseFile).
3. Backfill stale checkboxes in earlier phases before marking later phases done.
4. Update plan.md status/progress from real checkbox counts.
5. If any completed task cannot be mapped to a phase file, report unresolved mappings and do not claim full completion.

Plan YAML Frontmatter

All plan.md files MUST have:

---