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