t1357.3: Create mission orchestrator agent doc#2511
t1357.3: Create mission orchestrator agent doc#2511alex-solovyev wants to merge 1 commit intomainfrom
Conversation
…ject execution Create workflows/mission-orchestrator.md with guidance for driving missions from scoped milestones to verified completion. Covers: execution loop (sequential milestones, parallel features), self-organisation (file/folder management, temporary draft agent creation), improvement feedback to aidevops, reference patterns for existing capabilities, research guidance for unknown domains, POC vs full mode specifics, failure recovery, budget tracking, and pulse integration. Closes #2497
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces the concept and detailed documentation for a "Mission Orchestrator" agent, designed to autonomously manage and execute complex, multi-day projects from defined milestones to completion. The orchestrator provides guidance on execution loops, self-organization, failure recovery, and integration with existing systems, aiming to enhance the framework's ability to handle strategic, long-running tasks. The changes also ensure this new workflow is properly indexed and discoverable within the agent documentation structure. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
WalkthroughThis pull request introduces the Mission Orchestrator documentation and updates the agent index files. It adds a comprehensive mission-orchestrator.md guide to the workflows directory and updates AGENTS.md and subagent-index.toon to reference the new workflow, with the TOON header index bumped from 13 to 14. Changes
Possibly Related PRs
Poem
🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Fri Feb 27 23:31:22 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive and well-structured agent document for a mission orchestrator, outlining a complex, long-running process. However, the document contains several security vulnerabilities, specifically Command Injection and Path Traversal, due to the direct incorporation of unsanitized variables from untrusted sources into shell command templates and file operations. For command injection, it is critical to use bash arrays for safe dynamic command construction. This could lead to Remote Code Execution (RCE) or arbitrary file access. Additionally, there are significant contradictions within the described execution model that need to be resolved to improve clarity and implementability.
| opencode run --dir <repo_path> --title "Mission {id} / {feature_id}: {title}" \ | ||
| "/full-loop Implement {feature_description} -- Context: part of mission {id}, milestone {N}" & |
There was a problem hiding this comment.
The opencode run command templates, specifically at lines 99-100, use variables like {title} and {feature_description} directly from the mission state file. This poses a significant Command Injection vulnerability, as shell metacharacters in these variables could lead to arbitrary command execution. To avoid command injection vulnerabilities when constructing shell commands dynamically, it is crucial to use a bash array to build the command and its arguments safely, rather than direct variable interpolation. Additionally, update these instructions to explicitly require sanitization or proper escaping of all variables before using them in shell commands.
Beyond this security concern, there's a major contradiction in the agent's execution model. The "Execution Loop" (lines 93-127) describes direct worker dispatch using opencode run and ps, which conflicts with the "Integration with Pulse" model (lines 428-444) where pulse dispatches workers based on GitHub issues. The "Execution Loop" section should be rewritten to align with the Pulse integration model. Additionally, please clarify the internal contradiction within the "Integration with Pulse" section regarding whether issues are created for all features or only for the next milestone's features.
| opencode run --dir <repo_path> --title "Mission {id} / {feature_id}: {title}" \ | |
| "/full-loop Implement {feature_description} -- Context: part of mission {id}, milestone {N}" & | |
| # Full mode — standard worktree + PR workflow (sanitize all variables to prevent shell injection) | |
| opencode run --dir <repo_path> --title "Mission {id} / {feature_id}: {title}" \ | |
| "/full-loop Implement {feature_description} -- Context: part of mission {id}, milestone {N}" & |
References
- To avoid command injection vulnerabilities when constructing shell commands dynamically, do not use
eval. Instead, use a bash array to build the command and its arguments safely.
|
|
||
| ```bash | ||
| # Find and read the mission file | ||
| cat todo/missions/{mission_id}-mission.md |
There was a problem hiding this comment.
The instructions for the Mission Orchestrator agent provide several shell command templates that directly incorporate variables derived from untrusted sources (such as the mission state file or user-supplied mission IDs) without any requirement for sanitization or validation.
Specifically, this cat command is vulnerable to path traversal if {mission_id} contains ../. Since the agent has bash tool access, an attacker who can influence the mission ID could read arbitrary files on the system.
Remediation: Instruct the agent to validate and sanitize the {mission_id} variable (e.g., ensuring it only contains alphanumeric characters and hyphens) before using it in a shell command.
| cat todo/missions/{mission_id}-mission.md | |
| # Find and read the mission file (ensure {mission_id} is sanitized: alphanumeric + hyphens only) | |
| cat todo/missions/{mission_id}-mission.md |
| mkdir -p ~/.aidevops/agents/draft/{mission_id}/ | ||
|
|
||
| cat > ~/.aidevops/agents/draft/{mission_id}/{name}.md << 'AGENT' |
There was a problem hiding this comment.
The instructions for temporary agent creation use {mission_id} and {name} to construct file paths for mkdir and cat. If these variables contain path traversal sequences (e.g., ../), the LLM could be tricked into writing files outside the intended directory (~/.aidevops/agents/draft/), potentially overwriting sensitive system files or configuration.
Remediation: Instruct the agent to strictly validate {mission_id} and {name} to ensure they do not contain path traversal characters and consist only of safe characters.
| mkdir -p ~/.aidevops/agents/draft/{mission_id}/ | |
| cat > ~/.aidevops/agents/draft/{mission_id}/{name}.md << 'AGENT' | |
| # Sanitize {mission_id} and {name} to prevent path traversal | |
| mkdir -p ~/.aidevops/agents/draft/{mission_id}/ | |
| cat > ~/.aidevops/agents/draft/{mission_id}/{name}.md << 'AGENT' |
| opencode run --dir <repo_path> --agent Research --title "Mission {id}: Research {topic}" \ | ||
| "Research {topic} for mission {id}. Deliverable: a summary document at \ | ||
| todo/missions/{id}/research/{topic}.md covering: key concepts, recommended \ |
There was a problem hiding this comment.
The research command template uses the {topic} variable in both the command title and the prompt. Similar to other command templates, this is vulnerable to shell injection if the topic string contains malicious shell metacharacters. To avoid command injection vulnerabilities when constructing shell commands dynamically, it is crucial to use a bash array to build the command and its arguments safely, rather than direct variable interpolation. Additionally, instruct the agent to sanitize the {topic} variable before incorporating it into the shell command.
| opencode run --dir <repo_path> --agent Research --title "Mission {id}: Research {topic}" \ | |
| "Research {topic} for mission {id}. Deliverable: a summary document at \ | |
| todo/missions/{id}/research/{topic}.md covering: key concepts, recommended \ | |
| # Sanitize {topic} and {id} to prevent injection and traversal | |
| opencode run --dir <repo_path> --agent Research --title "Mission {id}: Research {topic}" \ | |
| "Research {topic} for mission {id}. Deliverable: a summary document at \ | |
| todo/missions/{id}/research/{topic}.md covering: key concepts, recommended \ |
References
- To avoid command injection vulnerabilities when constructing shell commands dynamically, do not use
eval. Instead, use a bash array to build the command and its arguments safely.
| | Aspect | Full Mode | POC Mode | | ||
| |--------|-----------|----------| | ||
| | Git workflow | Worktree + PR per feature | Single branch or direct to main | | ||
| | Task briefs | Required per feature | Skipped | | ||
| | Code review | PR review before merge | Self-merge, no review | | ||
| | Quality gates | Preflight + postflight | Basic: does it run? | | ||
| | Parallel workers | Up to `max_parallel_workers` | Single worker per milestone | | ||
| | Validation | Full criteria | "Does the demo work?" | | ||
| | Documentation | Required | Minimal — README only | |
There was a problem hiding this comment.
There is a contradiction regarding parallelism in POC mode.
The table in "POC Mode Specifics" (line 372) states that for "Parallel workers", POC mode uses a "Single worker per milestone".
However, the example in "Step 3: Dispatch Features" (lines 103-107) is inside a loop For each feature..., which implies that multiple features in a milestone could be dispatched in parallel, even in POC mode. The dispatch rules on line 111 also state to "Respect max_parallel_workers from mission config", which seems to apply to both modes.
Please clarify the intended behavior for parallelism in POC mode to resolve this contradiction. For example, should the table on line 372 be updated to something like "Reduced parallelism (e.g., 1)" or should the dispatch logic explicitly handle this?
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.agents/workflows/mission-orchestrator.md (1)
317-329: Search commands reference~/.aidevops/agents/— these should work for installed framework but not in-repo development.The
rgcommands assume the framework is installed at~/.aidevops/. For consistency with other docs, consider noting this is the installed path, or use relative paths when working within the repo.💡 Consider adding a note about path context
### Using Existing aidevops Capabilities Before building something new, check if aidevops already has it: +> **Note:** Paths below assume the installed framework at `~/.aidevops/`. When working within the aidevops repo itself, use relative paths (e.g., `.agents/subagent-index.toon`). + ```bash # Search the subagent index for relevant capabilities rg "{keyword}" ~/.aidevops/agents/subagent-index.toon🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/workflows/mission-orchestrator.md around lines 317 - 329, Update the commands that reference the installed framework to clarify context: note that the rg/search lines target the installed subagent index (subagent-index.toon) under the framework install and therefore use the installed path, and add equivalent relative repo examples for in-repo development (e.g., repo-relative glob patterns) plus a short note about the aidevops skills search and the grep mcp_servers check so readers know when to use installed vs repo paths; update the snippets around the rg and "aidevops skills search" commands and add a one-line explanation indicating which commands expect the framework to be installed versus run from the repo.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.agents/workflows/mission-orchestrator.md:
- Around line 317-329: Update the commands that reference the installed
framework to clarify context: note that the rg/search lines target the installed
subagent index (subagent-index.toon) under the framework install and therefore
use the installed path, and add equivalent relative repo examples for in-repo
development (e.g., repo-relative glob patterns) plus a short note about the
aidevops skills search and the grep mcp_servers check so readers know when to
use installed vs repo paths; update the snippets around the rg and "aidevops
skills search" commands and add a one-line explanation indicating which commands
expect the framework to be installed versus run from the repo.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.agents/AGENTS.md.agents/subagent-index.toon.agents/workflows/mission-orchestrator.md
1 participant
Summary
workflows/mission-orchestrator.md— the agent doc that guides autonomous multi-day mission execution from milestones to completionWhat the orchestrator covers
todo/missions/{id}/), temporary agent creation (draft tier), promotion workflowDesign decisions
workflows/(consistent withralph-loop.md,plans.md— process guides)Closes #2497
Summary by CodeRabbit
New Features
Documentation