mirror of
https://github.com/openai/codex.git
synced 2026-11-10 21:00:47 +00:00
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# Codex Orchestration Framework: Plan & Open Questions
|
||
|
||
This document collects the high‑level architecture, planned features, and unresolved design decisions for the proposed **codex-agents** orchestration framework.
|
||
|
||
## 1. Architecture & Core Components
|
||
|
||
- **XDG‑compliant configuration & state**
|
||
- Repo‑local overrides: `<repo>/.codex-agent/config.toml`
|
||
- User‑wide config: `$XDG_CONFIG_HOME/codex-agents/config.toml`
|
||
- Global task registry: `$XDG_DATA_HOME/codex-agents/tasks.json`
|
||
|
||
- **CLI & optional TUI**
|
||
- `codex-agent init` → bootstrap repo (copy prompts, create directories)
|
||
- `codex-agent status [--tui]` → show global and per‑repo task/merge status
|
||
- `codex-agent config` → inspect or edit effective config
|
||
- `codex-agent agents` → view per‑agent instruction overrides
|
||
|
||
- **Task management (`codex-agent task`)**
|
||
- `add`, `list`, `edit`, `worktree add|remove`, `validate`, `review`, `complete`
|
||
- Interactive AI Q&A flow for `task add` to auto‑populate slug, goal, dependencies, and stub file
|
||
|
||
- **Worktree hydration**
|
||
- OS‑aware reflink: macOS `cp -cRp`, Linux `cp --reflink=auto`, fallback to `rsync`
|
||
- COW setup via `git worktree add --no-checkout` + hydration step
|
||
|
||
- **Merge & Conflict Resolver (`codex-agent merge`)**
|
||
- `merge check` → dry‑run merge in temp worktree
|
||
- `merge resolve` → AI‑driven conflict resolution or explicit bail-out
|
||
- `merge rebase` → manual rebase entrypoint
|
||
|
||
- **Code Validator (`codex-agent task validate|review`)**
|
||
- Run linters/tests, then invoke Validator agent prompt
|
||
- Enforce configurable policies (doc coverage, style rules, test thresholds)
|
||
|
||
- **Project Manager (`codex-agent manager`)**
|
||
- Wave planning, parallel launch commands, live monitoring of worktrees
|
||
|
||
## 2. Phased Roadmap
|
||
|
||
Phase | Deliverables
|
||
:----:|:--------------------------------------------------------------------------------------
|
||
1 | XDG config + global `tasks.json` + basic `task list|add|worktree` CLI
|
||
2 | Merge check & conflict-resolver prompt + `merge check|resolve` commands
|
||
3 | Validator agent integration + `task validate|review`
|
||
4 | Project Manager planning & launching (`manager plan|launch|monitor`)
|
||
5 | Interactive `task add` QA loop + per-agent instruction overrides
|
||
6 | TUI mode for `status` + live dashboard
|
||
7 | Polishing docs, tests, packaging, and PyPI release
|
||
|
||
## 3. Open Questions & Design Decisions
|
||
|
||
1. **Global registry schema**
|
||
- What additional fields should `tasks.json` track? (e.g. priority, owner, labels)
|
||
|
||
2. **Config file format & schema**
|
||
- TOML vs YAML vs JSON for `config.toml`?
|
||
- Which policy keys to expose for Validator and Resolver agents?
|
||
|
||
3. **Per‑agent instruction overrides**
|
||
- How to structure override files (`validator.toml`, `conflict-resolver.toml`, etc.)?
|
||
- Should we fallback to AGENTS‑style instruction files in the repo root if present?
|
||
|
||
4. **CLI command names & flags**
|
||
- Confirm subcommand verbs (`merge resolve` vs `task rebase`, `task validate` vs `task lint`)
|
||
- Standardize flags for interactive vs non‑interactive modes
|
||
|
||
5. **Conflict Resolver scope**
|
||
- Auto‑resolve only trivial hunks, or attempt full rebase‑based AI resolution?
|
||
- How and when can the agent “give up” and hand control back to the user?
|
||
|
||
6. **Validator policies & auto‑fix**
|
||
- Default policy values (max line length, doc coverage %)
|
||
- Should `--auto-fix` let the agent rewrite code, or only report issues?
|
||
|
||
7. **Interactive Task Creation**
|
||
- Best UX for prompting the user: CLI Q&A loop vs opening an editor with agent instructions?
|
||
- How to capture dependencies and inject them into the new task stub?
|
||
|
||
8. **Session restore UX**
|
||
- Always on for `codex session <UUID>`, or opt‑in via flag?
|
||
- How to surface restore failures or drift in transcript format?
|
||
|
||
9. **TUI implementation**
|
||
- Framework choice (curses, Rich, Textual)
|
||
- Auto‑refresh interval and keybindings for actions (open worktree, resolve, validate)
|
||
|
||
10. **Packaging & distribution**
|
||
- Final PyPI package name (`codex-agents` vs `ai-orchestrator`)
|
||
- Versioning strategy and backwards‑compatibility guarantees
|
||
|
||
---
|
||
|
||
_This plan will evolve as we answer these questions and move through the roadmap phases._
|