# 01 — CodexHelper — Proposal (LLM)

- Tool: `CodexHelper` bash wrapper for codex-cli.
- CLI (subcommands):
  - new-project: scaffold project files
  - run: compose prompts + call codex
  - new-mode: scaffold mode (repo-only)
- Where to run: repo → only new-mode; elsewhere → new-project, run.
- Prompts order: global system → mode system overlay (optional) → mode rules → project narrative.
- Config: YAML + yq; precedence CLI > env > project > mode > global.
- Binary: detect `codex` then `codex-cli`; override `CODEX_BIN`.
- Safety: no overwrites without `--force`; never `git push` for user projects.
- Outputs: `<project>/runs/<ts>/...`.
- Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/{system.md,system.llm.md}`, `modes/<Name>/{mode.md,system.md?,defaults.yaml}`, `templates/project/<Name>/...`, `templates/project/_shared/AGENTS.md`, `meta/{AGENTS.seed.md,AGENTS.seed.llm.md}`.
- Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`, `.gitea/workflows/`, `docker/`, `scripts/`.
- Governance/Propagation: non-project-specific workflow changes get recorded in `prompts/global/` and seed AGENTS templates; proposal/plan updated so scaffolding includes them.
- TDD Governance: adopt test-driven development with full unit/integration tests for all features in this repo and generated projects; tests written first and required for acceptance.
- Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed.
- Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`.
- CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea + Docker orchestration; dependencies via Docker; explicit names/cleanup.
 - .gitignore Governance: maintain `.gitignore` with `runs/` and OS ignores across repos and generated projects.
 - Audits Governance: run audits regularly; prompt before releases; record under `docs/audits/`; enforce via CI step.
- Phase 1 acceptance:
  - new-mode creates mode skeleton
  - new-project scaffolds without overwrites
  - run composes and calls detected codex; writes under runs/
  - precedence respected; running in repo errors for run/new-project
  - new-project copies `templates/project/_shared/AGENTS.md` into project root as `AGENTS.md`
  - prompts/global present and used in prompt composition
  - governance rule: changes to global norms propagate to prompts/global and AGENTS templates; logged in DevLog
  - tests: unit/integration tests (bats) cover CLI flows and guardrails; TDD observed
  - zero debt: docs/tests included with every feature; no pending TODOs/deferrals; production-ready criteria met
  - planning: architecture/module map documented; module implementations follow approved plan with no unplanned refactors
  - clean root: root remains minimal; scaffolding organizes assets under subdirectories
  - ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
  - project CI: scaffold includes `.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, and `scripts/test.docker.sh`
  - audits: audit script present and run in CI; reports recorded in repo when performed
  - ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
\n+## Approval — Tick All That Apply

- Subcommands approved: `new-project`, `run`, `new-mode` [ ]
- Scope approved: repo→`new-mode` only; outside→`new-project`/`run` [ ]
- Prompts order approved: global→mode-system?→mode→project [ ]
- Config+precedence approved: YAML+yq; CLI>ENV>project>mode>global [ ]
- Safety approved: `--force` to overwrite; no `git push`; outputs to `<project>/runs/<ts>/...` [ ]
- Repo layout approved (modes, templates, global prompts) [ ]
- Project layout approved (prompts, `_mode/`, codex.yaml, codex.sh, .gitignore) [ ]
- Include empty `prompts/style.md` by default [ ]
- Binary discovery: `codex`→`codex-cli`; override `CODEX_BIN` [ ]
- Pass-through flags: `--mode --prompt-file --config --sandbox --full-auto` [ ]
- Block `run`/`new-project` inside repo with helpful error [ ]
- Phase 1 (Crawl) scope acceptable [ ]
- Add `docs/ROADMAP.md`; MCP deferred [ ]

Final: Reply in the human doc with “Approved for Plan” when all are checked.