@pi-unipi/milestone

Track project goals across workflow cycles. A MILESTONES.md file with phases and checkbox items that stays in sync with your specs, plans, and completed work.

Workflow operates at the task level — brainstorm, plan, work, review. Project goals scatter across those documents. Milestone gives you a single view of what's done and what's left, and keeps the agent aligned with your goals across sessions.

Commands

Command	Description
/unipi:milestone-onboard	Create MILESTONES.md from existing workflow docs
/unipi:milestone-update	Sync MILESTONES.md with completed work

Special Triggers

Session Start

On before_agent_start, milestone reads .unipi/docs/MILESTONES.md and appends a progress summary to the system prompt:

## Project Milestones
Overall progress: 5/10 items (50%)
  Phase 1: Foundation: 3/5 done
  Phase 2: Features: 2/5 done
Current focus: Phase 1: Foundation

If MILESTONES.md doesn't exist, no context is injected.

Session End

On session_shutdown, milestone scans workflow docs modified during the session. Detects items that changed from - [ ] to - [x] and auto-updates MILESTONES.md using exact text matching.

Coexist Triggers

Trigger	Behavior
After brainstorm	Checks if new spec items map to milestones, logs suggestions
After plan	Maps plan tasks to milestone items, logs coverage
After consolidate	References auto-sync from session shutdown

All triggers are non-blocking and skip gracefully if MILESTONES.md doesn't exist.

Milestone registers with the info-screen dashboard, showing progress, current phase, and remaining items.

MILESTONES.md Format

---
title: "Project Milestones"
created: 2026-04-28
updated: 2026-04-28
---

# Project Milestones

## Phase 1: Foundation
> Set up the core infrastructure

- [x] Project scaffold and build system
- [x] Database schema design
- [ ] Authentication system
- [ ] API routing layer

## Phase 2: Core Features
> Build the primary user-facing features

- [ ] User dashboard
- [ ] File upload system
- [ ] Notification service

API Exports

import {
  parseMilestones,      // Parse MILESTONES.md to MilestoneDoc
  writeMilestones,      // Write MilestoneDoc to MILESTONES.md
  updateItemStatus,     // Toggle a checkbox item
  getProgressSummary,   // Get progress stats
} from "@pi-unipi/milestone";

import type {
  MilestoneDoc,
  MilestonePhase,
  MilestoneItem,
  ProgressSummary,
  PhaseProgress,
} from "@pi-unipi/milestone";

Configurables

No configuration needed. Place MILESTONES.md at .unipi/docs/MILESTONES.md and the extension handles the rest.

License

MIT