# 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.