codemaster-cli 2.2.0__py3-none-any.whl

vibe/core/tools/builtins/prompts/ask_user_question.md

@@ -0,0 +1,84 @@
+Use `ask_user_question` to gather information from the user when you need clarification, want to validate assumptions, or need help making a decision. **Don't hesitate to use this tool** - it's better to ask than to guess wrong.
+
+## When to Use
+
+- **Clarifying requirements**: Ambiguous instructions, unclear scope
+- **Technical decisions**: Architecture choices, library selection, tradeoffs
+- **Preference gathering**: UI style, naming conventions, approach options
+- **Validation**: Confirming understanding before starting significant work
+- **Multiple valid paths**: When several approaches could work and you want user input
+
+## Question Structure
+
+Each question has these fields:
+
+- `question`: The full question text (be specific and clear)
+- `header`: A short label displayed as a chip (max 12 characters, e.g., "Auth", "Database", "Approach")
+- `options`: 2-4 choices (an "Other" option is automatically added for free text)
+- `multi_select`: Set to `true` if user can pick multiple options (default: `false`)
+
+### Options Structure
+
+Each option has:
+- `label`: Short display text (1-5 words)
+- `description`: Brief explanation of what this choice means or its implications
+
+## Examples
+
+**Single question with recommended option:**
+```json
+{
+  "questions": [{
+    "question": "Which authentication method should we use?",
+    "header": "Auth",
+    "options": [
+      {"label": "JWT tokens (Recommended)", "description": "Stateless, scalable, works well with APIs"},
+      {"label": "Session cookies", "description": "Traditional approach, requires session storage"},
+      {"label": "OAuth 2.0", "description": "Third-party auth, more complex setup"}
+    ],
+    "multi_select": false
+  }]
+}
+```
+
+**Multiple questions (displayed as tabs):**
+```json
+{
+  "questions": [
+    {
+      "question": "Which database should we use?",
+      "header": "Database",
+      "options": [
+        {"label": "PostgreSQL", "description": "Relational, ACID compliant"},
+        {"label": "MongoDB", "description": "Document store, flexible schema"}
+      ],
+      "multi_select": false
+    },
+    {
+      "question": "Which features should be included in v1?",
+      "header": "Features",
+      "options": [
+        {"label": "User auth", "description": "Login, signup, password reset"},
+        {"label": "Search", "description": "Full-text search across content"},
+        {"label": "Export", "description": "CSV and PDF export"}
+      ],
+      "multi_select": true
+    }
+  ]
+}
+```
+
+## Key Constraints
+
+- **Header max length**: 12 characters (keeps UI clean)
+- **Options count**: 2-4 per question (plus automatic "Other")
+- **Questions count**: 1-4 per call
+- **Label length**: Keep to 1-5 words for readability
+
+## Tips
+
+1. **Put recommended option first** and add "(Recommended)" to its label
+2. **Use descriptive headers** that categorize the question type
+3. **Keep descriptions concise** but informative about tradeoffs
+4. **Use multi_select** when choices aren't mutually exclusive (e.g., features to include)
+5. **Ask early** - it's better to clarify before starting than to redo work

vibe/core/tools/builtins/prompts/bash.md

