governance: adopt TDD with full unit/integration tests; update system prompt and AGENTS templates\n\nplan: add TDD milestones and test coverage criteria; update proposal accordingly

collab/plan/01-codexhelper.llm.md

@@ -2,15 +2,16 @@
 
 - Scope: Phase 1 (Crawl) MVP for `CodexHelper` with subcommands, scaffolding, prompt composition, config precedence, and safety.
 
-- Milestones:
-  1) CLI skeleton + guardrails
-  2) Binary detection + pass-through flags
-  3) new-mode scaffolder (repo-only)
-  4) new-project scaffolder (outside repo)
-  5) run: compose prompts + invoke codex
-  6) Config precedence (YAML+yq)
-  7) Templates + copies (AGENTS.md, prompts/_mode)
-  8) Docs: README quickstart + wrapper usage
+- 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.
@@ -23,6 +24,7 @@
   - `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
 
 - Implementation details:
   - Guard where running: inside repo → only `new-mode` allowed.
@@ -38,11 +40,12 @@
   - `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.
 
 - 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.
-

collab/plan/01-codexhelper.md

@@ -2,38 +2,34 @@
 
 Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, prompt composition, config precedence, and safety.
 
-## Milestones & Tasks
-1) CLI skeleton + guardrails
-- Add `CodexHelper` bash script with `new-project`, `run`, `new-mode` subcommands and `--help`.
-- Enforce location rules: inside this repo → only `new-mode` allowed; outside → `new-project`, `run`.
+## 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.
 
-2) Binary detection + pass-through
-- Implement `detect_codex`: `CODEX_BIN` env > `which codex` > `which codex-cli`; fail with helpful message if none.
-- Support pass-through flags: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto`, plus `--` to forward extras.
+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.
 
-3) new-mode (repo-only)
-- Create `modes/<Name>/{mode.md,defaults.yaml,system.md?}` with intake comments.
-- Refuse to overwrite unless `--force`.
+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.
 
-4) new-project (outside repo)
-- Create `<path>/<name>` (or use `<path>` if existing and empty/`--force`).
-- Copy templates:
-  - `templates/project/_shared/AGENTS.md` → `<project>/AGENTS.md`
-  - Create `prompts/project.md` (narrative template) and empty `prompts/style.md` (optional)
-  - Create `prompts/_mode/` and copy read-only references of `prompts/global/system.md` and selected mode prompts
-  - Generate `codex.yaml` with mode + codex settings (placeholders)
-  - Generate `codex.sh` entrypoint to compose prompts and call codex
-  - Add `.gitignore` (includes `runs/`)
+3) new-mode (repo-only) (tests first)
+- Write tests for scaffolding `modes/<Name>/...` and `--force` behavior.
+- Implement creation with intake comments and overwrite safeguards.
 
-5) run: compose + invoke
-- Validate project structure; ensure `prompts/_mode/` exists.
-- Compose prompts in order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
-- Create `runs/<timestamp>/` and save composed prompt and invocation metadata.
-- Invoke `$CODEX_BIN` with pass-through flags; handle `--sandbox` and `--full-auto`.
+4) new-project (outside repo) (tests first)
+- Write tests for project directory creation, copying AGENTS.md, prompts, codex.yaml, codex.sh, and `.gitignore` content.
+- Implement scaffolding and read-only copies under `prompts/_mode/`.
 
-6) Config precedence (YAML + yq)
-- Load `codex.yaml`; merge with mode defaults and global defaults.
-- Apply ENV overrides; apply CLI overrides last.
+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
 - Add `docs/wrapper.md` with usage examples and config reference.
@@ -45,6 +41,7 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p
 - 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.
 
 ## 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`.
@@ -53,13 +50,15 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p
 - 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.
 
 ## 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)
 - Day 1: Milestones 1–3
 - Day 2: Milestones 4–5
 - Day 3: Milestone 6 + Docs
-
+ - Ongoing: Maintain/expand tests with each feature change (TDD).