ChatGPTScaffolding/collab/plan/01-codexhelper.md

01 — CodexHelper — Implementation Plan

Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, prompt composition, config precedence, and safety.

Milestones & Tasks (TDD)

0. Test harness setup

• Add tests/ directory and scripts/test.sh using bats-core (document installation/usage).
• Write initial smoke tests that will fail until implementation exists.

0a) Architecture & Module Map

• Create docs/architecture.md summarizing global architecture, module boundaries, and responsibilities for Phase 1.
• Add or update ADRs as needed for key decisions.

1. CLI skeleton + guardrails (tests first)

• Write tests for --help, subcommands, and location guardrails.
• Implement CodexHelper with new-project, run, new-mode and enforce location rules.

2. Binary detection + pass-through (tests first)

• Write tests for CODEX_BIN, codex, codex-cli resolution and pass-through flags.
• Implement detect_codex and flag forwarding.

3. new-mode (repo-only) (tests first)

• Write tests for scaffolding modes/<Name>/... and --force behavior.
• Implement creation with intake comments and overwrite safeguards.

4. new-project (outside repo) (tests first)

• Write tests for project directory creation, copying AGENTS.md, prompts, codex.yaml, codex.sh, .gitignore content, and CI/containers artifacts (.gitea/workflows/ci.yml, docker/compose.yml, docker/test/Dockerfile, scripts/test.docker.sh).
• Implement scaffolding and read-only copies under prompts/_mode/.

5. run: compose + invoke (tests first)

• Write tests for prompt composition order, runs/<timestamp>/ outputs, and invocation args.
• Implement composition and execution using $CODEX_BIN.

6. Config precedence (YAML + yq) (tests first)

• Write tests covering precedence: global < mode < project < env < CLI.
• Implement merging with yq and apply overrides.

7. Docs (no deferral)

• Add docs/wrapper.md with usage examples and config reference.
• Update README.md quickstart: installation, basic flows.
• Ensure docs updated in the same commit as features.

Safety & Policies

• Never overwrite without --force.
• Never git push for user projects.
• Write outputs to <project>/runs/<timestamp>/....
• Minimal chat; read .llm.md, write both .md and .llm.md for collab artifacts.
• Governance/Propagation: reflect future non-project-specific norms into prompts/global/ and AGENTS templates; log in DevLog.
• TDD default: write failing tests before implementing features; require unit/integration tests for all new functionality in this repo and generated projects.
• Zero Technical Debt: safety first; no technical debt; always production-ready; do not defer tests/docs/refactors; use sub-agents as needed to maintain quality and speed.
• Planning/Architecture: align via Questions→Proposal→Plan; maintain docs/architecture.md and ADRs; avoid refactors except when plans/docs are updated due to new information.

Acceptance Criteria

• Inside this repo: CodexHelper new-mode --name Demo creates modes/Demo/{mode.md,defaults.yaml} (and optional system.md) and refuses overwrites without --force.
• Outside this repo: CodexHelper new-project --mode Demo --name demo --path /tmp creates project with AGENTS.md, prompts/{project.md,style.md}, prompts/_mode/ (copies of global+mode), codex.yaml, codex.sh, .gitignore (with runs/).
• Inside the new project: CodexHelper run --full-auto composes prompts and calls detected binary; artifacts under runs/<timestamp>/....
• Precedence: CLI > env > project > mode > global.
• prompts/global/{system.md,system.llm.md} are present and included in composition.
• Running CodexHelper run or new-project inside this repo errors with guidance.
• Tests: bats test suite covers all CLI paths and guardrails; tests pass locally; test runner script present.
• Project CI: scaffold contains Gitea workflow and Docker artifacts for local parity.

Assumptions/Risks

• codex-cli flags may vary; we’ll design pass-through and document tested flags.
• yq is available; if missing, we provide a helpful error.
• bats-core availability assumed; if not present, document installation and provide graceful skip with clear message.

Timeline (targeted)

Accelerated (8 hours today):

• Hour 0–1: Test harness setup; write failing smoke tests (CLI, guardrails)
• Hour 0–1 (parallel): Draft docs/architecture.md (module map) and commit
• Hour 1–2: Milestone 1 — CLI skeleton + guardrails (make tests pass)
• Hour 2–3: Milestone 2 — Binary detection + pass-through (tests first)
• Hour 3–4: Milestone 3 — new-mode scaffolder (tests first)
• Hour 4–6: Milestone 4 — new-project scaffolder (tests first)
• Hour 6–7: Milestone 5 — run: compose + invoke (tests first)
• Hour 7–8: Milestone 6 — Config precedence (tests first); finalize quickstart docs
• Ongoing: Maintain/expand tests with each feature change (TDD).