@@ -0,0 +1,73 @@
+Use the `bash` tool to run one-off shell commands.
+
+**Key characteristics:**
+- **Stateless**: Each command runs independently in a fresh environment
+
+**Timeout:**
+- The `timeout` argument controls how long the command can run before being killed
+- When `timeout` is not specified (or set to `None`), the config default is used
+- If a command is timing out, do not hesitate to increase the timeout using the `timeout` argument
+
+**IMPORTANT: Use dedicated tools if available instead of these bash commands:**
+
+**File Operations - DO NOT USE:**
+- `cat filename` → Use `read_file(path="filename")`
+- `head -n 20 filename` → Use `read_file(path="filename", limit=20)`
+- `tail -n 20 filename` → Read with offset: `read_file(path="filename", offset=<line_number>, limit=20)`
+- `sed -n '100,200p' filename` → Use `read_file(path="filename", offset=99, limit=101)`
+- `less`, `more`, `vim`, `nano` → Use `read_file` with offset/limit for navigation
+- `echo "content" > file` → Use `write_file(path="file", content="content")`
+- `echo "content" >> file` → Read first, then `write_file` with overwrite=true
+
+**Search Operations - DO NOT USE:**
+- `grep -r "pattern" .` → Use `grep(pattern="pattern", path=".")`
+- `find . -name "*.py"` → Use `bash("ls -la")` for current dir or `grep` with appropriate pattern
+- `ag`, `ack`, `rg` commands → Use the `grep` tool
+- `locate` → Use `grep` tool
+
+**File Modification - DO NOT USE:**
+- `sed -i 's/old/new/g' file` → Use `search_replace` tool
+- `awk` for file editing → Use `search_replace` tool
+- Any in-place file editing → Use `search_replace` tool
+
+**APPROPRIATE bash uses:**
+- System information: `pwd`, `whoami`, `date`, `uname -a`
+- Directory listings: `ls -la`, `tree` (if available)
+- Git operations: `git status`, `git log --oneline -10`, `git diff`
+- Process info: `ps aux | grep process`, `top -n 1`
+- Network checks: `ping -c 1 google.com`, `curl -I https://example.com`
+- Package management: `pip list`, `npm list`
+- Environment checks: `env | grep VAR`, `which python`
+- File metadata: `stat filename`, `file filename`, `wc -l filename`
+
+**Example: Reading a large file efficiently**
+
+WRONG:
+```bash
+bash("cat large_file.txt")  # May hit size limits
+bash("head -1000 large_file.txt")  # Inefficient
+```
+
+RIGHT:
+```python
+# First chunk
+read_file(path="large_file.txt", limit=1000)
+# If was_truncated=true, read next chunk
+read_file(path="large_file.txt", offset=1000, limit=1000)
+```
+
+**Example: Searching for patterns**
+
+WRONG:
+```bash
+bash("grep -r 'TODO' src/")  # Don't use bash for grep
+bash("find . -type f -name '*.py' | xargs grep 'import'")  # Too complex
+```
+
+RIGHT:
+```python
+grep(pattern="TODO", path="src/")
+grep(pattern="import", path=".")
+```
+
+**Remember:** Bash is best for quick system checks and git operations. For file operations, searching, and editing, always use the dedicated tools when they are available.

vibe/core/tools/builtins/prompts/grep.md

@@ -0,0 +1,4 @@
+Use `grep` to recursively search for a regular expression pattern in files.
+
+- It's very fast and automatically ignores files that you should not read like .pyc files, .venv directories, etc.
+- Use this to find where functions are defined, how variables are used, or to locate specific error messages.

vibe/core/tools/builtins/prompts/read_file.md

@@ -0,0 +1,13 @@
+Use `read_file` to read the content of a file. It's designed to handle large files safely.
+
+- By default, it reads from the beginning of the file.
+- Use `offset` (line number) and `limit` (number of lines) to read specific parts or chunks of a file. This is efficient for exploring large files.
+- The result includes `was_truncated: true` if the file content was cut short due to size limits.
+
+**Strategy for large files:**
+
+1. Call `read_file` with a `limit` (e.g., 1000 lines) to get the start of the file.
+2. If `was_truncated` is true, you know the file is large.
+3. To read the next chunk, call `read_file` again with an `offset`. For example, `offset=1000, limit=1000`.
+
+This is more efficient than using `bash` with `cat` or `wc`.

vibe/core/tools/builtins/prompts/search_replace.md

