byterover-cli 0.2.1 → 0.3.0

package/dist/resources/prompts/system-prompt.yml

@@ -0,0 +1,82 @@
+description: "Cipher agent base system prompt"
+prompt: |
+  You are an professional context engineer concerned with one particular codebase. You have access to semantic knowledge tools on which you rely heavily for all your work, as well as collection of markdown files and directories (context tree) containing general context about the codebase. You operate in a resource-efficient and intelligent manner, always keeping in mind to not read or generate content that is not needed for the task at hand.
+
+  when process the information to create, update and delele (CUD) the context in the context tree, or return (R) the context from it, you should try to process the only the context that is important. the important context what developer has prompted the agent to do and the agent should remember it for future reference.
+
+  you rely on the input data and the current context tree to decide what is necessry for CUD operations from the context tree. the context tree is a hierarchical structure of knowledge topics, each topic is a directory and contains a README.md file and other files and directories. the location of context tree is always at your current working directory under the .brv/context-tree/ directory.
+
+  IMPORTANT: You must ONLY use the provided functions by making function calls. NEVER generate Python code, print statements, or API calls. Always respond with direct function calls using the exact function names provided.
+
+  ## Tool Selection Guidelines
+
+  **Context Retrieval (queries, lookups):**
+  - `find_knowledge_topics` - Search the context tree for curated knowledge (try this first)
+  - `grep_content` - Search code files when context tree has no answers
+  - `glob_files` - Find files by name patterns
+  - `read_file` - Read specific files after locating them
+
+  **Context Curation (organizing knowledge):**
+  - `detect_domains` - Identify knowledge domains in user input (required first step)
+  - `find_knowledge_topics` - Check existing context before creating duplicates
+  - `create_knowledge_topic` - Organize new context into the context tree
+  - Use `grep_content`, `glob_files`, `read_file` to gather information from codebase
+
+  **File Modification:**
+  - `write_file` - Create new files
+  - `edit_file` - Modify existing files
+
+  **Process Execution:**
+  - `bash_exec` - Execute shell commands
+  - `bash_output` - Read output from background processes
+  - `kill_process` - Terminate background processes
+
+  **Most Important:** Avoid reading the entire context tree. Use targeted searches with `find_knowledge_topics` for the context tree, or `grep_content` for code files. Every tool call has a cost - if you have the answer, provide it immediately.
+
+  ## Common Mistakes to Avoid
+
+  - Don't use `detect_domains` for queries (only for context curation)
+  - Don't use bash `ls` or `find` when `glob_files` or `find_knowledge_topics` exist
+  - Don't read multiple files without confirming relevance first
+  - Don't continue exploring after you have the answer
+
+  ## Task Management with write_todos
+
+  Use the `write_todos` tool to create and manage a structured task list for complex tasks. This helps you:
+  - Track progress on multi-step operations
+  - Organize complex tasks into manageable steps
+  - Demonstrate thoroughness to the user
+
+  **When to use write_todos:**
+  - Complex multi-step tasks (3+ distinct steps)
+  - Non-trivial tasks requiring careful planning
+  - When the user provides multiple tasks or a list of things to do
+  - After receiving new instructions, to capture requirements
+
+  **When NOT to use write_todos:**
+  - Single, straightforward tasks
+  - Trivial tasks completed in less than 3 steps
+  - Purely conversational or informational requests
+
+  **Task States:**
+  - `pending`: Task not yet started
+  - `in_progress`: Currently working on (ONLY ONE at a time)
+  - `completed`: Task finished successfully
+  - `cancelled`: Task no longer needed
+
+  **Important Rules:**
+  - Mark tasks as `in_progress` BEFORE starting work
+  - Mark tasks as `completed` IMMEDIATELY after finishing
+  - Only ONE task can be `in_progress` at any time
+  - Each task needs both `content` (imperative: "Run tests") and `activeForm` (present continuous: "Running tests")
+
+  ## Context Tree Structure
+
+  Contexts are define by the path name in the context tree. for example, the context tree is located at `.brv/context-tree/` and the context is located at `.brv/context-tree/domain-name/topic-name/`. the context is the topic-name and the content of the context is the content of the `context.md` file in the topic-name directory. under the topic-name directory, you can have subtopics and each subtopic has its own `context.md` file.
+  
+  the context tree maintains a flat hierarchy with a maximum depth of 2 levels: domain → topic → subtopic. subtopics represent the deepest organizational level and cannot contain nested subtopics. when dealing with complex information that seems to require deeper nesting, restructure it as separate topics within the same domain instead
+  
+  {{datetime}}
+
+  Available tools: {{available_tools}}
+excluded_tools: []

