Prometheus Strategic Planner
Relevant source files
The following files were used as context for generating this wiki page:
- src/agents/prometheus/AGENTS.md
- src/agents/prometheus/identity-constraints.ts
- src/agents/prometheus/interview-mode.ts
- src/agents/prometheus/plan-generation.ts
- src/agents/prometheus/plan-template.ts
- src/agents/prometheus/gemini.ts
- src/agents/prometheus/gpt.ts
- src/agents/prometheus/behavioral-summary.ts
- src/hooks/prometheus-md-only/constants.ts
Prometheus is the dedicated strategic planning agent within the OhMyOpenCode ecosystem. Its primary mission is to transform high-level user requests (e.g., "build X" or "fix Y") into comprehensive, "decision-complete" work plans. By design, Prometheus is a planner, not an implementer; it is strictly forbidden from writing source code or executing implementation tasks, focusing instead on gathering requirements, exploring the codebase, and resolving technical ambiguities before any work begins.
The agent operates through a structured multi-phase workflow involving heavy codebase exploration, user interviews, and consultation with advisory agents like Metis and Oracle. This ensures that the resulting plan, saved to .sisyphus/plans/*.md, provides an execution roadmap that leaves zero judgment calls for implementation agents like Sisyphus.
Sources: src/agents/prometheus/identity-constraints.ts:10-25, src/agents/prometheus/gemini.ts:25-30, src/agents/prometheus/AGENTS.md:7-12
Core Identity and Constraints
Prometheus is governed by a set of non-negotiable constraints that define its role as a "Strategic Planning Consultant."
The Planner Mandate
Prometheus interprets all imperative commands (e.g., "Implement feature X") as requests to create a work plan for that feature. It maintains a strict "Mutation Rule" set that permits reading and searching the codebase but forbids writing to any files outside the .sisyphus/ directory.
| Allowed Actions | Forbidden Actions |
|---|---|
| Reading/searching files and manifests | Writing code files (.ts, .js, .py, etc.) |
| Static analysis and repo exploration | Editing source code or running linters |
| Firing explore/librarian subagents | Executing tasks or "doing the work" |
Writing to .sisyphus/plans/ and .sisyphus/drafts/ | Creating non-markdown files |
Sources: src/agents/prometheus/identity-constraints.ts:16-55, src/agents/prometheus/gemini.ts:71-86, src/hooks/prometheus-md-only/constants.ts:9-13
Specialized Planning Principles
- Decision Complete: The plan must resolve every technical approach and ambiguity so that an executor makes no judgment calls.
- Explore Before Asking: Prometheus must ground itself in the actual codebase before asking the user questions.
- Single Plan Mandate: Regardless of project size, all work must be consolidated into one markdown file (even 50+ TODOs) to prevent context loss.
Sources: src/agents/prometheus/gemini.ts:50-65, src/agents/prometheus/identity-constraints.ts:135-155
Operational Workflow
Prometheus follows a strictly sequenced operational loop to ensure plan quality.
Phase 1: Grounding and Exploration
Before interacting with the user, Prometheus performs heavy exploration. This involves launching at least three parallel subagents to map codebase patterns, assess test infrastructure, and understand architectural boundaries.
The "Thinking Checkpoint" is mandatory, requiring the agent to verbalize discoveries and identify remaining unknowns before the interview phase.
Sources: src/agents/prometheus/gemini.ts:98-148, src/agents/prometheus/gpt.ts:114-148
Phase 2: Interview Mode
During the interview, Prometheus acts as a consultant. It uses a "Draft as Working Memory" protocol, continuously updating .sisyphus/drafts/{name}.md with requirements, technical decisions, and research findings.
- Clearance Check: After every turn, the agent evaluates if the core objective, scope boundaries, technical approach, and test strategy are confirmed.
- Auto-Transition: Once the checklist is all "YES", it moves to plan generation.
Sources: src/agents/prometheus/identity-constraints.ts:182-210, src/agents/prometheus/interview-mode.ts:10-40
Phase 3: Plan Generation
The generation process utilizes an Incremental Write Protocol to avoid output token limits. Prometheus first writes a skeleton, then uses Edit calls to append task batches.
Work Plan Structure
Generated plans are saved as YAML-infused Markdown files in .sisyphus/plans/. They are structured to optimize for parallel execution and automated verification.
Execution Strategy and Parallelism
Prometheus must maximize throughput by grouping tasks into "Waves."
- Wave 1: Foundations, scaffolding, and shared dependencies (e.g., types, schemas).
- Subsequent Waves: Core logic and UI modules that depend on earlier foundations.
- Target: 5-8 tasks per wave to ensure high concurrency.
Sources: src/agents/prometheus/plan-template.ts:75-120, src/agents/prometheus/identity-constraints.ts:125-133
Task (TODO) Specification
Every task in a Prometheus plan must include:
- Recommended Agent Profile: Category (e.g.,
visual-engineering,ultrabrain) and required skills. - Exhaustive References: Specific file paths and line numbers (e.g.,
src/auth.ts:45-78) illustrating patterns to follow. - QA Scenarios: Mandatory "Happy Path" and "Failure/Edge Case" scenarios with concrete tool steps (Playwright, Bash, etc.).
Sources: src/agents/prometheus/plan-template.ts:150-250, src/agents/prometheus/gpt.ts:340-385
Final Verification Wave
The end of every plan includes a "Final Verification Wave" consisting of four parallel review tasks:
- F1: Plan Compliance Audit (Oracle): Verifies all "Must Haves" were implemented.
- F2: Code Quality Review: Checks for linting, type errors, and "AI slop" patterns.
- F3: Real Manual QA: Re-executes every QA scenario from the plan.
- F4: Scope Fidelity Check: Ensures no scope creep or cross-task contamination occurred.
Sources: src/agents/prometheus/plan-template.ts:285-310, src/agents/prometheus/gpt.ts:387-400
Summary of Behavioral Constraints
| Constraint | Enforcement |
|---|---|
| Markdown-Only | Enforced by prometheus-md-only hook; non-.md writes are blocked. |
| Path Restriction | Limited to .sisyphus/plans/ and .sisyphus/drafts/. |
| Consultation | Mandatory Metis consultation before generating any plan. |
| Handoff | Must delete draft file and guide user to /start-work upon completion. |
Sources: src/hooks/prometheus-md-only/constants.ts:5-15, src/agents/prometheus/behavioral-summary.ts:10-35, src/agents/prometheus/identity-constraints.ts:105-123
Prometheus serves as the high-intelligence bridge between abstract user intent and concrete agent execution, ensuring that the development process is grounded in codebase reality and guarded against common AI failure modes like over-engineering or lack of test coverage.