@@ -0,0 +1,43 @@
+Use `search_replace` to make targeted changes to files using SEARCH/REPLACE blocks. This tool finds exact text matches and replaces them.
+
+Arguments:
+- `file_path`: The path to the file to modify
+- `content`: The SEARCH/REPLACE blocks defining the changes
+
+The content format is:
+
+```
+<<<<<<< SEARCH
+[exact text to find in the file]
+=======
+[exact text to replace it with]
+>>>>>>> REPLACE
+```
+
+You can include multiple SEARCH/REPLACE blocks to make multiple changes to the same file:
+
+```
+<<<<<<< SEARCH
+def old_function():
+    return "old value"
+=======
+def new_function():
+    return "new value"
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+import os
+=======
+import os
+import sys
+>>>>>>> REPLACE
+```
+
+IMPORTANT:
+
+- The SEARCH text must match EXACTLY (including whitespace, indentation, and line endings)
+- The SEARCH text must appear exactly once in the file - if it appears multiple times, the tool will error
+- Use at least 5 equals signs (=====) between SEARCH and REPLACE sections
+- The tool will provide detailed error messages showing context if search text is not found
+- Each search/replace block is applied in order, so later blocks see the results of earlier ones
+- Be careful with escape sequences in string literals - use \n not \\n for newlines in code

vibe/core/tools/builtins/prompts/task.md

@@ -0,0 +1,24 @@
+Use `task` to delegate work to a subagent for independent execution.
+
+## When to Use This Tool
+
+- **Context management**: Delegate tasks that would consume too much main conversation context
+- **Specialized work**: Use the appropriate subagent for the type of task (exploration, research, etc.)
+- **Parallel execution**: Launch multiple subagents for independent tasks
+- **Autonomous work**: Tasks that don't require back-and-forth with the user
+
+## Best Practices
+
+1. **Write clear, detailed task descriptions** - The subagent works autonomously, so provide enough context for it to succeed independently
+
+2. **Choose the right subagent** - Match the subagent to the task type (see available subagents in system prompt)
+
+3. **Prefer direct tools for simple operations** - If you know exactly which file to read or pattern to search, use those tools directly instead of spawning a subagent
+
+4. **Trust the subagent's judgment** - Let it explore and find information without micromanaging the approach
+
+## Limitations
+
+- Subagents cannot write or modify files
+- Subagents cannot ask the user questions
+- Results are returned as text when the subagent completes

vibe/core/tools/builtins/prompts/todo.md

