plan: add Phase 1 implementation plan for CodexHelper (milestones, deliverables, acceptance criteria)

collab/plan/01-codexhelper.llm.md

@@ -0,0 +1,48 @@
+# 01 — CodexHelper — Implementation Plan (LLM)
+
+- Scope: Phase 1 (Crawl) MVP for `CodexHelper` with subcommands, scaffolding, prompt composition, config precedence, and safety.
+
+- Milestones:
+  1) CLI skeleton + guardrails
+  2) Binary detection + pass-through flags
+  3) new-mode scaffolder (repo-only)
+  4) new-project scaffolder (outside repo)
+  5) run: compose prompts + invoke codex
+  6) Config precedence (YAML+yq)
+  7) Templates + copies (AGENTS.md, prompts/_mode)
+  8) Docs: README quickstart + wrapper usage
+
+- 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>/`.
+
+- 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
+
+- 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.
+
+- 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/`).
+
+- Next: Implement per milestones; add concise README quickstart.
+