docs(proposal): add 01-codexhelper proposal based on approved questions

collab/proposals/01-codexhelper.md

@@ -0,0 +1,97 @@
+# 01 — CodexHelper — Proposal
+
+Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes”, project scaffolding, and a clean CLI.
+
+## Summary of Agreed Direction
+- Name/Install: `CodexHelper` script in this repo; users add it to PATH. Optional `bin/install.sh` to symlink into `~/bin`.
+- CLI Style: Subcommands — `new-project`, `new-mode`, `run`.
+- Where to run: Outside this repo → `new-project`, `run`. Inside this repo → only `new-mode`.
+- Modes/Prompts: Global system (repo-wide) → optional mode system overlay → mode rules → project narrative.
+- Config: YAML with `yq`. Precedence: CLI > env > project > mode > global defaults.
+- Binary discovery: `which codex`, then `which codex-cli`; override with `CODEX_BIN`. No auto-install.
+- Safety/Outputs: Never overwrite without `--force`; never `git push` in user projects; write runs to `<project>/runs/<timestamp>/...`.
+- Licensing: Repo (wrapper, modes, prompts) AGPLv3; user artifacts are user-licensed.
+- OS/Deps: Ubuntu/Debian, bash/zsh; deps: bash, git, yq.
+
+## CLI
+- `CodexHelper new-project --mode <ModeName> --name <project-name> --path <dir> [--force] [--sandbox <mode>] [--full-auto] [--config <file>]`
+  - Creates project structure in `<dir>/<project-name>` (or `<dir>` if it exists):
+    - `prompts/project.md` (narrative template), optional `prompts/style.md`
+    - `prompts/_mode/` with copies of global/mode prompts
+    - `codex.yaml` (mode + settings + MCP placeholders)
+    - `codex.sh` (entrypoint wrapper that resolves config and calls `codex`)
+    - `.gitignore` (includes `runs/`)
+- `CodexHelper run [--mode <ModeName>] [--prompt-file <file>] [--config <file>] [--sandbox <mode>] [--full-auto] [--force]`
+  - Must be run inside a project dir; composes prompts in correct order; writes logs to `runs/<timestamp>/...`.
+  - Respects precedence: CLI > env > project > mode > global.
+- `CodexHelper new-mode --name <ModeName>` (only in this repo root)
+  - Scaffolds `modes/<ModeName>/mode.md` and optional `modes/<ModeName>/system.md`, plus `modes/<ModeName>/defaults.yaml`.
+  - Uses a markdown intake template for quick editing.
+
+## Repository Layout (this repo)
+- `CodexHelper` (bash)
+- `bin/install.sh` (optional symlink helper)
+- `prompts/global/system.md` (global system rules)
+- `modes/<ModeName>/mode.md` (mode rules)
+- `modes/<ModeName>/system.md` (optional mode-specific system overlay)
+- `modes/<ModeName>/defaults.yaml` (default codex settings, optional MCP placeholders)
+- `templates/project/<ModeName>/...` (project scaffolding templates copied on `new-project`)
+
+## Project Layout (generated)
+- `prompts/project.md` (+ optional `prompts/style.md`)
+- `prompts/_mode/` (read-only copies from this repo)
+- `codex.yaml` (project config)
+- `codex.sh` (entrypoint wrapper around codex-cli)
+- `runs/` (created on first run; ignored by VCS)
+
+## Config Details
+- Format: YAML (`yq` for merging/reading)
+- Precedence resolution: merge defaults in order — global defaults → mode defaults → project config → env vars → CLI flags.
+- Key fields in `codex.yaml`:
+  - `mode: <ModeName>`
+  - `codex:` `{ model, token_budget, reasoning_level, sandbox, full_auto, extra_args[] }`
+  - `prompts:` `{ project: prompts/project.md, mode_dir: prompts/_mode }`
+  - `mcp:` placeholders (deferred per roadmap)
+
+## Prompt Composition
+- Order: Global system → Mode system overlay (if any) → Mode rules → Project narrative.
+- Implementation: `codex.sh` concatenates/feeds prompts to `codex` in that order (exact mechanism depends on codex-cli interface; we’ll use files/flags as supported).
+
+## Safety
+- Guardrails:
+  - Refuse `run` and `new-project` inside this repo; allow only `new-mode` here.
+  - Refuse to overwrite files unless `--force`.
+  - Never execute `git push` in user projects.
+
+## Crawl → Walk → Run
+- Crawl (Phase 1 — initial MVP):
+  - `CodexHelper` with subcommands implemented.
+  - Global system location and one example mode scaffolder.
+  - Project scaffold: prompts, codex.yaml, codex.sh, .gitignore (runs/).
+  - Config precedence implemented; sandbox/full-auto pass-through.
+  - Binary detection and friendly error messages.
+  - Minimal docs: README quickstart; `docs/wrapper.md` for usage.
+- Walk (Phase 2):
+  - `--interactive` prompts for missing values.
+  - Mode defaults (`defaults.yaml`) respected and merged.
+  - Basic tests for key flows; improved logging in `runs/`.
+  - Add `docs/ROADMAP.md` entries and initial MCP placeholders.
+- Run (Phase 3):
+  - Mode/project wizards via markdown intake with validation.
+  - MCP integration options.
+  - Additional quality-of-life flags and templates.
+
+## Acceptance Criteria (Phase 1)
+- Running `CodexHelper new-mode --name Demo` inside this repo creates `modes/Demo/{mode.md,defaults.yaml}`.
+- Running `CodexHelper new-project --mode Demo --name demo --path /tmp` creates a project with files listed above, without overwrites unless `--force`.
+- Inside that project, `CodexHelper run --full-auto` composes prompts and calls the detected `codex` binary. It writes artifacts under `runs/<timestamp>/...`.
+- Precedence works: CLI options override env, which override project config, which override mode defaults.
+- Running `CodexHelper run` in this repo prints an error guiding usage.
+
+## Open Items for Confirmation
+- Template coverage: include `prompts/style.md` by default? (we’ll include as optional, empty file)
+- Exact prompt-passing flags to `codex-cli` (confirm once coding — will use pass-through and files as supported).
+
+## Next Step
+- On approval, I will create a concrete implementation plan at `collab/plan/01-codexhelper.md` and proceed with the Crawl phase implementation.
+