35 lines
1.6 KiB
Markdown
35 lines
1.6 KiB
Markdown
# CodexHelper — Architecture (Phase 1)
|
|
|
|
Overview
|
|
- Goal: Bash wrapper around `codex`/`codex-cli` with modes, project scaffolding, prompt composition, config precedence, and safety.
|
|
- Constraints: TDD, zero technical debt, plan-first, clean root, CI via Gitea with local Docker parity.
|
|
|
|
Modules
|
|
- CLI Entrypoint (`CodexHelper`)
|
|
- Subcommands: `new-mode` (repo-only), `new-project` (outside repo), `run` (outside repo)
|
|
- Guardrails: detect helper repo by structure; block disallowed subcommands
|
|
- Binary Detection: `CODEX_BIN` > `codex` > `codex-cli`
|
|
- Flag Pass-through: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto`, `--`
|
|
|
|
- Scaffolding
|
|
- Modes: `modes/<Name>/{mode.md, defaults.yaml, system.md?}` with intake hints
|
|
- Projects: `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/` (copies of global/mode prompts), `codex.yaml`, `codex.sh`, `.gitignore`, CI/containers templates
|
|
|
|
- Run Engine
|
|
- Validate project layout
|
|
- Compose prompts (global system → mode system? → mode rules → project narrative)
|
|
- Invoke `$CODEX_BIN` with pass-through flags; write artifacts under `runs/<ts>/`
|
|
|
|
- Config
|
|
- YAML via `yq`: global defaults < mode defaults < project config < ENV < CLI
|
|
|
|
Cross-cutting
|
|
- Tests: `tests/` via bats or fallback; Docker Compose runner for local parity; Gitea Actions for CI
|
|
- Docs: `README.md`, `docs/wrapper.md`, `docs/architecture.md`, DevLogs
|
|
- Governance: propagation updates applied to prompts/global and AGENTS templates
|
|
|
|
Assumptions
|
|
- `yq` available in containers; host only orchestrates Docker and git/tea.
|
|
- codex auth may require host mounts; handled via project `codex.sh` composition.
|
|
|