Byterover Progress

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:

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:

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

Important Rules

1. Query before presenting — Always load state from the knowledge base, never assume
2. Be honest about gaps — If knowledge is incomplete, say what is missing
3. Route intelligently — Present the most logical action, not a generic menu
4. Update status every session — Curate project status so the next session can resume
5. Pending items are knowledge — Store and retrieve them via brv curate / brv query
6. Max 5 files per curate — Break down large status updates
7. Never read secrets — Skip .env, credential files, and similar
8. 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.