pinkroosterai/pm-next

Pick Up Next Work Item

Find the highest-priority actionable item, prepare it for implementation (scaffolding if needed), and execute it.

Step 1: Parse Arguments & Resolve Project

Parse $ARGUMENTS:

• --auto: Fully autonomous mode — no prompts, auto-select, auto-scaffold, auto-commit per WP. Remove the flag before further parsing.
• Entity type filter: Optional Wp, Issue, or FeatureRequest. Default: omit (returns all types mixed by priority).

Resolve project:

• Current directory: !pwd
• Call mcp__pinkrooster__get_project_status with projectPath → extract projectId

Initialize: completedItems = [], skippedItems = [], iterationCount = 0

Step 2: Find Next Item

Call mcp__pinkrooster__get_next_actions with:

• projectId from Step 1
• limit: 10 (fetch more candidates for smarter selection)
• entityType: the specified filter, or omit entirely to get all actionable WPs, Issues (without linked WPs), and FRs (without linked WPs), sorted by priority

This returns a queue of candidates.

Smart Selection

Don't blindly take the #1 item. Evaluate the queue to find the most impactful item to work on:

1. Blockers first: If any item in the queue is blocking other items (check blocking field on WP details), prefer it over higher-priority leaf items. Completing a blocker unblocks downstream work, which has a multiplier effect on project progress.

2. Ready WPs over unscaffolded entities: A WP with phases and tasks is ready to implement immediately. An Issue or FR without a linked WP needs scaffolding first (extra overhead). When priorities are equal, prefer the ready WP.

3. Priority as tiebreaker: When impact is equal, use the API's priority ordering (Critical > High > Medium > Low).

In practice, this means: scan the top 5 candidates, check if any are blockers (call mcp__pinkrooster__get_work_package_details on WP candidates to check their blocking field), and select accordingly. If no blockers, fall through to priority ordering.

If empty queue:

• Auto mode → jump to Step 7 (Exit)
• Interactive → "No actionable items found. Run /pm-status for overview."

Select

• Auto mode: Apply smart selection. No prompt.
• Interactive: Present the top candidates and recommendation using the AskUserQuestion tool:
  • Question: "Which item would you like to work on next?"
  • Header: "Next item"
  • Options: Build from the queue (up to 4). Mark the recommended item: [{label: "#1 {entityId}", description: "[{priority}] \"{name}\" ({state}) — {type} ⭐ Recommended: {reason}"}, {label: "#2 {entityId}", description: "[{priority}] \"{name}\" ({state}) — {type}"}, ...]
  • Explain why the recommended item was chosen (e.g., "blocks 2 other WPs" or "highest priority, ready to implement")
  • If only one candidate, auto-select it without asking.

Step 3: Normalize to Work Package

Every item must become a WP before implementation. This step resolves the selected item to a concrete WP with phases and tasks.

If WP (proj-N-wp-N)

1. Call mcp__pinkrooster__get_work_package_details with the WP ID (if not already loaded from smart selection)
2. Blocked check: If blockedBy contains any non-terminal WP:
   • Auto mode → add to skippedItems with reason "blocked by {blockerId}", try next candidate from Step 2 queue
   • Interactive → use the AskUserQuestion tool:
     • Question: "{wpId} is blocked by {blockerId}. What would you like to do?"
     • Header: "Blocked"
     • Options: [{label: "Work on blocker", description: "Switch to implementing {blockerId} first"}, {label: "Pick different", description: "Go back and choose a different item from the queue"}]
3. Load linked Issues (if linkedIssueIds is non-empty): call mcp__pinkrooster__get_issue_details for each
4. Load linked FRs (if linkedFeatureRequestIds is non-empty): call mcp__pinkrooster__get_feature_request_details for each — note user stories for context
5. Proceed to Step 4 with this WP.

If Issue (proj-N-issue-N)

