79 lines
4.8 KiB
Markdown
79 lines
4.8 KiB
Markdown
# 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).
|