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?