feat: Created the Oracle agent to handle high-level architectural decisions and design questions about a given codebase
This commit is contained in:
@@ -0,0 +1,17 @@
|
||||
# Oracle
|
||||
|
||||
An AI agent specialized in high-level architecture, complex debugging, and design decisions.
|
||||
|
||||
This agent is designed to be delegated to by the **[Sisyphus](../sisyphus/README.md)** agent when deep reasoning, architectural advice,
|
||||
or complex problem-solving is required. Sisyphus acts as the coordinator, while Oracle provides the expert analysis and
|
||||
recommendations.
|
||||
|
||||
It can also be used as a standalone tool for design reviews and solving difficult technical challenges.
|
||||
|
||||
## Features
|
||||
|
||||
- 🏛️ System architecture and design patterns
|
||||
- 🐛 Complex debugging and root cause analysis
|
||||
- ⚖️ Tradeoff analysis and technology selection
|
||||
- 📝 Code review and best practices advice
|
||||
- 🧠 Deep reasoning for ambiguous problems
|
||||
@@ -0,0 +1,82 @@
|
||||
name: oracle
|
||||
description: High-IQ advisor for architecture, debugging, and complex decisions
|
||||
version: 1.0.0
|
||||
temperature: 0.2
|
||||
top_p: 0.95
|
||||
|
||||
variables:
|
||||
- name: project_dir
|
||||
description: Project directory for context
|
||||
default: '.'
|
||||
|
||||
global_tools:
|
||||
- fs_read.sh
|
||||
- fs_grep.sh
|
||||
- fs_glob.sh
|
||||
- fs_ls.sh
|
||||
- execute_command.sh
|
||||
|
||||
instructions: |
|
||||
You are Oracle - a senior architect and debugger consulted for complex decisions.
|
||||
|
||||
## Your Role
|
||||
|
||||
You are READ-ONLY. You analyze, advise, and recommend. You do NOT implement.
|
||||
|
||||
## When You're Consulted
|
||||
|
||||
1. **Architecture Decisions**: Multi-system tradeoffs, design patterns, technology choices
|
||||
2. **Complex Debugging**: After 2+ failed fix attempts, deep analysis needed
|
||||
3. **Code Review**: Evaluating proposed designs or implementations
|
||||
4. **Risk Assessment**: Security, performance, or reliability concerns
|
||||
|
||||
## File Reading Strategy (IMPORTANT - minimize token usage)
|
||||
|
||||
1. **Use grep to find relevant code** - `fs_grep --pattern "auth" --include "*.rs"` finds where things are
|
||||
2. **Read only what you need** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79
|
||||
3. **Never read entire large files** - If 500+ lines, grep first, then read the relevant section
|
||||
4. **Use glob to discover files** - `fs_glob --pattern "*.rs" --path src/`
|
||||
|
||||
## Your Process
|
||||
|
||||
1. **Understand**: Use grep/glob to find relevant code, then read targeted sections
|
||||
2. **Analyze**: Consider multiple angles and tradeoffs
|
||||
3. **Recommend**: Provide clear, actionable advice
|
||||
4. **Justify**: Explain your reasoning
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure your response as:
|
||||
|
||||
```
|
||||
## Analysis
|
||||
[Your understanding of the situation]
|
||||
|
||||
## Recommendation
|
||||
[Clear, specific advice]
|
||||
|
||||
## Reasoning
|
||||
[Why this is the right approach]
|
||||
|
||||
## Risks/Considerations
|
||||
[What to watch out for]
|
||||
|
||||
ORACLE_COMPLETE
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Never modify files** - You advise, others implement
|
||||
2. **Be thorough** - Read all relevant context before advising
|
||||
3. **Be specific** - General advice isn't helpful
|
||||
4. **Consider tradeoffs** - There are rarely perfect solutions
|
||||
5. **Stay focused** - Answer the specific question asked
|
||||
|
||||
## Context
|
||||
- Project: {{project_dir}}
|
||||
- CWD: {{__cwd__}}
|
||||
|
||||
conversation_starters:
|
||||
- 'Review this architecture design'
|
||||
- 'Help debug this complex issue'
|
||||
- 'Evaluate these implementation options'
|
||||
Executable
+131
@@ -0,0 +1,131 @@
|
||||
#!/usr/bin/env bash
|
||||
set -eo pipefail
|
||||
|
||||
# shellcheck disable=SC1090
|
||||
source "$LLM_PROMPT_UTILS_FILE"
|
||||
source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
|
||||
|
||||
# @env LLM_OUTPUT=/dev/stdout
|
||||
# @env LLM_AGENT_VAR_PROJECT_DIR=.
|
||||
# @describe Oracle agent tools for analysis and consultation (read-only)
|
||||
|
||||
_project_dir() {
|
||||
local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
|
||||
(cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
|
||||
}
|
||||
|
||||
# @cmd Read a file for analysis
|
||||
# @option --path! Path to the file (relative to project root)
|
||||
read_file() {
|
||||
local project_dir
|
||||
project_dir=$(_project_dir)
|
||||
# shellcheck disable=SC2154
|
||||
local full_path="${project_dir}/${argc_path}"
|
||||
|
||||
if [[ ! -f "${full_path}" ]]; then
|
||||
error "File not found: ${argc_path}" >> "$LLM_OUTPUT"
|
||||
return 1
|
||||
fi
|
||||
|
||||
{
|
||||
info "Reading: ${argc_path}"
|
||||
echo ""
|
||||
cat "${full_path}"
|
||||
} >> "$LLM_OUTPUT"
|
||||
}
|
||||
|
||||
# @cmd Get project structure and type
|
||||
get_project_info() {
|
||||
local project_dir
|
||||
project_dir=$(_project_dir)
|
||||
|
||||
local project_info
|
||||
project_info=$(detect_project "${project_dir}")
|
||||
|
||||
{
|
||||
info "Project Analysis" >> "$LLM_OUTPUT"
|
||||
cat <<-EOF
|
||||
|
||||
Type: $(echo "${project_info}" | jq -r '.type')
|
||||
Build: $(echo "${project_info}" | jq -r '.build')
|
||||
Test: $(echo "${project_info}" | jq -r '.test')
|
||||
|
||||
EOF
|
||||
|
||||
info "Structure:" >> "$LLM_OUTPUT"
|
||||
get_tree "${project_dir}" 3
|
||||
} >> "$LLM_OUTPUT"
|
||||
}
|
||||
|
||||
# @cmd Search for patterns in the codebase
|
||||
# @option --pattern! Pattern to search for
|
||||
# @option --file-type Filter by extension (e.g., "rs", "py")
|
||||
search_code() {
|
||||
local file_type="${argc_file_type:-}"
|
||||
local project_dir
|
||||
project_dir=$(_project_dir)
|
||||
|
||||
# shellcheck disable=SC2154
|
||||
info "Searching: ${argc_pattern}" >> "$LLM_OUTPUT"
|
||||
echo "" >> "$LLM_OUTPUT"
|
||||
|
||||
local include_arg=""
|
||||
if [[ -n "${file_type}" ]]; then
|
||||
include_arg="--include=*.${file_type}"
|
||||
fi
|
||||
|
||||
local results
|
||||
# shellcheck disable=SC2086
|
||||
results=$(grep -rn ${include_arg} "${argc_pattern}" "${project_dir}" 2>/dev/null | \
|
||||
grep -v '/target/' | \
|
||||
grep -v '/node_modules/' | \
|
||||
grep -v '/.git/' | \
|
||||
head -30) || true
|
||||
|
||||
if [[ -n "${results}" ]]; then
|
||||
echo "${results}" >> "$LLM_OUTPUT"
|
||||
else
|
||||
warn "No matches found" >> "$LLM_OUTPUT"
|
||||
fi
|
||||
}
|
||||
|
||||
# @cmd Run a read-only command for analysis (e.g., git log, cargo tree)
|
||||
# @option --command! Command to run
|
||||
analyze_with_command() {
|
||||
local project_dir
|
||||
project_dir=$(_project_dir)
|
||||
|
||||
local dangerous_patterns="rm |>|>>|mv |cp |chmod |chown |sudo|curl.*\\||wget.*\\|"
|
||||
# shellcheck disable=SC2154
|
||||
if echo "${argc_command}" | grep -qE "${dangerous_patterns}"; then
|
||||
error "Command appears to modify files or be dangerous. Oracle is read-only." >> "$LLM_OUTPUT"
|
||||
return 1
|
||||
fi
|
||||
|
||||
info "Running: ${argc_command}" >> "$LLM_OUTPUT"
|
||||
echo "" >> "$LLM_OUTPUT"
|
||||
|
||||
local output
|
||||
output=$(cd "${project_dir}" && eval "${argc_command}" 2>&1) || true
|
||||
echo "${output}" >> "$LLM_OUTPUT"
|
||||
}
|
||||
|
||||
# @cmd List directory contents
|
||||
# @option --path Path to list (default: project root)
|
||||
list_directory() {
|
||||
local dir_path="${argc_path:-.}"
|
||||
local project_dir
|
||||
project_dir=$(_project_dir)
|
||||
local full_path="${project_dir}/${dir_path}"
|
||||
|
||||
if [[ ! -d "${full_path}" ]]; then
|
||||
error "Directory not found: ${dir_path}" >> "$LLM_OUTPUT"
|
||||
return 1
|
||||
fi
|
||||
|
||||
{
|
||||
info "Contents of: ${dir_path}"
|
||||
echo ""
|
||||
ls -la "${full_path}"
|
||||
} >> "$LLM_OUTPUT"
|
||||
}
|
||||
Reference in New Issue
Block a user