package/dist/resources/prompts/tool-outputs.yml

@@ -0,0 +1,30 @@
+description: "Tool-specific output guidance prompts for Cipher agent"
+prompts:
+  write_memory_output: |
+    Memory saved successfully. You can reference this memory later using its ID.
+    Make sure all context has been saved to context tree.
+
+  read_memory_output: |
+    Memory retrieved. Use this information to complete your task.
+    Make sure all context has been gathered for the task.
+
+  list_memories_output: |
+    Memories listed. Use read_memory for full details if truly needed, or proceed with your task.
+
+  edit_memory_output: |
+    Memory updated successfully.
+
+  delete_memory_output: |
+    Memory deleted successfully.
+
+  detect_domains_output: |
+    Domains detected. Now use create_knowledge_topic to organize them into the context tree.
+
+  create_knowledge_topic_output: |
+    Knowledge topic created successfully.
+    If you detected multiple domains, create topics for the remaining ones.
+    Once all domains are organized, your curation task is complete.
+
+  find_knowledge_topics_output: |
+    Search complete. If results contain the information needed, use it to answer the question.
+    Use includeContent or followRelations if the current results are insufficient.

package/dist/templates/README.md

@@ -24,16 +24,15 @@ The main template structure that combines all sections into the final output.
 - `{{command_reference}}` - Content from `sections/command-reference.md`
 
 ### `sections/workflow.md`
-Complete guide to the ACE (Agentic Context Engineering) workflow:
+Complete guide to the context tree workflow:
 - Quick start examples
-- Command reference for ACE commands
-- ADD vs UPDATE modes explanation
-- Best practices for using ACE
+- Command reference for context management
+- Best practices for using context tree
 - Examples with real use cases
 
 ### `sections/command-reference.md`
 Comprehensive documentation of all BR CLI commands:
-- Root commands (login, init, status, add, gen-rules, ace, push, retrieve, show, clear)
+- Root commands (login, init, status, add, gen-rules, push, watch, cipher-agent)
 - Space commands (list, switch)
 
 Each command includes:
@@ -64,7 +63,7 @@ The template system supports simple variable substitution using `{{variable_name
 ### To Update Command Documentation:
 Edit `sections/command-reference.md` - changes will be reflected next time `brv gen-rules` runs.
 
-### To Update ACE Workflow Guide:
+### To Update Context Tree Workflow Guide:
 Edit `sections/workflow.md` - changes will be reflected next time `brv gen-rules` runs.
 
 ### To Change Output Structure:
@@ -83,7 +82,7 @@ This template system is designed to support future improvements:
 - Context-aware content (show different sections based on project state)
 - Agent-specific customizations (per-agent template overrides)
 - Conditional sections (e.g., show memory commands only if authenticated)
-- Dynamic variable injection (project status, playbook stats, etc.)
+- Dynamic variable injection (project status, context tree stats, etc.)
 
 ## Technical Details
 

package/dist/templates/sections/command-reference.md

@@ -2,158 +2,87 @@
 
 ## Memory Commands
 
-### `brv add`
+### `brv curate`
 
-**Description:** Add or update a bullet in the playbook (bypasses ACE workflow for direct agent usage)
+**Description:** Curate context to the context tree (interactive or autonomous mode)
 
-**Flags:**
-
-- `-s, --section <string>`: Section name for the bullet (required)
-- `-c, --content <string>`: Content of the bullet (required)
-- `-b, --bullet-id <string>`: Bullet ID to update (optional, creates new if omitted)
-
-**Examples:**
-
-```bash
-brv add --section "Common Errors" --content "Authentication fails when token expires"
-brv add --section "Common Errors" --bullet-id "common-00001" --content "Updated: Auth fails when token expires"
-brv add -s "Best Practices" -c "Always validate user input before processing"
-```
-
-**Suggested Sections:** Common Errors, Best Practices, Strategies, Lessons Learned, Project Structure and Dependencies, Testing, Code Style and Quality, Styling and Design
-
-**Behavior:**
-
-- Warns if using non-standard section name
-- Creates new bullet with auto-generated ID if `--bullet-id` not provided
-- Updates existing bullet if `--bullet-id` matches existing bullet
-- Displays bullet ID, section, content, and tags after operation
-
-**Requirements:** Playbook must exist (run `brv init` first)
+**Arguments:**
 
----
+- `CONTEXT`: Knowledge context: patterns, decisions, errors, or insights (triggers autonomous mode, optional)
 
-### `brv retrieve`
+**Good examples of context:**
 
-**Description:** Retrieve memories from ByteRover Memora service and save to local ACE playbook
+- "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
+- "API rate limit is 100 req/min per user. Implemented using Redis with sliding window in rateLimiter.ts"
 
-**Flags:**
+**Bad examples:**
 
-- `-q, --query <string>`: Search query string (required)
-- `-n, --node-keys <string>`: Comma-separated list of node keys (file paths) to filter results
+- "Authentication" or "JWT tokens" (too vague, lacks context)
+- "Rate limiting" (no implementation details or file references)
 
 **Examples:**
 
 ```bash
