byterover-progress - SKILL.md Agent Skill

name: byterover-progress description: "Check project progress, resume paused work, and route to the next action. Loads project state from the knowledge base, presents a status report, detects incomplete work or handoffs, and suggests the most logical next workflow to invoke."

ByteRover Project Progress

A structured workflow for understanding where a project stands and what to do next. Loads all project state from the knowledge base, detects paused work or incomplete phases, and intelligently routes to the appropriate next action.

When to Use

Starting a new session and need to pick up where you left off
After being away from a project and need to regain context
When unsure what to work on next
To check overall milestone progress and phase completion
To review pending items or deferred ideas

Prerequisites

Run brv status first. If errors occur, instruct the user to resolve them in the brv terminal. See the byterover skill's TROUBLESHOOTING.md for details.

Process

Phase 1: Load Project State

Query the knowledge base for complete project context:

brv query "What is the project definition and current milestone?"
brv query "What is the current project status and last activity?"
brv query "What is the project roadmap and phase completion status?"
brv query "Is there paused work, handoff context, or incomplete tasks to resume?"
brv query "What pending items, deferred ideas, or todos exist?"

If no project knowledge exists, inform the user and recommend running byterover-milestone to define a project.

Phase 2: Assess Current Position

From the retrieved knowledge, determine:

Milestone — Current version, name, and goal
Phase position — Which phase is active, how many completed vs remaining
Phase status — Not started, planned, in progress, or complete
Paused work — Whether a handoff exists with context for resumption
Pending items — Count of deferred ideas, todos, or unresolved concerns
Last activity — What was done last and when
Blockers — Any known issues preventing progress

Phase 3: Present Status Report

Format a clear status summary:

# [Project Name] — Progress Report

Milestone: v[X.Y] [Name]
Phase: [N] of [Total] — [Phase Name] — [Status]
Last activity: [description]

Completed Phases:
- Phase 1: [Name] — [one-line summary]
- Phase 2: [Name] — [one-line summary]

Current Phase:
Phase [N]: [Name] — [Goal]
Status: [Not started / Planned / In progress / Blocked]

Pending Items: [count] items
[Top 3-5 items if any]

Paused Work: [Yes/No]
[Handoff context if paused]

Phase 4: Route to Next Action

Based on the assessed state, recommend the most logical next step:

State	Recommended Action
Paused work exists	Resume from handoff — describe what was in progress and next steps
Phase has a plan, not yet executed	Run `byterover-execute` to begin phase execution
Phase needs a plan	Run `byterover-plan` for the current phase
Current phase complete, more remain	Run `byterover-plan` for the next phase
All phases complete	Run `byterover-ship` to complete the milestone
Pending items need attention	Present items, let user choose: work on it, defer, or add to phase
No project defined	Run `byterover-milestone` to start a new project

Present the recommendation with reasoning. If multiple options are valid, list them in priority order and let the user choose.

If the user wants to review pending items:

List all items with brief descriptions
For each selected item, show full context
Offer actions: work on it now, defer to next milestone, add to current phase plan

Phase 5: Update Status

After the routing decision, update the knowledge base:

brv curate "Project status: Session resumed. Current position: Phase [N] — [status]. Next action: [what user chose]. Pending items: [count]" -f [relevant files]

Completion

Clearly state:

What the user should do next
Which workflow skill to invoke (if any)
Key context for the next action

Important Rules

Query before presenting — Always load state from the knowledge base, never assume
Be honest about gaps — If knowledge is incomplete, say what is missing
Route intelligently — Present the most logical action, not a generic menu
Update status every session — Curate project status so the next session can resume
Pending items are knowledge — Store and retrieve them via brv curate / brv query
Max 5 files per curate — Break down large status updates
Never read secrets — Skip .env, credential files, and similar
Verify curations — After storing critical context, run brv curate view <logId> to confirm what was stored (logId is printed by brv curate on completion). Run brv curate view --help to see all options.