ChatGPTScaffolding/collab/proposals/01-codexhelper.md

# 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, system.llm.md}` (global system rules; human + LLM)
- `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`)
- `templates/project/_shared/AGENTS.md` (AGENTS template copied into projects)
- `meta/{AGENTS.seed.md, AGENTS.seed.llm.md}` (seed AGENTS templates for bootstrap/reference)
- Governance/Propagation: maintain global norms in `prompts/global/` and seed AGENTS templates; reflect such changes in proposal/plan for scaffolding.
- TDD Governance: enforce test-driven development; require unit/integration tests for all features here and in generated projects.
- Zero Technical Debt: safety first; always production-ready; no deferring tests/docs/refactors; leverage sub-agents when needed.
- Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; keep a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated.
- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`.
- CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea and Docker only; dependencies via Docker; explicit names and cleanup.
 - .gitignore Governance: include and maintain `.gitignore` entries (e.g., `runs/`, OS files) across repos and generated projects.
 - Audits Governance: perform regular audits; prompt before releases; store reports under `docs/audits/` and enforce via CI step.

## Project Layout (generated)
- `AGENTS.md` (from `templates/project/_shared/AGENTS.md`)
- `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)
- `.gitea/workflows/` for CI; `docker/` for compose and Dockerfiles; `scripts/` for docker orchestration (tests, ci)

## 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).
  - Explicit: `prompts/global/` is present and used as the base of composition.
  - Governance/Propagation: non-project-specific rules are folded back into global/system and templates; changes logged.
  - TDD: tests are written first and required for acceptance.
  - Zero Debt: no pending TODOs/deferrals; docs updated alongside code; production-ready gate on each change.
  - Planning/Architecture: architecture/module map documented; implementations follow plan without unplanned refactors.

## 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.
- Project scaffold includes `AGENTS.md` copied from `templates/project/_shared/AGENTS.md`.
- `prompts/global/{system.md, system.llm.md}` exist and are included in composition.
- Governance/Propagation honored: when norms change, update `prompts/global/` and AGENTS templates; log in DevLog.
- TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass.
- Zero Debt honored: code, tests, and docs complete; no debt items remain.
- Clean Root honored: only essential files at root; scaffolding places assets under subdirectories.
- CI/Containers honored: CI runs in Gitea and locally using the same Docker Compose; containers and networks use explicit names and are cleaned up.
- Project scaffold includes `.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, and `scripts/test.docker.sh` copied from templates.
 - Audits honored: audit script present and executed in CI; reports are recorded when performed.

## 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.

## Approval Checklist
Please answer inline. When all are approved, reply “Approved for Plan”.

1) Subcommands: approve `new-project`, `run`, `new-mode`? Any renames?
2) Scope: inside this repo allow only `new-mode`; outside allow `new-project` and `run`?
3) Prompts order: global system → mode system overlay (optional) → mode rules → project narrative?
4) Config format/precedence: YAML with `yq`; CLI > env > project > mode > global?
5) Safety: require `--force` to overwrite; never `git push` for user projects; outputs under `<project>/runs/<timestamp>/...`?
6) Repo layout: `CodexHelper`, `prompts/global/system.md`, `modes/<Name>/{mode.md, system.md?, defaults.yaml}`, `templates/project/<Name>/...`?
7) Project layout: `prompts/{project.md, style.md?}`, `prompts/_mode/` (read-only copies), `codex.yaml`, `codex.sh`, `.gitignore (runs/)`?
8) Include empty `prompts/style.md` by default?
9) Binary discovery: try `codex` then `codex-cli`; allow override `CODEX_BIN`?
10) Pass-through flags: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto` to underlying `codex`?
11) Block `run` and `new-project` inside this repo with a helpful error?
12) Phase 1 (Crawl) scope acceptable as listed?
13) Roadmap: add `docs/ROADMAP.md`; defer MCP integration for now?