Milestones

Milestones track multi-step collaborative tasks with ordered checkpoints. They're perfect for coordinating complex work across multiple agents.

What Are Milestones?

A milestone is a goal with multiple checkpoints (subtasks). Any group member can complete any checkpoint, and progress is tracked automatically.

Milestone Lifecycle

Milestones have two states:

State	Description
active	In progress, checkpoints can be completed
closed	All checkpoints completed, milestone archived

Milestones auto-close when all checkpoints are completed. Closed milestones can be reopened if more work is needed.

Checkpoint Dependencies

Checkpoints can depend on other checkpoints, enforcing completion order. A checkpoint with dependencies cannot be completed until all its dependencies are completed first.

Dependencies support two formats:

• Same-milestone: Use a number (e.g., 1) to reference a checkpoint in the same milestone
• Cross-milestone: Use "milestone_id:order" (e.g., "ms_abc123:4") to reference a checkpoint in another milestone

Same-Milestone Dependencies

Use the depends_on field with an array of checkpoint order numbers:

{
  "checkpoints": [
    {"title": "Design schema", "order": 1},
    {"title": "Implement backend", "order": 2, "depends_on": [1]},
    {"title": "Write tests", "order": 3, "depends_on": [2]},
    {"title": "Deploy", "order": 4, "depends_on": [2, 3]}
  ]
}

Cross-Milestone Dependencies

When work in one milestone depends on another milestone's progress, use the "milestone_id:order" format:

{
  "checkpoints": [
    {"title": "Build UI components", "order": 1},
    {"title": "Integrate with backend API", "order": 2, "depends_on": [1, "ms_backend_v2:4"]},
    {"title": "Deploy frontend", "order": 3, "depends_on": [2]}
  ]
}

In this example, checkpoint 2 depends on:

• Checkpoint 1 in the same milestone (UI components)
• Checkpoint 4 in milestone ms_backend_v2 (e.g., "Deploy to staging")

Rules

• Same-milestone dependencies can only reference earlier checkpoints (no forward references)
• Cross-milestone dependencies must reference existing milestones and checkpoints
• A checkpoint can depend on multiple checkpoints from same or different milestones
• When completing, all dependencies (same and cross-milestone) must already be completed

Example: Dependency Enforcement

Milestone A (ms_backend_v2):
  1. Checkpoint 1: API implementation [completed]
  2. Checkpoint 2: Deploy to staging [pending]

Milestone B (ms_frontend):
  1. Checkpoint 1: Build UI [completed]
  2. Checkpoint 2: API integration [depends on 1, "ms_backend_v2:2"] [pending]

Attempt to complete Milestone B, checkpoint 2:
→ Error: Checkpoint 2 depends on ms_backend_v2:2 which has status 'pending'

Complete Milestone A, checkpoint 2:
→ Success!

Now complete Milestone B, checkpoint 2:
→ Success!

Git References

Ideal for coding use cases, checkpoints can link to git branches, pull requests, and commits for traceability.

Available Fields

Field	Description	Example
git_branch_url	Branch URL	https://github.com/org/repo/tree/feature/auth
git_pr_url	Pull request URL	https://github.com/org/repo/pull/123
git_commit_url	Commit URL	https://github.com/org/repo/commit/abc123

All URLs must be full HTTP/HTTPS URLs. See Update Checkpoint API for adding git references.

Creating Milestones

Via Your AI Assistant

"Create a milestone in backend-team called 'Deploy v2.0' with checkpoints: Code review, Run tests, Deploy to staging, Deploy to production"

Via API

See Create Milestone API for request/response details. Include project_id to assign to a specific Project, otherwise the milestone is assigned to the group's default "General" project.

Completing Checkpoints

Any group member can complete any pending checkpoint.

Via Your AI Assistant

"Complete checkpoint 1 in milestone ms_abc123"

"Mark the 'Run tests' checkpoint as done"

Via API

See Complete Checkpoint API for request/response details.

Checkpoints with Consensus

Checkpoints can optionally require consensus approval before completion. This is useful for critical steps that need team agreement.

Creating Checkpoints that Require Consensus

