diff --git a/collab/plan/01-codexhelper.llm.md b/collab/plan/01-codexhelper.llm.md index 03b59a2..e6e39ef 100644 --- a/collab/plan/01-codexhelper.llm.md +++ b/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//...` (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//`. - 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. - diff --git a/collab/plan/01-codexhelper.md b/collab/plan/01-codexhelper.md index 5a494a2..b697880 100644 --- a/collab/plan/01-codexhelper.md +++ b/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//{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 `/` (or use `` if existing and empty/`--force`). -- Copy templates: - - `templates/project/_shared/AGENTS.md` → `/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//...` 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//` 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//` 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 `/runs//...`. - 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). diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md index c5e2dc2..2897469 100644 --- a/collab/proposals/01-codexhelper.llm.md +++ b/collab/proposals/01-codexhelper.llm.md @@ -13,7 +13,8 @@ - Outputs: `/runs//...`. - Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/{system.md,system.llm.md}`, `modes//{mode.md,system.md?,defaults.yaml}`, `templates/project//...`, `templates/project/_shared/AGENTS.md`, `meta/{AGENTS.seed.md,AGENTS.seed.llm.md}`. - Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`. - - Governance/Propagation: non-project-specific workflow changes get recorded in `prompts/global/` and seed AGENTS templates; proposal/plan updated so scaffolding includes them. +- Governance/Propagation: non-project-specific workflow changes get recorded in `prompts/global/` and seed AGENTS templates; proposal/plan updated so scaffolding includes them. + - TDD Governance: adopt test-driven development with full unit/integration tests for all features in this repo and generated projects; tests written first and required for acceptance. - Phase 1 acceptance: - new-mode creates mode skeleton - new-project scaffolds without overwrites @@ -22,6 +23,7 @@ - new-project copies `templates/project/_shared/AGENTS.md` into project root as `AGENTS.md` - prompts/global present and used in prompt composition - governance rule: changes to global norms propagate to prompts/global and AGENTS templates; logged in DevLog + - tests: unit/integration tests (bats) cover CLI flows and guardrails; TDD observed \n+## Approval — Tick All That Apply - Subcommands approved: `new-project`, `run`, `new-mode` [ ] diff --git a/collab/proposals/01-codexhelper.md b/collab/proposals/01-codexhelper.md index 6927d9e..558e688 100644 --- a/collab/proposals/01-codexhelper.md +++ b/collab/proposals/01-codexhelper.md @@ -38,7 +38,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - `templates/project//...` (project scaffolding templates copied on `new-project`) - `templates/project/_shared/AGENTS.md` (AGENTS template copied into projects) - `meta/{AGENTS.seed.md, AGENTS.seed.llm.md}` (seed AGENTS templates for bootstrap/reference) - - Governance/Propagation: maintain global norms in `prompts/global/` and seed AGENTS templates; reflect such changes in proposal/plan for scaffolding. +- Governance/Propagation: maintain global norms in `prompts/global/` and seed AGENTS templates; reflect such changes in proposal/plan for scaffolding. + - TDD Governance: enforce test-driven development; require unit/integration tests for all features here and in generated projects. ## Project Layout (generated) - `AGENTS.md` (from `templates/project/_shared/AGENTS.md`) @@ -61,7 +62,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - Order: Global system → Mode system overlay (if any) → Mode rules → Project narrative. - Implementation: `codex.sh` concatenates/feeds prompts to `codex` in that order (exact mechanism depends on codex-cli interface; we’ll use files/flags as supported). - Explicit: `prompts/global/` is present and used as the base of composition. - - Governance/Propagation: non-project-specific rules are folded back into global/system and templates; changes logged. + - Governance/Propagation: non-project-specific rules are folded back into global/system and templates; changes logged. + - TDD: tests are written first and required for acceptance. ## Safety - Guardrails: @@ -96,6 +98,7 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - Project scaffold includes `AGENTS.md` copied from `templates/project/_shared/AGENTS.md`. - `prompts/global/{system.md, system.llm.md}` exist and are included in composition. - Governance/Propagation honored: when norms change, update `prompts/global/` and AGENTS templates; log in DevLog. + - TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass. ## Open Items for Confirmation - Template coverage: include `prompts/style.md` by default? (we’ll include as optional, empty file) diff --git a/docs/devlog/DEVLOG_HUMAN.md b/docs/devlog/DEVLOG_HUMAN.md index 50da713..09f64c3 100644 --- a/docs/devlog/DEVLOG_HUMAN.md +++ b/docs/devlog/DEVLOG_HUMAN.md @@ -170,3 +170,17 @@ Details: Next Steps: - Await plan review/approval; then start implementation. + +--- + +Date: 2025-09-17 16:12 (UTC) + +Summary: +- Incorporated TDD as a governance rule with full unit/integration tests for all features in this repo and generated projects. + +Details: +- Updated `prompts/global/system.{md,llm.md}`, `meta/AGENTS.seed.*`, and `templates/project/_shared/AGENTS.md` to mandate TDD. +- Amended the proposal and plan to include TDD milestones and test coverage acceptance criteria. + +Next Steps: +- Execute the plan using TDD, starting with test harness setup and failing tests. diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 5c361c2..cdb36f5 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/docs/devlog/DEVLOG_LLM.md @@ -131,3 +131,11 @@ This log is concise and structured for quick machine parsing and summarization. - Added `collab/plan/01-codexhelper.md` and `.llm.md` with milestones, deliverables, and acceptance criteria - next: - Await plan review/approval; then implement per milestones + +## 2025-09-17T16:12Z +- context: Governance update — adopt TDD and full unit tests across this repo and generated projects +- actions: + - Updated global system prompt and seed/project AGENTS templates to encode TDD requirement + - Amended proposal and plan to include TDD milestones and acceptance criteria +- next: + - Proceed with TDD in implementation; scaffold tests first diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 23c40a0..84d2111 100644 --- a/meta/AGENTS.seed.llm.md +++ b/meta/AGENTS.seed.llm.md @@ -3,7 +3,7 @@ - One-way workflow: questions → proposal → plan → implement; no backsteps after approval. - Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts. - Chat ≤5 lines; default “Updated …”; no diffs; announce only collab file changes; log details in `docs/devlog/`. -- Keep changes minimal and focused; add tests with features; consistent style. +- Keep changes minimal and focused; adopt TDD (tests first); require unit/integration tests for all features; consistent style. - Git: Conventional Commits; branch `main`; optional tags `YYYY-MM-DD-HHMM`. - Tools: file-first; use `rg`; read ≤250 lines; respect sandbox/approvals; preface grouped commands. - Prompts/config (if applicable): YAML+yq; precedence CLI>ENV>project>mode>global; prompts order global→mode-system?→mode→project; outputs to `runs//`; `--force` to overwrite; never `git push`. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index f710c07..5b8b6fa 100644 --- a/meta/AGENTS.seed.md +++ b/meta/AGENTS.seed.md @@ -24,7 +24,8 @@ Note: This is a template copied into generated projects. Customize as needed for ## Code and Tests - Keep changes minimal and focused; avoid unrelated refactors. -- Add unit tests in `tests/` alongside features. +- Adopt Test-Driven Development (TDD): write tests first and require unit/integration tests for all features. +- Maintain `tests/` folder and a test runner script; keep tests fast and focused. - Maintain consistent style with the existing codebase. ## Git Workflow diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md index 1288b44..b26dbe8 100644 --- a/prompts/global/system.llm.md +++ b/prompts/global/system.llm.md @@ -5,7 +5,7 @@ - Linear workflow: questions → proposal → plan → implement; no backsteps after approval; edits stay in current step’s file. - Chat: ≤5 lines; default “Updated …”; no diffs; only announce collab file changes; log details in `docs/devlog/`. - Dev logs: update `docs/devlog/DEVLOG_{LLM,HUMAN}.md` each meaningful change. -- Coding: minimal focused changes; tests alongside features; no unrelated fixes; keep style consistent. +- Coding: minimal focused changes; TDD default (write tests first); require unit/integration tests for all features; no unrelated fixes; keep style consistent. - Git: work on `main`; Conventional Commits; tags `YYYY-MM-DD-HHMM` when needed. - Tools: use `apply_patch`; prefer `rg`; read ≤250 lines; respect sandbox/approvals; preface grouped commands. - Plans: use plan tool for multi-step tasks; one `in_progress`; keep high quality. diff --git a/prompts/global/system.md b/prompts/global/system.md index 642b068..adc17ac 100644 --- a/prompts/global/system.md +++ b/prompts/global/system.md @@ -33,7 +33,8 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa ## Coding and Tests - Fix root causes; avoid unrelated refactors. - Keep changes minimal and consistent with existing style. -- Add unit tests under `tests/` alongside new features when appropriate. +- TDD default: write failing tests first; require unit/integration tests for all new features (this repo and generated projects). +- Maintain `tests/` and a local test runner; keep tests fast and focused. - Do not add licenses/headers unless requested. ## Git Workflow diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md index a86cca8..644eb54 100644 --- a/templates/project/_shared/AGENTS.md +++ b/templates/project/_shared/AGENTS.md @@ -21,7 +21,7 @@ This file is copied by scaffolding into new projects. Edit to suit the project w - Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog. ## Coding, Tests, and Git -- Minimal, focused changes; add tests with features; consistent style. +- Minimal, focused changes; adopt TDD (write tests first) and require unit/integration tests for all features; consistent style. - Conventional Commits; branch `main`; tags `YYYY-MM-DD-HHMM` when warranted. ## Tooling and Safety