Skip to main content

​
Complete tasks and update local space automatically

This guide walks you through completing tasks and automatically updating your local space (playbook) with the knowledge gained during execution. The typical flow for completing a task in ByteRover uses the complete command, which runs a full ACE (Agentic Context Engineering) workflow in one go: 
> complete the task with `brv complete`: I implemented OAuth2 authentication flow
and the agent will execute the command 
brv complete "user-auth" \
"Implemented OAuth2 flow with PKCE. Added token refresh logic and secure storage in keychain. \
Updated auth service to handle expired tokens gracefully" \
"OAuth2 authentication working with automatic token refresh" \
--tool-usage "Read:src/infra/auth/oauth-service.ts,Edit:src/infra/auth/oauth-service.ts,Edit:src/infra/auth/token-store.ts,Bash:npm test" \
--feedback "All tests passed"
When the command runs, it executes three phases automatically:
  1. Executor: Saves your task execution details
  2. Reflector: Analyzes what happened and tags related playbook bullets
  3. Curator: Creates a delta operation to update the playbook with new knowledge
The playbook.json file is updated automatically, storing your key insight in the “Lessons Learned” section with tags like ['auto-generated'].

​
The three required arguments

Every complete command needs three core pieces of information: 1. Hint - A short identifier for naming output files: 
brv complete "user-auth" ...
2. Reasoning - Detailed explanation of your approach and what you did: 
... "Implemented OAuth2 flow with PKCE. Added token refresh logic..." ...
3. Final Answer - The outcome or solution: 
... "OAuth2 authentication working with automatic token refresh" ...

​
Required flags: tool-usage and feedback

Tool usage tracks what tools you used during the task: 
--tool-usage "Read:src/auth.ts,Edit:src/auth.ts,Bash:npm test"
Format: ToolName:argument separated by commas. The command extracts file paths from this to link your knowledge to specific files. Feedback captures the environment’s response: 
--feedback "All tests passed"
or when things go wrong: 
--feedback "Build failed with TypeScript errors in auth module"

​
Optional flags for more control

Reference playbook bullets you consulted: 
> complete this task and reference the bullets I used

brv complete "validation-fix" "Analyzed validator based on bullet-123 recommendations" "Fixed validation bug" --tool-usage "Grep:pattern:\"validate\",Read:src/validator.ts" --bullet-ids "bullet-123,bullet-456" --feedback "Tests passed"
Update existing knowledge instead of adding new: 
> complete this task and update the existing bullet about authentication

brv complete "auth-update" "Improved error handling in OAuth flow based on production issues" "Better error messages and retry logic" --tool-usage "Edit:src/auth.ts" --feedback "Tests passed" --update-bullet "bullet-5"
With --update-bullet, the command updates the specified bullet instead of creating a new one.

​
Understanding the workflow phases

When you run complete, you’ll see three distinct phases: Phase 1: Executor - Saves your task details 
📝 Phase 1: Saving executor output...
  ✓ Executor output saved: executor-outputs/user-auth-20250102-143022.json
Phase 2: Reflector - Analyzes the execution 
🤔 Phase 2: Generating reflection...
  ✓ Reflection saved: reflections/user-auth-20250102-143022.json
  ✓ Tags applied to playbook: 3
Phase 3: Curator - Updates the playbook 
🎨 Phase 3: Generating curation prompt...
  ✓ Delta saved: deltas/user-auth-20250102-143022.json
  ✓ Delta operations applied to playbook (1 operations)
All three artifacts are saved in their respective directories for audit trail and debugging.

​
The final summary

After completion, you get a comprehensive summary: 
================================================================================
✅ ACE WORKFLOW COMPLETED SUCCESSFULLY!
================================================================================

Summary:
  Hint: user-auth
  Executor output: executor-outputs/user-auth-20250102-143022.json
  Reflection: reflections/user-auth-20250102-143022.json
  Delta: deltas/user-auth-20250102-143022.json
  Tags applied: 3

Delta operations:
  - ADD: 1
  Total operations: 1

🎉 Playbook has been updated with new knowledge!
This tells you exactly what was saved and how the playbook changed.

​
You’re in Control of Your Completions

The complete command adapts to different scenarios:

​
Simple Task Completion

Just finished a straightforward fix? Keep it simple: 
> complete this bug fix with brv complete

brv complete "bug-fix" "Fixed null pointer in validator" "Validation now handles null inputs" --tool-usage "Edit:src/validator.ts" --feedback "Tests passed"

​
Complex Task with Context

Worked on something complex using multiple playbook bullets? 
> complete this feature implementation, I referenced several playbook bullets

brv complete "feature-x" "Implemented new feature following architecture patterns from bullet-10 and testing guidelines from bullet-25" "Feature X fully working with tests" --tool-usage "Read:src/core/interfaces/i-service.ts,Write:src/infra/service-impl.ts,Write:test/service.test.ts,Bash:npm test" --bullet-ids "bullet-10,bullet-25" --feedback "All tests passed, coverage at 95%"

​
Updating Existing Knowledge

Discovered something that improves old knowledge? 
> complete this and update the existing authentication bullet with new learnings

brv complete "auth-improvement" "Found that OAuth refresh tokens expire after 7 days, not 30 as previously documented. Updated token refresh logic to handle this" "Auth now properly handles 7-day expiry" --tool-usage "Edit:src/auth.ts,Edit:docs/auth.md" --feedback "Production testing confirmed" --update-bullet "bullet-15"

​
Failed Tasks (Learning from Failures)

Even failures teach valuable lessons: 
> complete this task even though it failed, I want to capture what went wrong

brv complete "db-migration" "Attempted to add new column to users table but encountered foreign key constraint issues. Need to drop and recreate constraints first" "Migration failed - constraints blocking" --tool-usage "Read:migrations/001-add-column.sql,Bash:npm run migrate" --feedback "Error: foreign key constraint violation on users table"
The reflector will identify this as a failure and capture the root cause for future reference.

​
Capturing Tool Usage Patterns

Track exactly which tools helped you succeed: 
> complete this with detailed tool usage tracking

brv complete "refactor" "Used Grep to find all usages, Read to understand implementations, Edit to refactor, Bash to verify tests" "Refactoring complete" --tool-usage "Grep:pattern:\"oldFunction\",Read:src/old.ts,Read:src/new.ts,Edit:src/old.ts,Edit:src/new.ts,Edit:test/old.test.ts,Bash:npm test" --feedback "All 47 tests passed"
The more detailed your tool usage, the better the playbook can link knowledge to specific files.