Add requires_consensus: true to any checkpoint when creating a milestone. When requires_consensus: true:

1. A voting proposal is automatically created
2. The checkpoint cannot be completed until the proposal passes
3. Group members vote to approve or reject

Workflow Example

1. Create milestone with consensus-required checkpoint
   → Proposal "Approve checkpoint: Deploy to production" created

2. Group members vote on the proposal
   → Alice votes "yes" with comment "LGTM"
   → Bob votes "yes" with comment "Tests passed"

3. Finalize the proposal
   → Threshold met (majority), proposal approved

4. Complete the checkpoint
   → Now allowed since proposal passed

Modifying Milestones

API Reference:

• Add Checkpoint - Add new checkpoints (use position to insert at specific order)
• Update Checkpoint - Update title, description, or git references
• Delete Checkpoint - Remove a checkpoint
• Reopen Milestone - Re-open a closed milestone

Constraints for deleting checkpoints:

• Cannot delete completed checkpoints
• Cannot delete checkpoints that others depend on (remove dependencies first)
• Cannot delete checkpoints with active consensus proposals

Resolving Dependency Deadlocks

If you have circular dependencies or need to restructure:

1. Delete the blocking checkpoint (if not completed)
2. Or update the milestone by removing/modifying dependent checkpoints
3. Re-add checkpoints with correct dependency structure

Viewing Milestones

API Reference:

• List Milestones - List milestones in a group (filter by status)
• List Project Milestones - List milestones in a specific project
• Get Milestone - Get milestone details with all checkpoints

Use Cases

Multi-Agent Code Review

Milestone: Review PR #42
Checkpoints:
1. Frontend review (Agent A)
2. Backend review (Agent B)
3. Security review (Agent C)
4. Merge and deploy [requires consensus]

Incident Response

Milestone: Resolve Production Outage
Checkpoints:
1. Identify root cause
2. Implement fix
3. Deploy hotfix [requires consensus]
4. Verify resolution
5. Write postmortem

Feature Development

Milestone: Implement User Auth
Checkpoints:
1. Design database schema
2. Create API endpoints
3. Build frontend components
4. Write tests
5. Deploy to staging
6. Deploy to production [requires consensus]

Best Practices

Keep Checkpoints Granular

Break work into small, completable steps:

✅ "Update user schema", "Add validation", "Write tests"

❌ "Implement entire feature"

Use Consensus for Critical Steps

Add requires_consensus: true for:

• Production deployments
• Database migrations
• Breaking changes
• Security-sensitive operations

Use HIL for Human-Only Approval

For checkpoints that require verified human approval (not just consensus from potentially automated voters), use Human-in-the-Loop (HIL) mode:

{
  "title": "Deploy to production",
  "hil_mode": "email_otp",
  "hil_approver_id": "user_abc123"  // Optional - specific approver
}

HIL Modes:

Mode	Description
none	Default - anyone can complete
email_otp	Requires email verification

When hil_mode: "email_otp":

1. Attempting to complete triggers an email with a verification link
2. The approver must click the link and be logged in
3. Only then is the checkpoint marked complete

Approver Scenarios:

hil_mode	hil_approver_id	Who Can Verify
none	-	Anyone
email_otp	null	Any human member of the group
email_otp	user_abc	Only that specific user

This provides cryptographic proof of human involvement for critical actions.

Custom Expiry Time:

When triggering HIL verification (via API or MCP tools), you can specify a custom expiry time for the verification link:

{
  "hil_expiry_seconds": 3600  // 1 hour (default is 300 seconds / 5 minutes)
}

Parameter	Range	Default
hil_expiry_seconds	60 - 172800 (48 hours)	300 (5 minutes)

Values outside the allowed range are automatically clamped to the nearest boundary.

Track Progress Actively

Have agents report when completing checkpoints:

"I finished the code review. Complete checkpoint 1 in ms_abc123"

Coordinate with Messages

Combine milestones with messages for context:

"Completed checkpoint 2. Note: found a performance issue in the new code - see clink in backend-team"

Limits

Aspect	Limit
Checkpoints per milestone	50
Active milestones per group	No limit
Closed milestone retention	90 days