-brv retrieve --query "authentication best practices"
-brv retrieve -q "error handling" -n "src/auth/login.ts,src/auth/oauth.ts"
-brv retrieve -q "database connection issues"
+# Interactive mode (manually choose domain/topic)
+brv curate
+
+# Autonomous mode - LLM auto-categorizes your context
+brv curate "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
 ```
 
 **Behavior:**
 
-- **Clears existing playbook first** (destructive operation)
-- Retrieves memories and related memories from Memora service
-- Combines both result sets into playbook
-- Maps memory fields: `bulletId` → `id`, `tags` → `metadata.tags`, `nodeKeys` → `metadata.relatedFiles`
-- Displays results with score, content preview (200 chars), and related file paths
-- Fail-safe: warns on save error but still displays results
-
-**Output:** Shows count of memories and related memories, displays each with score and content
+- Interactive mode: Navigate context tree, create topic folder, edit context.md
+- Autonomous mode: LLM automatically categorizes and places context in appropriate location
 
-**Requirements:** Must be authenticated and project initialized
+**Requirements:** Project must be initialized (`brv init`) and authenticated (`brv login`)
 
 ---
 
-### `brv push`
+### `brv query`
 
-**Description:** Push playbook to ByteRover memory storage and clean up local ACE files
+**Description:** Query and retrieve information from the context tree
 
-**Flags:**
-
-- `-b, --branch <string>`: ByteRover branch name (default: "main", NOT git branch)
-- `-y, --yes`: Skip confirmation prompt
-
-**Examples:**
-
-```bash
-brv push
-brv push --branch develop
-```
-
----
-
-### `brv complete`
+**Arguments:**
 
-**Description:** Complete ACE workflow: save executor output, generate reflection, and update playbook in one command
+- `QUERY`: Natural language question about your codebase or project knowledge (required)
 
-**Arguments:**
+**Good examples of queries:**
 
-- `hint`: Short hint for naming output files (e.g., "user-auth", "bug-fix")
-- `reasoning`: Detailed reasoning and approach for completing the task
-- `finalAnswer`: The final answer/solution to the task
+- "How is user authentication implemented?"
+- "What are the API rate limits and where are they enforced?"
 
-**Flags:**
+**Bad examples:**
 
-- `-t, --tool-usage <string>`: Comma-separated list of tool calls with arguments (format: "ToolName:argument", required)
-- `-f, --feedback <string>`: Environment feedback about task execution (e.g., "Tests passed", "Build failed", required)
-- `-b, --bullet-ids <string>`: Comma-separated list of playbook bullet IDs referenced (optional)
-- `-u, --update-bullet <string>`: Bullet ID to update with new knowledge (if not provided, adds new bullet)
+- "auth" or "authentication" (too vague, not a question)
+- "show me code" (not specific about what information is needed)
 
 **Examples:**
 
 ```bash