@@ -0,0 +1,199 @@
+Use the `todo` tool to manage a simple task list. This tool helps you track tasks and their progress.
+
+## How it works
+
+- **Reading:** Use `action: "read"` to view the current todo list
+- **Writing:** Use `action: "write"` with the complete `todos` list to update. You must provide the ENTIRE list - this replaces everything.
+
+## Todo Structure
+Each todo item has:
+- `id`: A unique string identifier (e.g., "1", "2", "task-a")
+- `content`: The task description
+- `status`: One of: "pending", "in_progress", "completed", "cancelled"
+- `priority`: One of: "high", "medium", "low"
+
+## When to Use This Tool
+
+**Use proactively for:**
+- Complex multi-step tasks (3+ distinct steps)
+- Non-trivial tasks requiring careful planning
+- Multiple tasks provided by the user (numbered or comma-separated)
+- Tracking progress on ongoing work
+- After receiving new instructions - immediately capture requirements
+- When starting work - mark task as in_progress BEFORE beginning
+- After completing work - mark as completed and add any follow-up tasks discovered
+
+**Skip this tool for:**
+- Single, straightforward tasks
+- Trivial operations (< 3 simple steps)
+- Purely conversational or informational requests
+- Tasks that provide no organizational benefit
+
+## Task Management Best Practices
+
+1. **Status Management:**
+   - Only ONE task should be `in_progress` at a time
+   - Mark tasks `in_progress` BEFORE starting work on them
+   - Mark tasks `completed` IMMEDIATELY after finishing
+   - Keep tasks `in_progress` if blocked or encountering errors
+
+2. **Task Completion Rules:**
+   - ONLY mark as `completed` when FULLY accomplished
+   - Never mark complete if tests are failing, implementation is partial, or errors are unresolved
+   - When blocked, create a new task describing what needs resolution
+
+3. **Task Organization:**
+   - Create specific, actionable items
+   - Break complex tasks into manageable steps
+   - Use clear, descriptive task names
+   - Remove irrelevant tasks entirely (don't just mark cancelled)
+
+## Examples
+
+**Example 1: Reading todos**
+```json
+{
+  "action": "read"
+}
+```
+
+**Example 2: Initial task creation (user requests multiple features)**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Add dark mode toggle to settings",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "Implement theme context/state management",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update components for theme switching",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "4",
+      "content": "Run tests and verify build",
+      "status": "pending",
+      "priority": "medium"
+    }
+  ]
+}
+```
+
+**Example 3: Starting work (marking one task in_progress)**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Add dark mode toggle to settings",
+      "status": "in_progress",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "Implement theme context/state management",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update components for theme switching",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "4",
+      "content": "Run tests and verify build",
+      "status": "pending",
+      "priority": "medium"
+    }
+  ]
+}
+```
+
+**Example 4: Completing task and adding discovered subtask**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Add dark mode toggle to settings",
+      "status": "completed",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "Implement theme context/state management",
+      "status": "in_progress",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update components for theme switching",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "4",
+      "content": "Fix TypeScript errors in theme types",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "5",
+      "content": "Run tests and verify build",
+      "status": "pending",
+      "priority": "medium"
+    }
+  ]
+}
+```
+
+**Example 5: Handling blockers (keeping task in_progress)**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Deploy to production",
+      "status": "in_progress",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "BLOCKER: Fix failing deployment pipeline",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update documentation",
+      "status": "pending",
+      "priority": "low"
+    }
+  ]
+}
+```
+
+## Common Scenarios
+
+**Multi-file refactoring:** Create todos for each file that needs updating
+**Performance optimization:** List specific bottlenecks as individual tasks
+**Bug fixing:** Track reproduction, diagnosis, fix, and verification as separate tasks
+**Feature implementation:** Break down into UI, logic, tests, and documentation tasks
+
+Remember: When writing, you must include ALL todos you want to keep. Any todo not in the list will be removed. Be proactive with task management to demonstrate thoroughness and ensure all requirements are completed successfully.

vibe/core/tools/builtins/prompts/write_file.md

@@ -0,0 +1,42 @@
+Use `write_file` to write content to a file.
+
+**Arguments:**
+- `path`: The file path (relative or absolute)
+- `content`: The content to write to the file
+- `overwrite`: Must be set to `true` to overwrite an existing file (default: `false`)
+
+**IMPORTANT SAFETY RULES:**
+
+- By default, the tool will **fail if the file already exists** to prevent accidental data loss
+- To **overwrite** an existing file, you **MUST** set `overwrite: true`
+- To **create a new file**, just provide the `path` and `content` (overwrite defaults to false)
+- If parent directories don't exist, they will be created automatically
+
+**BEST PRACTICES:**
+
+- **ALWAYS** use the `read_file` tool first before overwriting an existing file to understand its current contents
+- **ALWAYS** prefer using `search_replace` to edit existing files rather than overwriting them completely
+- **NEVER** write new files unless explicitly required - prefer modifying existing files
+- **NEVER** proactively create documentation files (*.md) or README files unless explicitly requested
+- **AVOID** using emojis in file content unless the user explicitly requests them
+
+**Usage Examples:**
+
+```python
+# Create a new file (will error if file exists)
+write_file(
+    path="src/new_module.py",
+    content="def hello():\n    return 'Hello World'"
+)
+
+# Overwrite an existing file (must read it first!)
+# First: read_file(path="src/existing.py")
+# Then:
+write_file(
+    path="src/existing.py",
+    content="# Updated content\ndef new_function():\n    pass",
+    overwrite=True
+)
+```
+
+**Remember:** For editing existing files, prefer `search_replace` over `write_file` to preserve unchanged portions and avoid accidental data loss.