68 lines
4.0 KiB
Markdown
68 lines
4.0 KiB
Markdown
# 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.
|