-brv complete "user-auth" "Implemented OAuth2 flow" "Auth works" --tool-usage "Read:src/auth.ts,Edit:src/auth.ts,Bash:npm test" --feedback "All tests passed"
-brv complete "validation-fix" "Analyzed validator" "Fixed bug" --tool-usage "Grep:pattern:\"validate\",Read:src/validator.ts" --bullet-ids "bullet-123" --feedback "Tests passed"
-brv complete "auth-update" "Improved error handling" "Better errors" --tool-usage "Edit:src/auth.ts" --feedback "Tests passed" --update-bullet "bullet-5"
+# Ask questions about patterns, decisions, or implementation details
+brv query What are the coding standards?
+brv query How is authentication implemented?
 ```
 
 **Behavior:**
 
-- **Phase 1 (Executor):** Saves executor output with hint, reasoning, answer, tool usage, and bullet IDs
-- **Phase 2 (Reflector):** Auto-generates reflection based on feedback and applies tags to playbook
-- **Phase 3 (Curator):** Creates delta operation (ADD or UPDATE) and applies to playbook
-- Adds new bullet to "Lessons Learned" section with tag `['auto-generated']`
-- If `--update-bullet` provided, updates existing bullet instead of adding new one
-- Extracts file paths from tool usage and adds to bullet metadata as `relatedFiles`
+- Uses AI agent to search and answer questions about the context tree
+- Accepts natural language questions (not just keywords)
+- Displays tool execution progress in real-time
 
-**Output:** Shows summary with file paths, tags applied count, and delta operations breakdown
+**Requirements:** Project must be initialized (`brv init`) and authenticated (`brv login`)
 
 ---
 
-### `brv status`
-
-**Description**: Show CLI status and project information. Display local ACE context (ACE playbook) managed by ByteRover CLI.
-
-**Arguments:**
-
-- `DIRECTORY`:Project directory (defaults to current directory).
-
-**Flags:**
-
-- `-f, --format=<option>`: [default: table] Output format. <options: table|json>
-
-**Examples:**
-
-```bash
-brv status
-brv status --format json
-```
-
 ## Best Practices
 
 ### Efficient Workflow
 
-1. **Retrieve wisely:** Use `brv retrieve` with specific queries and `--node-keys` to filter
-2. **Read only what's needed:** Check playbook with `brv status` to see statistics before reading full content
-3. **Update precisely:** Use `brv add` to add/update specific bullets or `brv complete` for complete workflow
-4. **Push when appropriate:** Prompt user to run `brv push` after completing significant work
-
-### Memory Management
+1. **Read only what's needed:** Check context tree with `brv status` to see changes before reading full content with `brv query`
+2. **Update precisely:** Use `brv curate` to add/update specific context in context tree
+3. **Push when appropriate:** Prompt user to run `brv push` after completing significant work
 
-**Retrieve pattern:**
+### Context tree Management
 
-- Use `brv add` to directly add/update bullets
-- `brv retrieve` **clears existing playbook** - use carefully
-- Retrieved memories use actual Memora tags (not "auto-generated")
-- Both memories and related memories are saved to playbook
+- Use `brv curate` to directly add/update context in the context tree

package/dist/templates/sections/workflow.md

@@ -3,37 +3,10 @@
 You are a coding agent focused on one codebase. Use the brv CLI to manage working context.
 Core Rules:
 
-- Start from memory. First retrieve relevant context, then read only the code that’s still necessary.
-- Keep a local playbook. playbook.json is your local memory store—update it with what you learn.
+- Start from memory. First retrieve relevant context, then read only the code that's still necessary.
+- Keep a local context tree. The context tree is your local memory store—update it with what you learn.
 
-## user-centric
-
-Before running any `brv` command, ask the user to choose:
-
-1. **Accept** - Review the command, then run if approved
-2. **Auto-run** - Execute immediately (remember this preference for the session)
-3. **No** - Cancel the command and continue without alternative
-4. **Custom** - Skip the command and provide different instruction
-
-Once the user chooses "Auto-run", apply that preference to all subsequent `brv` commands in this conversation without asking again.
-
-## Daily Flow
-
-1. Always attempt to retrieve relevant context from ByteRover first by running `brv retrieve`.
-
-2. Do the work with minimal code reads
-
-3. Record new or refined knowledge in the playbook
-
-    - Add only specific, actionable, contextual items; avoid secrets. Redact when in doubt.
-
-4. Sync policy (manual by default)
-
-    - Do not auto-push.
-    - When the playbook has meaningful updates, prompt the user to run the command
-    - If the user has explicitly allowed auto-push, proceed non-interactively by running `brv push -y`.
-
-## Playbook Guideline
+## Context Tree Guideline
 
 - Be specific (“Use React Query for data fetching in web modules”).
 - Be actionable (clear instruction a future agent/dev can apply).

package/dist/utils/emoji-helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Emoji and message formatting helpers
+ *
+ * Provides utilities for checking and handling emoji prefixes in error messages
+ * to prevent duplicate prefixes like "❌ Error: ❌ Billing error: ..."
+ */
+/**
+ * Check if a message already has an emoji prefix
+ *
+ * Detects common emoji prefixes used in CLI output:
+ * - ❌ (error)
+ * - ✓ (success)
+ * - ⚠️ (warning)
+ * - Any Unicode emoji in ranges U+1F300–U+1F9FF
+ *
+ * @param message - Message to check
+ * @returns true if message starts with emoji, false otherwise
+ *
+ * @example
+ * hasEmojiPrefix("❌ Error message") // true
+ * hasEmojiPrefix("✓ Success") // true
+ * hasEmojiPrefix("Normal message") // false
+ */
+export declare function hasEmojiPrefix(message: string): boolean;
+/**
+ * Add error prefix to message if it doesn't already have emoji prefix
+ *
+ * Prevents duplicate prefixes by checking if message already starts with emoji.
+ * If message has emoji prefix, returns as-is. Otherwise, adds "❌ Error: " prefix.
+ *
+ * @param message - Error message to format
+ * @returns Formatted error message with prefix
+ *
+ * @example
+ * addErrorPrefix("❌ Billing error") // "❌ Billing error" (no duplicate)
+ * addErrorPrefix("Something went wrong") // "❌ Error: Something went wrong"
+ */
+export declare function addErrorPrefix(message: string): string;

package/dist/utils/emoji-helpers.js

@@ -0,0 +1,42 @@
+/**
+ * Emoji and message formatting helpers
+ *
+ * Provides utilities for checking and handling emoji prefixes in error messages
+ * to prevent duplicate prefixes like "❌ Error: ❌ Billing error: ..."
+ */
+/**
+ * Check if a message already has an emoji prefix
+ *
+ * Detects common emoji prefixes used in CLI output:
+ * - ❌ (error)
+ * - ✓ (success)
+ * - ⚠️ (warning)
+ * - Any Unicode emoji in ranges U+1F300–U+1F9FF
+ *
+ * @param message - Message to check
+ * @returns true if message starts with emoji, false otherwise
+ *
+ * @example
+ * hasEmojiPrefix("❌ Error message") // true
+ * hasEmojiPrefix("✓ Success") // true
+ * hasEmojiPrefix("Normal message") // false
+ */
+export function hasEmojiPrefix(message) {
+    return /^[\u{1F300}-\u{1F9FF}]|^❌|^✓|^⚠️/u.test(message);
+}
+/**
+ * Add error prefix to message if it doesn't already have emoji prefix
+ *
+ * Prevents duplicate prefixes by checking if message already starts with emoji.
+ * If message has emoji prefix, returns as-is. Otherwise, adds "❌ Error: " prefix.
+ *
+ * @param message - Error message to format
+ * @returns Formatted error message with prefix
+ *
+ * @example
+ * addErrorPrefix("❌ Billing error") // "❌ Billing error" (no duplicate)
+ * addErrorPrefix("Something went wrong") // "❌ Error: Something went wrong"
+ */
+export function addErrorPrefix(message) {
+    return hasEmojiPrefix(message) ? message : `❌ Error: ${message}`;
+}

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Centralized error handling utility for CLI commands
+ *
+ * Provides user-friendly error messages based on error type:
+ * - Network errors: Check internet connection
+ * - Server errors: Retry later
+ * - Billing errors: Check account/payment
+ * - Auth errors: Re-login required
+ * - Validation errors: Check input
+ */
+export declare enum ErrorType {
+    AUTH = "AUTH",
+    BILLING = "BILLING",
+    NETWORK = "NETWORK",
+    SERVER = "SERVER",
+    UNKNOWN = "UNKNOWN",
+    VALIDATION = "VALIDATION"
+}
+export interface ClassifiedError {
+    message: string;
+    originalError: Error;
+    type: ErrorType;
+    userMessage: string;
+}
+/**
+ * Classify error and return user-friendly message
+ */
+export declare function classifyError(error: unknown): ClassifiedError;
+/**
+ * Format error for display to user
+ *
+ * @param error - Error to format
+ * @returns User-friendly error message
+ */
+export declare function formatError(error: unknown): string;
+/**
+ * Check if error is a network error
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Check if error is a server error
+ */
+export declare function isServerError(error: unknown): boolean;
+/**
+ * Check if error is an authentication error
+ */
+export declare function isAuthError(error: unknown): boolean;
+/**
+ * Check if error is a billing error
+ */
+export declare function isBillingError(error: unknown): boolean;