1. Call mcp__pinkrooster__get_issue_details
2. If linked WPs exist: pick the first non-terminal WP → load its details → proceed as WP path above (skip steps 1-2, go straight to blocked check)
3. If no linked WP: auto-scaffold:
   • Invoke /pm-scaffold {issueId}
   • In auto mode: scaffold must proceed without prompting (skip quality warnings for sparse data)
   • On success: extract the new WP ID → load its details → proceed to Step 4
   • On failure: auto mode → add to skippedItems with reason "scaffold failed", try next candidate. Interactive → report error.

If Feature Request (proj-N-fr-N)

1. Call mcp__pinkrooster__get_feature_request_details — note user stories
2. If linked WPs exist: pick the first non-terminal WP → load its details → proceed as WP path above
3. If no linked WP: auto-scaffold:
   • Invoke /pm-scaffold {frId}
   • In auto mode: scaffold must proceed without prompting (skip quality warnings for sparse data)
   • On success: extract the new WP ID → load its details → proceed to Step 4
   • On failure: auto mode → add to skippedItems with reason "scaffold failed", try next candidate. Interactive → report error.

Note: If all candidates in the queue are exhausted (all blocked or failed), auto mode re-fetches in Step 2. If re-fetch also returns nothing actionable → Step 7 (Exit).

Step 4: Activate Entities & Show Context

We now have a resolved WP. Activate all inactive entities without prompting, then show the user what they're about to implement.

Activate

1. WP (if NotStarted or Blocked): call mcp__pinkrooster__create_or_update_work_package with state: "Implementing" → report "{wpId} → Implementing"
2. Linked Issues (for each in linkedIssueIds, if NotStarted or Blocked): call mcp__pinkrooster__create_or_update_issue with state: "Implementing" → report "Auto-activated {issueId} → Implementing"
3. Linked FRs (for each in linkedFeatureRequestIds, if Proposed or Deferred): call mcp__pinkrooster__create_or_update_feature_request with status: "InProgress" → report "Auto-activated {frId} → InProgress"

Show Implementation Context

Present enough detail for the user to understand what's about to happen:

## Implementing: {wpId} "{wpName}"

### Overview
- Priority: {priority} | Complexity: {estimatedComplexity}/10 | Type: {wpType}
- Tasks: {nonTerminalCount} remaining across {phaseCount} phases
- Linked: {issueId and/or frId if any}

### Phase Breakdown
**Phase 1: {phaseName}** — {taskCount} tasks
  {task1Name} → {task2Name} → ... (dependency chain)

**Phase 2: {phaseName}** — {taskCount} tasks
  ...

### User Stories (if FR linked)
- As a {role}, I want {goal}, so that {benefit}
- ...

### Selection Rationale
- {why this item was chosen: "Highest priority", "Unblocks proj-1-wp-4 and proj-1-wp-5", etc.}

Step 5: Implement

Invoke /pm-implement {wpId} to execute all tasks across all phases.

/pm-implement autonomously handles:

• Task dependency ordering and sequential execution
• Reading target files, implementing code changes
• Building and running tests after each task (with auto-fix on failure)
• Transitioning tasks to Implementing → Completed
• Phase verification gates (acceptance criteria checks between phases)
• Phase/WP auto-completion via state cascades
• Auto-completion of linked Issue and FR when the WP cascades to Completed

When /pm-implement returns

Check the WP's final state by calling mcp__pinkrooster__get_work_package_details:

WP is Completed (normal case — all tasks done, cascades fired):

• Add to completedItems
• Proceed to Step 6 (Commit)

WP is NOT Completed (some tasks were blocked by external deps, or a phase verification gate failed):

• Commit whatever changes were made (partial work is still valuable)
• Auto mode → add to skippedItems with reason "incomplete: {details}", proceed to Step 6 then loop back to Step 2
• Interactive → report status and suggest: "Continue with /pm-implement {wpId}, or /pm-next for different work."

Build/test failures that /pm-implement could not resolve:

