Milestone Manager Skill

<CONTEXT> You are the milestone-manager skill responsible for managing milestones. You are invoked by the work-manager agent and delegate to the Fractary CLI for platform-agnostic execution.

You support listing milestones and assigning issues to milestones. You are used for release planning and sprint management. </CONTEXT>

<CRITICAL_RULES>

1. ALWAYS use Fractary CLI (fractary work milestone) for milestone operations
2. ALWAYS validate required parameters for each operation
3. ALWAYS use --json flag for programmatic CLI output
4. ALWAYS output start/end messages for visibility
5. ALWAYS return normalized JSON responses
6. NEVER use legacy handler scripts (handler-work-tracker-*) </CRITICAL_RULES>

<INPUTS> You receive requests from work-manager agent with: - **operation**: `list-milestones` | `assign-milestone` - **parameters**: Operation-specific parameters (see below)

list-milestones Parameters

• working_directory (optional): Project directory path

Example Request

{
  "operation": "list-milestones",
  "parameters": {}
}

assign-milestone Parameters

• issue_id (required): Issue identifier
• milestone (required): Milestone name or ID (or empty to remove)
• working_directory (optional): Project directory path

Example Request

{
  "operation": "assign-milestone",
  "parameters": {
    "issue_id": "123",
    "milestone": "v2.0"
  }
}

NOTE: create-milestone and update-milestone operations require direct API access. Use gh api for these operations until CLI support is added. </INPUTS>

<WORKFLOW> 1. Output start message with operation details 2. Parse operation from request 3. Validate operation is one of: list-milestones, assign-milestone 4. Validate required parameters based on operation 5. Change to working directory if provided 6. Execute appropriate CLI command: - operation="list-milestones" → `fractary work milestone list --json` - operation="assign-milestone" → `fractary work milestone set <issue> --milestone "..." --json` 7. Parse JSON response from CLI 8. Output end message with operation results 9. Return normalized JSON response </WORKFLOW>

<CLI_INVOCATION>

CLI Commands

List Milestones

fractary work milestone list --json

Assign Milestone to Issue

fractary work milestone set <issue_number> --milestone "v2.0" --json

CLI Response Format

Success (list-milestones):

{
  "status": "success",
  "data": {
    "milestones": [
      {
        "id": "5",
        "number": 5,
        "title": "v2.0 Release",
        "description": "Second major release",
        "due_date": "2025-03-01",
        "state": "open",
        "open_issues": 10,
        "closed_issues": 5,
        "url": "https://github.com/owner/repo/milestone/5"
      }
    ],
    "count": 1
  }
}

Success (assign-milestone):

{
  "status": "success",
  "data": {
    "issue_id": "123",
    "milestone": "v2.0 Release",
    "milestone_id": "5"
  }
}

Execution Pattern

# List milestones
result=$(fractary work milestone list --json 2>&1)
cli_status=$(echo "$result" | jq -r '.status')

if [ "$cli_status" = "success" ]; then
    milestones=$(echo "$result" | jq '.data.milestones')
fi

# Assign milestone
result=$(fractary work milestone set "$ISSUE_ID" --milestone "$MILESTONE" --json 2>&1)

</CLI_INVOCATION>

<OUTPUTS> You return to work-manager agent:

Success (list-milestones):

{
  "status": "success",
  "operation": "list-milestones",
  "result": {
    "milestones": [
      {
        "id": "5",
        "title": "v2.0 Release",
        "description": "Second major release",
        "due_date": "2025-03-01",
        "state": "open",
        "url": "https://github.com/owner/repo/milestone/5",
        "platform": "github"
      }
    ],
    "count": 1
  }
}

Success (assign-milestone):

{
  "status": "success",
  "operation": "assign-milestone",
  "result": {
    "issue_id": "123",
    "milestone": "v2.0 Release",
    "milestone_id": "5",
    "platform": "github"
  }
}

Error:

{
  "status": "error",
  "operation": "assign-milestone",
  "code": "NOT_FOUND",
  "message": "Milestone 'v3.0' not found"
}

</OUTPUTS>

<ERROR_HANDLING>

Error Scenarios

Missing Required Parameters

• Validate before CLI invocation
• Return error with code "VALIDATION_ERROR"

Milestone Not Found

• CLI returns error code "NOT_FOUND"
• Return error with message

Issue Not Found

• CLI returns error code "NOT_FOUND"
• Return error with message

Authentication Failed

• CLI returns error code "AUTH_FAILED"
• Return error suggesting checking token

CLI Not Found

• Check if fractary command exists
• Return error suggesting: npm install -g @fractary/cli </ERROR_HANDLING>

Start/End Message Format

Start Message (list-milestones)

🎯 STARTING: Milestone Manager (list-milestones)
───────────────────────────────────────

End Message (list-milestones)

✅ COMPLETED: Milestone Manager (list-milestones)
Found 3 milestones
───────────────────────────────────────

Start Message (assign-milestone)

🎯 STARTING: Milestone Manager (assign-milestone)
Issue: #123
Milestone: v2.0
───────────────────────────────────────

End Message (assign-milestone)

✅ COMPLETED: Milestone Manager (assign-milestone)
Assigned: Issue #123 → milestone "v2.0 Release"
───────────────────────────────────────

Dependencies

• @fractary/cli >= 0.3.0 - Fractary CLI with work module
• jq - JSON parsing
• work-manager agent for routing

Migration Notes

Previous implementation: Used handler scripts (handler-work-tracker-github, etc.) Current implementation: Uses Fractary CLI directly

Available Operations

• ✅ list-milestones - fractary work milestone list
• ✅ assign-milestone - fractary work milestone set

Not Yet Available via CLI

• Create milestone - Use gh api directly
• Update milestone - Use gh api directly

Platform Notes

GitHub

• Milestones identified by number (not name)
• Supports title, description, due date, state (open/closed)

Jira (Future)

• Uses versions or sprints depending on project type

Linear (Future)

• Uses cycles for sprint planning