ChatGPTScaffolding/collab/proposals/01-codexhelper.llm.md

01 — CodexHelper — Proposal (LLM)

• Tool: CodexHelper bash wrapper for codex-cli.

• CLI (subcommands):

  • new-project: scaffold project files
  • run: compose prompts + call codex
  • new-mode: scaffold mode (repo-only)

• Where to run: repo → only new-mode; elsewhere → new-project, run.

• Prompts order: global system → mode system overlay (optional) → mode rules → project narrative.

• Config: YAML + yq; precedence CLI > env > project > mode > global.

• Binary: detect codex then codex-cli; override CODEX_BIN.

• Safety: no overwrites without --force; never git push for user projects.

• Outputs: <project>/runs/<ts>/....

• Layout (repo): CodexHelper, bin/install.sh, prompts/global/{system.md,system.llm.md}, modes/<Name>/{mode.md,system.md?,defaults.yaml}, templates/project/<Name>/..., templates/project/_shared/AGENTS.md, meta/{AGENTS.seed.md,AGENTS.seed.llm.md}.

• Layout (project): AGENTS.md, prompts/{project.md,style.md?}, prompts/_mode/, codex.yaml, codex.sh, runs/, .gitea/workflows/, docker/, scripts/.

• Governance/Propagation: non-project-specific workflow changes get recorded in prompts/global/ and seed AGENTS templates; proposal/plan updated so scaffolding includes them.

• TDD Governance: adopt test-driven development with full unit/integration tests for all features in this repo and generated projects; tests written first and required for acceptance.

• Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed.

• Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain 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 + Docker orchestration; dependencies via Docker; explicit names/cleanup.

• .gitignore Governance: maintain .gitignore with runs/ and OS ignores across repos and generated projects.

• Audits Governance: run audits regularly; prompt before releases; record under docs/audits/; enforce via CI step.

• Phase 1 acceptance:

  • new-mode creates mode skeleton
  • new-project scaffolds without overwrites
  • run composes and calls detected codex; writes under runs/
  • precedence respected; running in repo errors for run/new-project
  • new-project copies templates/project/_shared/AGENTS.md into project root as AGENTS.md
  • prompts/global present and used in prompt composition
  • governance rule: changes to global norms propagate to prompts/global and AGENTS templates; logged in DevLog
  • tests: unit/integration tests (bats) cover CLI flows and guardrails; TDD observed
  • zero debt: docs/tests included with every feature; no pending TODOs/deferrals; production-ready criteria met
  • planning: architecture/module map documented; module implementations follow approved plan with no unplanned refactors
  • clean root: root remains minimal; scaffolding organizes assets under subdirectories
  • ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
  • project CI: scaffold includes .gitea/workflows/ci.yml, docker/compose.yml, docker/test/Dockerfile, and scripts/test.docker.sh
  • audits: audit script present and run in CI; reports recorded in repo when performed
  • ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified \n+## Approval — Tick All That Apply

• Subcommands approved: new-project, run, new-mode [ ]

• Scope approved: repo→new-mode only; outside→new-project/run [ ]

• Prompts order approved: global→mode-system?→mode→project [ ]

• Config+precedence approved: YAML+yq; CLI>ENV>project>mode>global [ ]

• Safety approved: --force to overwrite; no git push; outputs to <project>/runs/<ts>/... [ ]

• Repo layout approved (modes, templates, global prompts) [ ]

• Project layout approved (prompts, _mode/, codex.yaml, codex.sh, .gitignore) [ ]

• Include empty prompts/style.md by default [ ]

• Binary discovery: codex→codex-cli; override CODEX_BIN [ ]

• Pass-through flags: --mode --prompt-file --config --sandbox --full-auto [ ]

• Block run/new-project inside repo with helpful error [ ]

• Phase 1 (Crawl) scope acceptable [ ]

• Add docs/ROADMAP.md; MCP deferred [ ]

Final: Reply in the human doc with “Approved for Plan” when all are checked.