• This is the one hard stop in auto mode. The agent could not fix the code.
• Commit changes so far (even if broken — the user needs to see the attempt)
• Report the failure clearly with test output and what was tried
• Exit the auto loop. User must intervene.

Step 6: Commit

After each WP (completed or partial), commit all changes:

1. Stage all files changed during this WP's implementation
2. Create a commit using conventional format:

<type>(<scope>): <summary of what was implemented>

Implements {wpId} "{wpName}".
{Linked: issueId "issueName" (if any)}
{Linked: frId "frName" (if any)}

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Commit type by WP type: feat (Feature), fix (BugFix), refactor (Refactor), chore (Chore/Spike).

If no files were changed (e.g., all tasks were skipped), skip the commit.

Step 7: Loop or Exit

Auto mode

If the WP completed or was skipped (not a hard failure): loop back to Step 2.

Increment iterationCount. Report progress between iterations:

---
## Auto-loop iteration {iterationCount}: {completedItems.length} completed, {skippedItems.length} skipped. Checking for more...
---

Exit conditions (any of these ends the loop):

| Condition | Output | |-----------|--------| | No actionable items from Step 2 | "No more actionable items." | | All candidates blocked/failed | "All remaining items are blocked or failed to scaffold." | | Hard build/test failure | "Stopping: unresolvable build/test failure in {wpId}." |

On exit, print the session summary:

## Auto-loop Complete

### Completed ({completedItems.length})
| # | WP | Name | Type | Commit |
|---|-----|------|------|--------|
| 1 | {wpId} | {wpName} | feat/fix/refactor | {short commit hash} |
| ... |

### Skipped ({skippedItems.length})
| # | Entity | Name | Reason |
|---|--------|------|--------|
| 1 | {entityId} | {name} | {reason} |
| ... |

### Session Stats
- Iterations: {iterationCount}
- Items completed: {completedItems.length}
- Items skipped: {skippedItems.length}

### Next Steps
- `/pm-status` — full project overview
- `/pm-triage` — review priorities and blocked items
- `/pm-next --auto` — resume autonomous work (after fixing any blockers)

Interactive mode

Use the AskUserQuestion tool:

• Question: "Work package complete. What would you like to do next?"
• Header: "Continue?"
• Options: [{label: "Next item", description: "Pick up the next priority item: /pm-next (Recommended)"}, {label: "Status", description: "Check project progress: /pm-status"}, {label: "Done", description: "Stop here for now"}]

---

Auto Mode Contract

--auto guarantees a hands-off experience. The agent follows these rules:

1. Never prompt the user — every decision point has an auto-mode default
2. Skip, don't stall — blocked items, scaffold failures, and incomplete WPs are skipped. They'll resurface in future iterations when conditions change.
3. Only stop on unresolvable failures — build/test errors that can't be auto-fixed are the single hard stop. Everything else is skippable.
4. Commit after every WP — keeps work atomic and recoverable, even for partial implementations
5. Re-fetch every iteration — completing a WP may auto-unblock other WPs via dependency cascades. Fresh data from get_next_actions reflects this.
6. Smart ordering governs selection — blockers first, ready WPs over unscaffolded entities, then priority as tiebreaker
7. Propagate auto-mode to delegated skills — when invoking /pm-scaffold or /pm-implement, suppress all interactive prompts (quality warnings, confirmations, "proceed?" questions). Proceed with available data.

Constraints

• Everything becomes a WP before implementation — Issues/FRs without WPs are auto-scaffolded
• Do NOT call /pm-verify separately — /pm-implement handles phase verification gates internally
• Do NOT call /pm-done separately — task/phase/WP completion happens via cascades inside /pm-implement, including auto-completion of linked Issues and FRs
• Tasks are too granular for this skill — use /pm-implement {taskId} directly for single-task work
• When delegating to /pm-scaffold in auto mode, skip all quality checks and user prompts
• Smart selection should not add significant latency — check at most 3-5 WPs for blocker status, don't deep-dive every candidate