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