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

collab/plan/01-codexhelper.md

@@ -0,0 +1,65 @@
+# 01 — CodexHelper — Implementation Plan
+
+Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, prompt composition, config precedence, and safety.
+
+## Milestones & Tasks
+1) CLI skeleton + guardrails
+- Add `CodexHelper` bash script with `new-project`, `run`, `new-mode` subcommands and `--help`.
+- Enforce location rules: inside this repo → only `new-mode` allowed; outside → `new-project`, `run`.
+
+2) Binary detection + pass-through
+- Implement `detect_codex`: `CODEX_BIN` env > `which codex` > `which codex-cli`; fail with helpful message if none.
+- Support pass-through flags: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto`, plus `--` to forward extras.
+
+3) new-mode (repo-only)
+- Create `modes/<Name>/{mode.md,defaults.yaml,system.md?}` with intake comments.
+- Refuse to overwrite unless `--force`.
+
+4) new-project (outside repo)
+- Create `<path>/<name>` (or use `<path>` if existing and empty/`--force`).
+- Copy templates:
+  - `templates/project/_shared/AGENTS.md` → `<project>/AGENTS.md`
+  - Create `prompts/project.md` (narrative template) and empty `prompts/style.md` (optional)
+  - Create `prompts/_mode/` and copy read-only references of `prompts/global/system.md` and selected mode prompts
+  - Generate `codex.yaml` with mode + codex settings (placeholders)
+  - Generate `codex.sh` entrypoint to compose prompts and call codex
+  - Add `.gitignore` (includes `runs/`)
+
+5) run: compose + invoke
+- Validate project structure; ensure `prompts/_mode/` exists.
+- Compose prompts in order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Create `runs/<timestamp>/` and save composed prompt and invocation metadata.
+- Invoke `$CODEX_BIN` with pass-through flags; handle `--sandbox` and `--full-auto`.
+
+6) Config precedence (YAML + yq)
+- Load `codex.yaml`; merge with mode defaults and global defaults.
+- Apply ENV overrides; apply CLI overrides last.
+
+7) Docs
+- Add `docs/wrapper.md` with usage examples and config reference.
+- Update `README.md` quickstart: installation, basic flows.
+
+## Safety & Policies
+- Never overwrite without `--force`.
+- Never `git push` for user projects.
+- Write outputs to `<project>/runs/<timestamp>/...`.
+- Minimal chat; read `.llm.md`, write both `.md` and `.llm.md` for collab artifacts.
+- Governance/Propagation: reflect future non-project-specific norms into `prompts/global/` and AGENTS templates; log in DevLog.
+
+## Acceptance Criteria
+- Inside this repo: `CodexHelper new-mode --name Demo` creates `modes/Demo/{mode.md,defaults.yaml}` (and optional `system.md`) and refuses overwrites without `--force`.
+- Outside this repo: `CodexHelper new-project --mode Demo --name demo --path /tmp` creates project with `AGENTS.md`, `prompts/{project.md,style.md}`, `prompts/_mode/` (copies of global+mode), `codex.yaml`, `codex.sh`, `.gitignore` (with `runs/`).
+- Inside the new project: `CodexHelper run --full-auto` composes prompts and calls detected binary; artifacts under `runs/<timestamp>/...`.
+- Precedence: CLI > env > project > mode > global.
+- `prompts/global/{system.md,system.llm.md}` are present and included in composition.
+- Running `CodexHelper run` or `new-project` inside this repo errors with guidance.
+
+## Assumptions/Risks
+- codex-cli flags may vary; we’ll design pass-through and document tested flags.
+- `yq` is available; if missing, we provide a helpful error.
+
+## Timeline (targeted)
+- Day 1: Milestones 1–3
+- Day 2: Milestones 4–5
+- Day 3: Milestone 6 + Docs
+