# 01 — CodexHelper — Implementation Plan (LLM)

- Scope: Phase 1 (Crawl) MVP for `CodexHelper` with subcommands, scaffolding, prompt composition, config precedence, and safety.

- Milestones (TDD for each step):
  0) Test harness setup (bats-core), tests/ structure, CI script (local)
  1) CLI skeleton + guardrails (write failing tests first)
  2) Binary detection + pass-through flags (tests first)
  3) new-mode scaffolder (repo-only) (tests first)
  4) new-project scaffolder (outside repo) (tests first)
  5) run: compose prompts + invoke codex (tests first)
  6) Config precedence (YAML+yq) (tests first)
  7) Templates + copies (AGENTS.md, prompts/_mode) (tests first)
  8) Docs: README quickstart + wrapper usage (ensure examples validated by tests where feasible)

- Key rules honored:
  - One-way workflow; minimal chat; read `.llm.md`, write both.
  - Governance/propagation: update prompts/global and seed/project AGENTS when norms change.
  - Safety: `--force` for overwrite; never `git push`; runs under `<project>/runs/<ts>/`.
  - Zero Technical Debt: production-ready always; no deferring docs/tests/refactors.
  - Planning/Architecture: plan ahead; maintain architecture/module map; implement module-by-module; avoid refactors unless plans/docs updated due to new info.

- Deliverables:
  - `CodexHelper` bash script
  - `prompts/global/{system.md,system.llm.md}` (already present)
  - `templates/project/_shared/AGENTS.md` (copy into project root)
  - `templates/project/<ModeName>/...` (optional mode-specific add-ons; start minimal)
  - `docs/wrapper.md` and README updates
  - Test harness (`bats`), `tests/` with coverage of all CLI paths
  - `docs/architecture.md` and ADRs for key decisions

- Implementation details:
  - Guard where running: inside repo → only `new-mode` allowed.
  - Detect codex: `CODEX_BIN` env > `which codex` > `which codex-cli`.
  - new-mode: create `modes/<Name>/{mode.md,defaults.yaml,system.md?}` with intake hints.
  - new-project: create dir, copy `AGENTS.md`, `prompts/project.md`, `prompts/style.md?`, `prompts/_mode/` with read-only copies of global+mode prompts, `codex.yaml`, `codex.sh`, `.gitignore` (includes `runs/`).
  - run: ensure project layout; compose prompts in order: global system → mode system? → mode rules → project narrative; call `$CODEX_BIN` with pass-through flags; write logs/artifacts to `runs/<ts>/`.
  - Config precedence: load YAML via yq; allow CLI/env override of codex settings and mode.

- Acceptance checks:
  - Running in repo: `new-mode` works; `run`/`new-project` error with guidance.
  - `new-project` scaffolds without overwrites; includes `AGENTS.md`; sets up `prompts/_mode/`.
  - `run` composes prompts and calls detected binary; artifacts under `runs/<ts>/`.
  - Precedence: CLI > env > project > mode > global.
  - `prompts/global/` used in composition.
  - Tests: all features covered by unit/integration tests (bats); TDD observed (tests committed alongside implementation); CI/local test script present.
  - Zero Debt: docs updated; no pending TODOs/deferrals; production-ready criteria met.
  - Planning/Architecture: architecture/module map exists and matches implemented modules; no unplanned refactors.

- Open choices (defaulting now):
  - Include empty `prompts/style.md`: Yes.
  - Config format: YAML only; tool: yq.
  - Project `.gitignore`: include `runs/` and any `*.llm.*` if user prefers later (for now, only `runs/`).
  - Test framework: bats-core for bash; simple runner `scripts/test.sh`.

- Next: Implement per milestones; add concise README quickstart.
 
- Accelerated Timeline (8 hours today):
   - H0–1: test harness + failing smoke tests (CLI, guardrails)
   - H1–2: CLI skeleton + guardrails (make tests pass)
   - H2–3: binary detection + pass-through (tests first)
   - H3–4: new-mode scaffolder (tests first)
   - H4–6: new-project scaffolder (tests first)
   - H6–7: run: compose + invoke (tests first)
  - H7–8: config precedence (tests first) + minimal docs
 
 - No deferral: docs must be completed; templates polished sufficiently for production.