From 2da83b83882aaadddab69db5c876397e64b4e5bc Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 09:52:39 -0500 Subject: [PATCH] docs(proposal): add 01-codexhelper proposal based on approved questions --- collab/proposals/01-codexhelper.md | 97 ++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 collab/proposals/01-codexhelper.md diff --git a/collab/proposals/01-codexhelper.md b/collab/proposals/01-codexhelper.md new file mode 100644 index 0000000..87e63c2 --- /dev/null +++ b/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 `/runs//...`. +- 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 --name --path [--force] [--sandbox ] [--full-auto] [--config ]` + - Creates project structure in `/` (or `` 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 ] [--prompt-file ] [--config ] [--sandbox ] [--full-auto] [--force]` + - Must be run inside a project dir; composes prompts in correct order; writes logs to `runs//...`. + - Respects precedence: CLI > env > project > mode > global. +- `CodexHelper new-mode --name ` (only in this repo root) + - Scaffolds `modes//mode.md` and optional `modes//system.md`, plus `modes//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//mode.md` (mode rules) +- `modes//system.md` (optional mode-specific system overlay) +- `modes//defaults.yaml` (default codex settings, optional MCP placeholders) +- `templates/project//...` (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: ` + - `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//...`. +- 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. +