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

01 — CodexHelper — Implementation Plan (LLM)

• Scope: Phase 1 (Crawl) MVP for CodexHelper with subcommands, scaffolding, prompt composition, config precedence, and safety.

• Milestones (TDD for each step): 0) Test harness setup (bats-core), tests/ structure, CI script (local)

  1. CLI skeleton + guardrails (write failing tests first)
  2. Binary detection + pass-through flags (tests first)
  3. new-mode scaffolder (repo-only) (tests first)
  4. new-project scaffolder (outside repo) (tests first)
  5. run: compose prompts + invoke codex (tests first)
  6. Config precedence (YAML+yq) (tests first)
  7. Templates + copies (AGENTS.md, prompts/_mode) (tests first)
  8. Docs: README quickstart + wrapper usage (ensure examples validated by tests where feasible)

• Key rules honored:

  • One-way workflow; minimal chat; read .llm.md, write both.
  • Governance/propagation: update prompts/global and seed/project AGENTS when norms change.
  • Safety: --force for overwrite; never git push; runs under <project>/runs/<ts>/.
  • Zero Technical Debt: production-ready always; no deferring docs/tests/refactors.
  • Planning/Architecture: plan ahead; maintain architecture/module map; implement module-by-module; avoid refactors unless plans/docs updated due to new info.

• Deliverables:

  • CodexHelper bash script
  • prompts/global/{system.md,system.llm.md} (already present)
  • templates/project/_shared/AGENTS.md (copy into project root)
  • templates/project/<ModeName>/... (optional mode-specific add-ons; start minimal)
  • docs/wrapper.md and README updates
  • Test harness (bats), tests/ with coverage of all CLI paths
  • docs/architecture.md and ADRs for key decisions

• Implementation details:

  • Guard where running: inside repo → only new-mode allowed.
  • Detect codex: CODEX_BIN env > which codex > which codex-cli.
  • new-mode: create modes/<Name>/{mode.md,defaults.yaml,system.md?} with intake hints.
  • new-project: create dir, copy AGENTS.md, prompts/project.md, prompts/style.md?, prompts/_mode/ with read-only copies of global+mode prompts, codex.yaml, codex.sh, .gitignore (includes runs/).
  • run: ensure project layout; compose prompts in order: global system → mode system? → mode rules → project narrative; call $CODEX_BIN with pass-through flags; write logs/artifacts to runs/<ts>/.
  • Config precedence: load YAML via yq; allow CLI/env override of codex settings and mode.

• Acceptance checks:

  • Running in repo: new-mode works; run/new-project error with guidance.
  • new-project scaffolds without overwrites; includes AGENTS.md; sets up prompts/_mode/.
  • run composes prompts and calls detected binary; artifacts under runs/<ts>/.
  • Precedence: CLI > env > project > mode > global.
  • prompts/global/ used in composition.
  • Tests: all features covered by unit/integration tests (bats); TDD observed (tests committed alongside implementation); CI/local test script present.
  • Zero Debt: docs updated; no pending TODOs/deferrals; production-ready criteria met.
  • Planning/Architecture: architecture/module map exists and matches implemented modules; no unplanned refactors.

• Open choices (defaulting now):

  • Include empty prompts/style.md: Yes.
  • Config format: YAML only; tool: yq.
  • Project .gitignore: include runs/ and any *.llm.* if user prefers later (for now, only runs/).
  • Test framework: bats-core for bash; simple runner scripts/test.sh.

• Next: Implement per milestones; add concise README quickstart.

• Accelerated Timeline (8 hours today):

  • H0–1: test harness + failing smoke tests (CLI, guardrails)
  • H1–2: CLI skeleton + guardrails (make tests pass)
  • H2–3: binary detection + pass-through (tests first)
  • H3–4: new-mode scaffolder (tests first)
  • H4–6: new-project scaffolder (tests first)
  • H6–7: run: compose + invoke (tests first)
  • H7–8: config precedence (tests first) + minimal docs

• No deferral: docs must be completed; templates polished sufficiently for production.