plan: add 8-hour accelerated timeline; maintain TDD across milestones

AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md — Working Agreements and Conventions
+
+Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.
+
+Note: The canonical system rules used by the agent are mirrored in `prompts/global/system.md` (human) and `prompts/global/system.llm.md` (LLM). Keep AGENTS.md and the system prompt aligned. A seed AGENTS template for generated projects lives at `meta/AGENTS.seed.md` (and `.llm.md`).
+
+## Collaboration Artifacts
+- Root: `collab/`
+- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
+- Naming per round: `NN-<subject>.md` inside each subdirectory (e.g., `00-bootstrap.md`, `01-codexhelper.md`).
+- LLM-optimized copies: add `.llm.md` sibling files (e.g., `01-codexhelper.llm.md`) that are concise and machine-friendly.
+- Versioning: start a new numbered file for major rounds rather than expanding one doc indefinitely.
+- Principle: Keep chat minimal; prefer file-based collaboration via these documents.
+
+### Sequencing Rules
+- Begin with a questions file in `collab/questions/` and iterate there until the agent is satisfied or the user instructs to proceed.
+- Do not create a proposal or plan until the questions have been edited by the user and explicitly approved.
+- After approval, create a concise proposal in `collab/proposals/` and a concrete plan in `collab/plan/`, then implement.
+- One-way progression: once a step (questions → proposal → plan) is approved, do not return to a prior step. Perform any subsequent clarifications/edits within the current step’s file for that round (e.g., continue editing `collab/proposals/NN-*.md` after proposal approval) and only create the next step’s file when moving forward.
+- Artifact edits live in-place: Users/humans will edit the non-LLM `.md` files; the agent reads `.llm.md` and writes both `.md` and `.llm.md` siblings for every collaboration artifact.
+
+### One-Time Exceptions
+- Only bypass the Questions→Proposal→Plan cycle when explicitly directed by the user; log such exceptions in `docs/devlog/`.
+
+## Logs and Documentation
+- Dev logs: `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` updated each meaningful change.
+- Project docs: `docs/` for feature docs (`<feature>.md`) and architectural decisions (`adr-<feature>.md`).
+- README: Keep `README.md` current with quickstart and usage.
+
+## Code and Tests
+- Add unit tests in `tests/` alongside features as they are introduced.
+- Keep changes minimal and focused. Avoid unrelated refactors.
+
+## Git Workflow
+- Branch: work on `main` for now.
+- Commits: concise, present-tense; Conventional Commits style preferred (e.g., `feat:`, `fix:`, `chore:`).
+- Releases/Tags: `YYYY-MM-DD-HHMM` when warranted; use `tea` if configured.
+
+## Wrapper Project Guidelines
+- Aim: Bash wrapper around `codex-cli` with modes (global prompt, mode prompt, project prompt, codex settings, MCP).
+- Approach: crawl → walk → run. Start with documented defaults and override via flags/env/config.
+- Wizards: Intake markdown forms for creating modes and projects.
+
+## Agent Notes
+- Ask clarifying questions in `collab/<...>-questions.md`.
+- Propose in `collab/<...>-proposal.md`, plan in `collab/<...>-plan.md`, then implement.
+- Respect repository structure and this AGENTS.md across all changes.
+
+## Token/Context Hygiene
+- Chat minimalism: keep messages short; prefer pointers to files over inline dumps.
+- Use `.llm.md` files for concise, machine-friendly summaries; avoid duplicating full human docs.
+- Read `.llm.md` for intake; do not rely on `.md` for reading. Write both `.md` and `.llm.md` when updating artifacts.
+- No large pastes in chat: never paste large code or markdown; write to files and reference paths/sections.
+- Incremental artifacts: start a new `NN-<subject>.md` per round to avoid long single files.
+- Status style: one-line updates before tool calls; rely on devlog for detail.
+- Avoid re-reading large files in chat; reference exact file paths and sections instead.
+
+## Chat Output Policy
+- Default message: `Updated <filepath>. Read/edit and let me know.`
+- Keep chat to five lines or fewer.
+- Do not paste diffs or file contents in chat; write to files instead.
+- Aggregate multiple updates in a short bulleted list of filepaths.
+- Push detailed reasoning/status to `docs/devlog/` and reference it when needed.
+- Only announce changes to collaboration files: `collab/questions/`, `collab/proposals/`, and `collab/plan/`.
+- For all other changes (docs, code, configs), skip chat announcements and log in DevLog.

SeedPrompt.md

@@ -0,0 +1,78 @@
+(We are in a codex-cli session and i've instructed it to read this file but given it no other instructions)
+
+
+## Meta Rules
+
+- Please keep a development log of your work (In both llm optimized form and human readable form ) (separate files) (in a subdirectory called devlog)
+- Please commit frequently and push/tag a release (YYYY-MM-DD-HHMM) (using the tea command) when you feel it's warranted (all work is done on main for now)
+- Please create and maintain README.md and a docs/ directory with <feature>.md and <adr-feature>.md as we go
+- Please create and maintain unit tests as we go in a tests/ directory
+
+
+## Ultimate goal of this project
+
+A wrapper bash script around codex-cli allowing the use of "modes" which will be a collection of 
+
+- A fixed Global system prompt 
+- A fixed Mode  prompt
+- A variable (user defined) project specific prompt
+- Codex settings (model/token budget/reasoning level etc)
+- MCP configuration
+
+Also:
+
+- A "wizard" to create new modes (by filling out a markdown file intake form)
+- A "wizard" to create new projects (by filling out a markdown file intake form)
+
+## Approach
+
+Lets "crawl/walk/run" , starting with a simple wrapper script for codex-cli that has (documented) defaults set but also allows (via command line flags/environment variables/config file) over-riding the options 
+
+This should be very collaborative. Ask questions (in a markdown file), once they are answered then create a proposal for review/approval, then create a plan for review/approval. Then once everything is approved, implement the code for review and approval.
+
+I want to be able to test the code early/often and be able to provide feedback. I want to be able to edit markdown files inline to provide context/ask questions etc as we go. The chat interface itself should be kept very clean as it's running in the bottom of my vscode instance and I want to use vscode markdown facilities to rapidly read/edit the markdown files. So our primary way of interacting
+will be via those files.
+
+Commit/push everything in the repo now before we get started on the project.
+
+---
+
+## Addendum (Housekeeping) — 2025-09-17
+
+- Create and use a `collab/` directory for coordination artifacts.
+- Under `collab/`, create subdirectories: `questions/`, `proposals/`, and `plan/`.
+- Use consistent filenames: `<step-or-subject>.md` inside each subdirectory.
+- Move existing files accordingly (e.g., `collab/questions/00-bootstrap.md`).
+- Create and maintain an `AGENTS.md` at the repo root with working agreements and conventions.
+- Continue keeping `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` updated.
+- After applying this structure, commit and push the changes.
+
+### Chat Output Preference
+
+- Keep chat output concise and minimal. The primary collaboration interface is via repository files (collab/, devlog/, docs/). Use chat only for brief status updates or to announce next actions.
+
+### Collaboration Sequencing
+
+- Start with questions in `collab/questions/` and keep iterating/adding questions until satisfied or instructed to move on.
+- Do not create proposals or plans until the questions file has been edited by the user and the user gives explicit approval.
+
+### Files Per Round + LLM Copies
+
+- Use multiple files per round rather than growing a single document.
+- Naming: `collab/<type>/NN-<subject>.md` (human) and `collab/<type>/NN-<subject>.llm.md` (LLM-optimized).
+- Start a new `NN` for each major round; keep subject consistent across types.
+
+### Token Discipline
+
+- Keep chat output extremely concise; use the filesystem (docs/devlog, collab/) for details.
+- Summarize for the model in `.llm.md` companions; keep human-readable detail in the primary `.md`.
+- Do not paste large content into chat; write to files and reference paths.
+- Prefer starting new numbered files per round to keep each doc short.
+
+### Chat Output Policy
+
+- Default chat line: `Updated <filepath>. Read/edit and let me know.`
+- Limit chat to five lines or fewer; avoid explanations in chat.
+- Never paste diffs or large content in chat; commit to files and reference paths.
+- Log detail in `docs/devlog/` and keep the chat terminal clean.
+- Only announce updates for `collab/questions/`, `collab/proposals/`, and `collab/plan/` files. All other updates go to DevLog without chat noise.

collab/plan/01-codexhelper.llm.md

@@ -0,0 +1,62 @@
+# 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>/`.
+
+- 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
+
+- 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.
+
+- 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
+ 
+ - Defer if needed: expand docs; polish templates.

collab/plan/01-codexhelper.md

@@ -0,0 +1,72 @@
+# 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.
+
+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, and `.gitignore` content.
+- 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
+- Add `docs/wrapper.md` with usage examples and config reference.
+- Update `README.md` quickstart: installation, basic flows.
+
+## 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.
+
+## 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.
+
+## 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 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); write quickstart docs
+
+Notes:
+- If behind schedule, defer non-essential docs to a follow-up commit and prioritize tested functionality.
+ - Ongoing: Maintain/expand tests with each feature change (TDD).

collab/proposals/01-codexhelper.llm.md

@@ -0,0 +1,43 @@
+# 01 — CodexHelper — Proposal (LLM)
+
+- Tool: `CodexHelper` bash wrapper for codex-cli.
+- CLI (subcommands):
+  - new-project: scaffold project files
+  - run: compose prompts + call codex
+  - new-mode: scaffold mode (repo-only)
+- Where to run: repo → only new-mode; elsewhere → new-project, run.
+- Prompts order: global system → mode system overlay (optional) → mode rules → project narrative.
+- Config: YAML + yq; precedence CLI > env > project > mode > global.
+- Binary: detect `codex` then `codex-cli`; override `CODEX_BIN`.
+- Safety: no overwrites without `--force`; never `git push` for user projects.
+- Outputs: `<project>/runs/<ts>/...`.
+- Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/{system.md,system.llm.md}`, `modes/<Name>/{mode.md,system.md?,defaults.yaml}`, `templates/project/<Name>/...`, `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.
+ - 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
+  - run composes and calls detected codex; writes under runs/
+  - precedence respected; running in repo errors for run/new-project
+  - 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` [ ]
+- Scope approved: repo→`new-mode` only; outside→`new-project`/`run` [ ]
+- Prompts order approved: global→mode-system?→mode→project [ ]
+- Config+precedence approved: YAML+yq; CLI>ENV>project>mode>global [ ]
+- Safety approved: `--force` to overwrite; no `git push`; outputs to `<project>/runs/<ts>/...` [ ]
+- Repo layout approved (modes, templates, global prompts) [ ]
+- Project layout approved (prompts, `_mode/`, codex.yaml, codex.sh, .gitignore) [ ]
+- Include empty `prompts/style.md` by default [ ]
+- Binary discovery: `codex`→`codex-cli`; override `CODEX_BIN` [ ]
+- Pass-through flags: `--mode --prompt-file --config --sandbox --full-auto` [ ]
+- Block `run`/`new-project` inside repo with helpful error [ ]
+- Phase 1 (Crawl) scope acceptable [ ]
+- Add `docs/ROADMAP.md`; MCP deferred [ ]
+
+Final: Reply in the human doc with “Approved for Plan” when all are checked.

collab/proposals/01-codexhelper.md

@@ -0,0 +1,125 @@
+# 01 — CodexHelper — Proposal
+
+Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes”, project scaffolding, and a clean CLI.
+
+## Summary of Agreed Direction
+- Name/Install: `CodexHelper` script in this repo; users add it to PATH. Optional `bin/install.sh` to symlink into `~/bin`.
+- CLI Style: Subcommands — `new-project`, `new-mode`, `run`.
+- Where to run: Outside this repo → `new-project`, `run`. Inside this repo → only `new-mode`.
+- Modes/Prompts: Global system (repo-wide) → optional mode system overlay → mode rules → project narrative.
+- Config: YAML with `yq`. Precedence: CLI > env > project > mode > global defaults.
+- Binary discovery: `which codex`, then `which codex-cli`; override with `CODEX_BIN`. No auto-install.
+- Safety/Outputs: Never overwrite without `--force`; never `git push` in user projects; write runs to `<project>/runs/<timestamp>/...`.
+- Licensing: Repo (wrapper, modes, prompts) AGPLv3; user artifacts are user-licensed.
+- OS/Deps: Ubuntu/Debian, bash/zsh; deps: bash, git, yq.
+
+## CLI
+- `CodexHelper new-project --mode <ModeName> --name <project-name> --path <dir> [--force] [--sandbox <mode>] [--full-auto] [--config <file>]`
+  - Creates project structure in `<dir>/<project-name>` (or `<dir>` if it exists):
+    - `prompts/project.md` (narrative template), optional `prompts/style.md`
+    - `prompts/_mode/` with copies of global/mode prompts
+    - `codex.yaml` (mode + settings + MCP placeholders)
+    - `codex.sh` (entrypoint wrapper that resolves config and calls `codex`)
+    - `.gitignore` (includes `runs/`)
+- `CodexHelper run [--mode <ModeName>] [--prompt-file <file>] [--config <file>] [--sandbox <mode>] [--full-auto] [--force]`
+  - Must be run inside a project dir; composes prompts in correct order; writes logs to `runs/<timestamp>/...`.
+  - Respects precedence: CLI > env > project > mode > global.
+- `CodexHelper new-mode --name <ModeName>` (only in this repo root)
+  - Scaffolds `modes/<ModeName>/mode.md` and optional `modes/<ModeName>/system.md`, plus `modes/<ModeName>/defaults.yaml`.
+  - Uses a markdown intake template for quick editing.
+
+## Repository Layout (this repo)
+- `CodexHelper` (bash)
+- `bin/install.sh` (optional symlink helper)
+- `prompts/global/{system.md, system.llm.md}` (global system rules; human + LLM)
+- `modes/<ModeName>/mode.md` (mode rules)
+- `modes/<ModeName>/system.md` (optional mode-specific system overlay)
+- `modes/<ModeName>/defaults.yaml` (default codex settings, optional MCP placeholders)
+- `templates/project/<ModeName>/...` (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.
+ - 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`)
+- `prompts/project.md` (+ optional `prompts/style.md`)
+- `prompts/_mode/` (read-only copies from this repo)
+- `codex.yaml` (project config)
+- `codex.sh` (entrypoint wrapper around codex-cli)
+- `runs/` (created on first run; ignored by VCS)
+
+## Config Details
+- Format: YAML (`yq` for merging/reading)
+- Precedence resolution: merge defaults in order — global defaults → mode defaults → project config → env vars → CLI flags.
+- Key fields in `codex.yaml`:
+  - `mode: <ModeName>`
+  - `codex:` `{ model, token_budget, reasoning_level, sandbox, full_auto, extra_args[] }`
+  - `prompts:` `{ project: prompts/project.md, mode_dir: prompts/_mode }`
+  - `mcp:` placeholders (deferred per roadmap)
+
+## Prompt Composition
+- 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.
+  - TDD: tests are written first and required for acceptance.
+
+## Safety
+- Guardrails:
+  - Refuse `run` and `new-project` inside this repo; allow only `new-mode` here.
+  - Refuse to overwrite files unless `--force`.
+  - Never execute `git push` in user projects.
+
+## Crawl → Walk → Run
+- Crawl (Phase 1 — initial MVP):
+  - `CodexHelper` with subcommands implemented.
+  - Global system location and one example mode scaffolder.
+  - Project scaffold: prompts, codex.yaml, codex.sh, .gitignore (runs/).
+  - Config precedence implemented; sandbox/full-auto pass-through.
+  - Binary detection and friendly error messages.
+  - Minimal docs: README quickstart; `docs/wrapper.md` for usage.
+- Walk (Phase 2):
+  - `--interactive` prompts for missing values.
+  - Mode defaults (`defaults.yaml`) respected and merged.
+  - Basic tests for key flows; improved logging in `runs/`.
+  - Add `docs/ROADMAP.md` entries and initial MCP placeholders.
+- Run (Phase 3):
+  - Mode/project wizards via markdown intake with validation.
+  - MCP integration options.
+  - Additional quality-of-life flags and templates.
+
+## Acceptance Criteria (Phase 1)
+- Running `CodexHelper new-mode --name Demo` inside this repo creates `modes/Demo/{mode.md,defaults.yaml}`.
+- Running `CodexHelper new-project --mode Demo --name demo --path /tmp` creates a project with files listed above, without overwrites unless `--force`.
+- Inside that project, `CodexHelper run --full-auto` composes prompts and calls the detected `codex` binary. It writes artifacts under `runs/<timestamp>/...`.
+- Precedence works: CLI options override env, which override project config, which override mode defaults.
+- Running `CodexHelper run` in this repo prints an error guiding usage.
+ - 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)
+- Exact prompt-passing flags to `codex-cli` (confirm once coding — will use pass-through and files as supported).
+
+## Next Step
+- On approval, I will create a concrete implementation plan at `collab/plan/01-codexhelper.md` and proceed with the Crawl phase implementation.
+
+## Approval Checklist
+Please answer inline. When all are approved, reply “Approved for Plan”.
+
+1) Subcommands: approve `new-project`, `run`, `new-mode`? Any renames?
+2) Scope: inside this repo allow only `new-mode`; outside allow `new-project` and `run`?
+3) Prompts order: global system → mode system overlay (optional) → mode rules → project narrative?
+4) Config format/precedence: YAML with `yq`; CLI > env > project > mode > global?
+5) Safety: require `--force` to overwrite; never `git push` for user projects; outputs under `<project>/runs/<timestamp>/...`?
+6) Repo layout: `CodexHelper`, `prompts/global/system.md`, `modes/<Name>/{mode.md, system.md?, defaults.yaml}`, `templates/project/<Name>/...`?
+7) Project layout: `prompts/{project.md, style.md?}`, `prompts/_mode/` (read-only copies), `codex.yaml`, `codex.sh`, `.gitignore (runs/)`?
+8) Include empty `prompts/style.md` by default?
+9) Binary discovery: try `codex` then `codex-cli`; allow override `CODEX_BIN`?
+10) Pass-through flags: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto` to underlying `codex`?
+11) Block `run` and `new-project` inside this repo with a helpful error?
+12) Phase 1 (Crawl) scope acceptable as listed?
+13) Roadmap: add `docs/ROADMAP.md`; defer MCP integration for now?

collab/questions/00-bootstrap.llm.md

@@ -0,0 +1,21 @@
+# 00 — Bootstrap — Questions (LLM)
+
+- Remote: origin main; push enabled.
+- Tagging: local time `YYYY-MM-DD-HHMM`.
+- Commits: Conventional Commits.
+- Codex binary: detect `codex` then `codex-cli`; allow `CODEX_BIN` override.
+- Invocation defaults: user currently uses `codex --sandbox workspace-write --full-auto`; make these configurable.
+- Defaults: accept codex-cli defaults for model/token/reasoning unless overridden.
+- Precedence: CLI > env > project > mode > global.
+- Config files: project-contained; no user home dotfiles.
+- Prompts storage: in this repo — global system + mode rules (and optional mode system overlay). Projects elsewhere.
+- Projects: not inside this repo; wrapper used from external project directories.
+- MCP: mix of per-mode defaults + per-project; defer implementation (track in `docs/ROADMAP.md`).
+- Wizards: basic for now (mode: name/desc/defaults/prompts/MCP; project: name/path/prompt/default mode/overrides).
+- CLI UX: prefer subcommands; inside this repo allow only `new-mode`; outside support `new-project` and `run`.
+- Outputs: write to `<project>/runs/<timestamp>/...`.
+- Safety: never overwrite without `--force`; never run `git push` for user projects.
+- Licensing: repo AGPLv3; user artifacts are user-licensed.
+- OS/Deps: Ubuntu/Debian; bash, git, yq.
+- Install: use `CodexHelper` from PATH; provide optional `bin/install.sh` to symlink.
+- Copy prompts: on project scaffold, copy global/mode prompts into `prompts/_mode/` in project (read-only annotated) and compose: global → mode overlay → mode rules → project narrative.

collab/questions/00-bootstrap.md

@@ -0,0 +1,236 @@
+# 00 — Bootstrap — Questions
+
+These questions guide the initial design and implementation. Please answer inline.
+
+Process note: We will continue to add or refine questions here until you approve this questions file. Only after approval will we draft a proposal and a plan.
+
+## Repo & workflow
+1. Git remote: Should we push to an existing remote? If yes, provide the remote URL and branch (default `origin main`).
+
+Yes. Remote is already setup, origin main works.
+
+2. Tagging: Use `YYYY-MM-DD-HHMM` in local time or UTC? Use `tea` only for tagging/releases, or also for pushes?
+
+local time
+I'll leave it to you to utilize git/tea commands how you see fit. That's an implementation detail as far as i'm concerned.
+
+3. Commit cadence: Any specific commit style (e.g., Conventional Commits)?
+
+Yes Conventional Commits always.
+
+## codex-cli wrapper
+4. codex-cli path: How is `codex`/`codex-cli` invoked in your environment (command name, install path)?
+
+Use which to figure out the path, I am not sure.
+For now, I use 
+
+codex --sandbox workspace-write --full-auto
+
+(We will need to let those options be set as well)
+
+5. Defaults: Preferred default model, token budget, and reasoning level?
+
+I am not sure. I've been happy with the defaults out of the box so far. 
+
+
+6. Config precedence: Order of overrides? (e.g., CLI flags > env vars > project config > mode config > global defaults)
+
+yes I think so. I believe that is the common convention? 
+
+In my mind, a project config would be a complete collection of everything needed and packed into a shell script that fires 
+up codex and feeds it the project/mode/system prompt.
+
+
+7. Config files: Desired locations/names? (e.g., `.codexrc`, `.codex/mode.yaml`, `project.yaml`)
+
+I don't want anything in a user home directory. I want it all contained in a project. 
+
+
+8. Prompts storage: Where to store Global System Prompt, Mode Prompt, and Project Prompt? (proposal: `modes/<name>/system.md`, `modes/<name>/mode.md`, `projects/<name>/prompt.md`)
+
+Right. 
+
+I don't want projects under this directory/repository. I don't want to pollute this repository with projects. They would go in a sibling directory or anywhere else the user wants them. This repository is just for the scaffolding project itself (shell script, example configs, template scaffolding for projects and modes) and of course the various modes themselves (and an example project of a resume rewriter to match to a job description).
+
+
+9. MCP configuration: Expected format and location? (JSON/YAML/TOML; per-mode vs per-project)
+
+I believe it would be a mix of per-mode (defaults) and per-project (as needed). So, for example, a software mode project at TSYS (my company) would have Cloudron/Gitea/Redmine MCP servers by default and then the project may add in language specific  MCP servers. I am not sure how to handle MCP, I want to tackle that last, as it's quite complex. (Ensure you create and maintain a ROADMAP.md file in the docs direcotry).
+
+## Wizards
+10. Mode wizard fields: Minimum fields for a mode (name, description, defaults, prompts, MCP config)? Any templates you prefer?
+11. Project wizard fields: Minimum fields for a project (name, path, project prompt, default mode, overrides)?
+
+Yes I think that's fine for now.
+
+## Execution behavior
+12. Mode selection: CLI flags `--mode`, `--project`, and optional `--prompt-file` acceptable?
+
+Hmmmm. I think just --mode. So heres my thinking... I would create and clone a new git repo somewhere in my home directory. I would have this shell script added to my path. I would go to my newly cloned repo, and I would run CodexHelper --mode SAASApp (let's say) and that would then scaffold a project of that mode? I'm struggling a bit to articulate what I want and think through the usage/implementation. I suppose maybe it would be  combo of --mode and --new-project or something like that? Basically I'm tired of maintaining a library of markdown files that I cobble together in each new project I run codex in. I want a way to streamline that.
+
+13. Non-interactive: Should wrapper fully resolve configs non-interactively by default, with an `--interactive` flag for wizard-like prompting?
+
+Hmmm. I am not sure. I haven't fully thought through the usage modes yet.
+
+14. Output handling: Where to log transcripts or runs? (proposal: `runs/<timestamp>/…`)
+
+That should NOT be in this project/directory. It should be wherever the script is invoked from. If the script is invoked in this repo working directory, it should only be for creating new modes. (or of course running unit tests etc)
+
+15. Safety: Any commands that must never be executed without confirmation?
+
+Hmmm. I am not sure. I haven't fully thought through the usage modes yet. Open to suggestions/trying things out.
+
+
+## Misc
+16. Licensing/headers: Any repo-specific requirements beyond the existing LICENSE?
+
+I want to clearly state that this repo is AGPLv3 (code/prompts) but NOT anything the user writes in their project specific prompt and any code they generate. Basically the "code" (shell script/prompt files) in this repo is AGPLv3 but the "data" (any artifacts they write or codex creates with them) is up to them to license.
+
+17. Supported OS/shells: Target bash/zsh on macOS/Linux, anything else?
+
+Lets say Ubuntu 22.04/Debian 12 or later. 
+
+## Followup 2025-17-09-14:21
+
+### Wrapper naming & install
+1. Wrapper name: prefer `codex-helper` or `CodexHelper`? Install path (e.g., `~/bin`)?
+
+CodexHelper please
+This will not be "installed". It will be cloned , the CodexHelper shell script added to the users path. The CodexHelper is only an entrypoint and wrapper around codex-cli (CodexHelper should have a bootstrap function to ensure codex-cli is actually installed of course). The CodexHelper script will be called from within a project directory somewhere else on the filesystem. It may or may not be a git repository working directory.
+
+2. Binary discovery: try `which codex` first, then `codex-cli`? Allow override via `CODEX_BIN` env var?
+
+Sure.
+
+### Modes and templates
+3. Repo layout: store modes under `modes/<name>/` with `system.md`, `mode.md`, `defaults.yaml`? OK?
+
+Yes. However the system prompt is shared across all modes. It will be about a dozen rules or so that I want applied to all of my projects.
+
+Perhaps we should allow a mode specific system prompt as well? I don't know enough about how prompts are chained or stacked to fully
+understand the implications. 
+
+Basically I want a base set of global rules, a mode set of rules and then a project prompt (which won't be rules per se (well maybe coding styles or something)) but more of a narrative/descriptive set of material telling codex WHAT to do (not so much how to do it)
+
+
+4. Project scaffolding: create templates under `templates/project/<mode>/...` and generate into user-specified target path? OK?
+
+I am not sure what this means? Give me some examples?
+
+5. Example project: include only one example (resume rewriter). Where should we place the example template in this repo?
+
+Actually forget all about the example project. I'm going to do that in a different repository. I want this project/repo to be purely code/prompts.
+
+### Project structure & config
+6. Config format: YAML vs JSON vs TOML? Preference? (YAML easier for markdown-heavy prompts.)
+7. Single file vs split: prefer `project.yaml` in project root, or split into `prompts/` + `codex.yaml`?
+8. Precedence confirm: CLI > env > project > mode > global defaults — confirm this exact order?
+9. Entrypoint script: generate `codex.sh` in project root that resolves config and runs `codex`? Name OK?
+
+I think that all looks good. I'll leave it to your discretion. I need to get a "feel" for the usage and tweak as we go.
+
+### CLI UX
+10. Subcommands: propose `new-project`, `new-mode`, and `run`. Example:
+    - `codex-helper new-project --mode SAASApp --name my-app --path ~/dev/my-app`
+    - `codex-helper new-mode --name SAASApp`
+    - `codex-helper run` (inside a project dir)
+    Approve?
+
+
+11. Flags: always accept `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto` to pass through to codex. Anything else?
+12. Non-interactive default: default non-interactive; add `--interactive` to prompt for missing values. Approve?
+
+Yes I think that all looks good.
+
+### Outputs, safety, and licensing
+13. Runs directory: write transcripts/logs to `<project>/runs/<timestamp>/...`. Approve?
+
+Well remember, we don't allow the script to run from inside the repo checkout directory except to create new modes. 
+
+14. Safety: default to no destructive actions; require `--force` to overwrite existing files; never run `git push` for user projects. Approve and add anything else?
+
+User projects will never be created in this repo. 
+
+15. Dependencies: are `bash`, `git`, and one of `jq` (JSON) or `yq` (YAML) acceptable? Preference?
+
+Sure. I suppose we should settle on either json or yaml? Supporting both seems like more work?
+
+16. Licensing in generated projects: include no default LICENSE, or include a template with TODO? Preference?
+
+The user will pick a license. We won't be invovled.
+
+### Roadmap
+17. We will add `docs/ROADMAP.md` and defer MCP integration. Any additional roadmap items you want listed now?
+
+No
+
+## Followup 2025-17-09-14:33
+
+### CLI UX and workflow
+1. Subcommands vs flags-only: prefer simple flags (e.g., `CodexHelper --mode SAASApp --new-project`) or explicit subcommands (`CodexHelper new-project --mode SAASApp`)? Please pick one.
+
+What are the tradeoffs? I don't really have a strong opinion either way. What do you think is the better UX? I think the subcommands looks a bit nicer.
+
+2. Project creation flow: confirm that `CodexHelper` runs from any project dir outside this repo to scaffold project files for a chosen mode; this repo is only for modes and the wrapper. Correct?
+
+That iscorrect. Modes, wrapper, prompts to be explicit.  (Of course a mode would have prompts and (eventaully) MCP config templates etc). I think we are on the same page.  Now, CodexHelper would run inside the repo to create a new mode. That would be the only command supported when running inside the repo (it would scaffold a new mode for bootstrap via filling out markdown intake files). 99.9% of the CodexHelper usage will be outside of the repo, yes.
+
+### Templates and scaffolding
+3. Examples for project scaffolding (pick what you want generated initially):
+   - prompts/: `project.md` (narrative), optional `style.md`
+   - config: `codex.yaml` (mode selection, settings, MCP placeholders)
+   - helper: `codex.sh` entrypoint that resolves config and runs `codex`
+   - runs/: created on first run, ignored by VCS
+   Keep/delete/adjust which of these?
+
+All of that looks good. What about the system prompt/mode prompt? And I presume the codex.sh invoking of codex would also automatically pass in project.md (and somehow the system/mode prompt as well)? Can the system/mode prompt be copied (read only) to the project directory? THis would allow the entire thing to be self contained/commited to git etc? And the read only bit could easily be removed if the user wants to edit the system/mode prompt.
+   
+
+### Prompts composition
+4. Confirm stacking order: Global system rules → Mode rules → Project narrative prompt. OK?
+
+Yes. That is correct.
+
+5. Locations proposal: `prompts/global/system.md` (repo-wide), `modes/<name>/system.md` (optional overlay), `modes/<name>/mode.md` (mode rules), project `prompts/project.md`. Approve?
+
+What would the optional overlay be for? Tell me more about that?
+project.md wouldn't be in this repo (or is that a blank placeholder file (or maybe a one line "put your instructions here" or something)) that gets copied into the project directory during bootstrap?
+
+### Config and tooling
+6. Format/tooling: choose YAML + `yq` as the single supported format/tool. Approve?
+Yes
+
+## Explainers 2025-17-09-14:52
+
+- Subcommands vs flags-only (tradeoffs):
+  - Subcommands: clearer discoverability (`CodexHelper new-project|new-mode|run`), better `--help` per action, easier future growth. Flags-only keeps one surface but is harder to parse and extend. Recommend subcommands; flag-only aliases can follow later if wanted.
+- Project scaffolding examples:
+  - In project: `prompts/project.md` (narrative), optional `prompts/style.md` (coding/style), `codex.yaml` (mode/config/MCP placeholders), `codex.sh` (entrypoint). `runs/` created on first run and ignored by VCS.
+  - `codex.sh` composes prompts: global system → mode rules → project narrative; passes them to `codex` with settings.
+- Mode/system prompt copies:
+  - Copy global/mode prompts into `prompts/_mode/` in the project as read-only templates (annotated header). Project becomes self-contained; users may edit if desired.
+- Optional mode-specific system overlay:
+  - For modes that need extra or tweaked system-level rules, include `modes/<name>/system.md` merged before mode rules.
+- `project.md` here vs user projects:
+  - This repo keeps a template (e.g., `templates/project/<mode>/prompts/project.md`) which bootstrap copies to user projects; users then author real content there.
+
+7. Precedence final confirm: CLI > env > project > mode > global defaults. Approve?
+
+Yes
+
+8. Binary detection: detect `codex` then `codex-cli`, override with `CODEX_BIN`. On missing, print instructions; no auto-install. Approve?
+
+Yes
+
+### Outputs and safety
+9. Runs location: always `<cwd>/runs/<timestamp>/...` (never in this repo unless creating modes). Approve?
+Yes
+
+10. Safety: never overwrite without `--force`; never run `git push` in user projects. Anything else to lock down?
+
+Cant think of anything
+
+### Install convenience
+11. Provide optional `bin/install.sh` to symlink `CodexHelper` into `~/bin` (no sudo). Include or skip?
+
+Yes

docs/devlog/DEVLOG_HUMAN.md

@@ -0,0 +1,186 @@
+# Development Log (Human Readable)
+
+Date: 2025-09-17 08:55 (UTC)
+
+Summary:
+- Bootstrapped collaboration scaffolding based on SeedPrompt.md.
+- Created dev logs (LLM-optimized and human-readable) and a QUESTIONS.md file.
+
+Details:
+- Rationale: Establish clear, file-based collaboration channels (logs + questions) with minimal noise in chat.
+- Scope: No functional code yet; this is setup to enable fast iteration.
+
+Next Steps:
+- Collect answers in `collab/questions/00-bootstrap.md`.
+- With clarifications, propose initial design and plan for the wrapper script (crawl phase).
+
+Notes:
+- Tagging a release and using `tea` is deferred until we have a first runnable wrapper or as directed.
+
+---
+
+Date: 2025-09-17 09:05 (UTC)
+
+Summary:
+- Introduced `collab/` directory; moved QUESTIONS into `collab/questions/00-bootstrap.md`.
+- Added `AGENTS.md`; appended housekeeping Addendum to `SeedPrompt.md`.
+
+Details:
+- Establishes consistent file-based collaboration area and naming scheme.
+
+Next Steps:
+- Await answers to bootstrap questions, then proceed after approval.
+
+---
+
+Date: 2025-09-17 14:52 (UTC)
+
+Summary:
+- Adjusted questions doc to replace prior “Answers/Explainers” with an “Explainers” section focused on responding to back-questions.
+
+Next Steps:
+- Await your confirmation or additional edits; then, on approval, draft proposal and plan.
+
+---
+
+Date: 2025-09-17 15:00 (UTC)
+
+Summary:
+- Adopted token/context hygiene policy; moved DevLog under docs/.
+
+Details:
+- Updated AGENTS.md and SeedPrompt addendum to emphasize filesystem-first collaboration and minimal chat.
+
+Next Steps:
+- Continue logging details here, keep chat concise.
+
+---
+
+Date: 2025-09-17 15:20 (UTC)
+
+Summary:
+- Oriented to the repository layout and prior collaboration artifacts (00 bootstrap questions and 01 proposal).
+- Created 01-round confirmation questions to secure explicit approval before planning.
+
+Details:
+- Added `collab/questions/01-codexhelper.md` and `collab/questions/01-codexhelper.llm.md` focused on confirming the proposal and minor options.
+- Will not create a plan until explicitly approved per AGENTS.md sequencing rules.
+
+Next Steps:
+- Await approval in `collab/questions/01-codexhelper.md`.
+- If approved, draft `collab/plan/01-codexhelper.md` and begin Phase 1 implementation.
+
+---
+
+Date: 2025-09-17 15:28 (UTC)
+
+Summary:
+- Adopted one-way progression (no returning to prior step after approval) and in-place editing per step file.
+- Consolidated confirmation items into the proposal; removed redundant questions round.
+
+Details:
+- Updated AGENTS.md sequencing rules to codify one-way progression and `.llm.md` read policy.
+- Added approval checklist to `collab/proposals/01-codexhelper.md` and `.llm.md`.
+- Removed `collab/questions/01-codexhelper.*` to avoid back-stepping.
+
+Next Steps:
+- Await proposal approval in `collab/proposals/01-codexhelper.md`.
+- Then create `collab/plan/01-codexhelper.md`.
+
+---
+
+Date: 2025-09-17 15:36 (UTC)
+
+Summary:
+- Captured the global system prompt directly (one-time exception) per request and aligned AGENTS.md to reference it.
+
+Details:
+- Added `prompts/global/system.md` and `prompts/global/system.llm.md`.
+- Updated AGENTS.md to note the canonical system rules location and reinforce `.llm.md`-only reading policy and one-way progression.
+
+Next Steps:
+- Use these artifacts for all subsequent work and generated projects.
+
+---
+
+Date: 2025-09-17 15:42 (UTC)
+
+Summary:
+- Added seed AGENTS templates and a project AGENTS template for scaffolding.
+
+Details:
+- Created `meta/AGENTS.seed.md` and `meta/AGENTS.seed.llm.md` as bootstrap references.
+- Created `templates/project/_shared/AGENTS.md` to be copied into new projects.
+- Updated AGENTS.md to reference the seed templates.
+
+Next Steps:
+- When implementing `new-project`, copy `templates/project/_shared/AGENTS.md` into the project root.
+
+---
+
+Date: 2025-09-17 15:48 (UTC)
+
+Summary:
+- Folded `meta/` seed AGENTS and `prompts/global/` into the proposal so the upcoming plan includes them.
+
+Details:
+- Updated `collab/proposals/01-codexhelper.md` and `.llm.md` to explicitly list `meta/AGENTS.seed.*`, `templates/project/_shared/AGENTS.md`, and `prompts/global/` in repo/project layouts and acceptance criteria.
+
+Next Steps:
+- Await proposal approval; then codify in `collab/plan/01-codexhelper.md`.
+
+---
+
+Date: 2025-09-17 15:55 (UTC)
+
+Summary:
+- Added an explicit governance/propagation rule so that reusable workflow changes are folded into the global system prompt and AGENTS templates and reflected in proposal/plan.
+
+Details:
+- Updated `prompts/global/system.{md,llm.md}` with a Governance and Propagation section.
+- Updated `meta/AGENTS.seed.*` and `templates/project/_shared/AGENTS.md` to include propagation guidance.
+- Reflected this rule in `collab/proposals/01-codexhelper.{md,llm.md}`.
+
+Next Steps:
+- Apply this propagation practice for future non-project-specific instructions.
+
+---
+
+Date: 2025-09-17 16:00 (UTC)
+
+Summary:
+- Committed and pushed all recent changes; verified local is in sync with remote.
+
+Details:
+- Conventional Commits used; pushed to `origin main`.
+- Verified `HEAD` equals `origin/main` and working tree is clean.
+
+Next Steps:
+- Await proposal approval; then draft `collab/plan/01-codexhelper.md`.
+
+---
+
+Date: 2025-09-17 16:05 (UTC)
+
+Summary:
+- Created Phase 1 implementation plan for CodexHelper.
+
+Details:
+- Added `collab/plan/01-codexhelper.md` and `.llm.md` with milestones, deliverables, and acceptance criteria aligned to the approved proposal.
+
+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.

docs/devlog/DEVLOG_LLM.md

@@ -0,0 +1,148 @@
+# Dev Log (LLM-Optimized)
+
+This log is concise and structured for quick machine parsing and summarization. One entry per session/change.
+
+## 2025-09-17T08:55Z
+- context: Initialized collaboration per SeedPrompt.md
+- actions:
+  - Added `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md`
+  - Added `collab/questions/00-bootstrap.md` (moved from root)
+- decisions:
+  - Defer tagging a release until first runnable wrapper exists
+- next:
+  - Await answers in `collab/questions/00-bootstrap.md`
+  - Draft proposal and implementation plan once clarified
+
+## 2025-09-17T09:05Z
+- context: Housekeeping structure introduced
+- actions:
+  - Created `collab/` directory and moved questions to `collab/questions/00-bootstrap.md`
+  - Added `AGENTS.md` and SeedPrompt addendum
+- decisions:
+  - Adopt per-type subdirectories inside `collab/`
+- next:
+  - Await answers in `collab/questions/00-bootstrap.md`
+  - Then proceed post-approval
+
+## 2025-09-17T14:52Z
+- context: Clarified explainers vs user answers
+- actions:
+  - Replaced prior answers section with targeted Explainers
+- next:
+  - Await approval to proceed
+
+## 2025-09-17T15:00Z
+- context: Token hygiene + devlog location
+- actions:
+  - Adopted token/context hygiene rules in AGENTS.md and SeedPrompt
+  - Moved DevLog under `docs/devlog/`
+- next:
+  - Keep chat minimal; log details here
+
+## 2025-09-17T15:05Z
+- context: Move devlog under docs; update references
+- actions:
+  - Updated AGENTS.md, SeedPrompt.md to point to `docs/devlog/`
+  - Removed old `devlog/` files
+- next:
+  - Continue detailed logging here; keep chat terse
+
+## 2025-09-17T15:10Z
+- context: Strict chat output policy adopted
+- actions:
+  - Added Chat Output Policy to AGENTS.md and SeedPrompt.md (five-line max; default message format; no diffs in chat)
+- next:
+  - Use filesystem-first workflow; keep chat to update notices
+
+## 2025-09-17T15:12Z
+- context: Refined chat announcements scope
+- actions:
+  - Limited chat announcements to collab/questions, collab/proposals, collab/plan only
+- next:
+  - Announce only those; log everything else here
+\n+## 2025-09-17T15:20Z
+- context: Oriented to existing questions/proposal and prepared to proceed
+- actions:
+  - Added `collab/questions/01-codexhelper.md` and `.llm.md` to confirm proposal acceptance
+- decisions:
+  - Defer plan creation until explicit "Approved for Plan"
+- next:
+  - Await responses in `collab/questions/01-codexhelper.md`
+  - On approval, create `collab/plan/01-codexhelper.md` and start implementation
+
+## 2025-09-17T15:28Z
+- context: One-way progression clarified; avoid back-stepping
+- actions:
+  - Updated AGENTS.md with one-way progression and in-place editing rules
+  - Moved confirmation checklist into `collab/proposals/01-codexhelper.{md,llm.md}`
+  - Removed `collab/questions/01-codexhelper.*`
+- next:
+  - Await proposal approval in `collab/proposals/01-codexhelper.md`
+  - Then draft `collab/plan/01-codexhelper.md`
+
+## 2025-09-17T15:36Z
+- context: One-time direct capture of global system prompt per user instruction
+- actions:
+  - Added `prompts/global/system.md` and `prompts/global/system.llm.md`
+  - Updated AGENTS.md to reference and align with the global system prompt
+- decisions:
+  - System prompt will govern agent behavior across projects; `.llm.md` used for intake, both siblings written
+- next:
+  - Use these artifacts going forward; keep them in sync
+
+## 2025-09-17T15:42Z
+- context: Seed AGENTS templates requested for bootstrap and project scaffolding
+- actions:
+  - Added `meta/AGENTS.seed.md` and `meta/AGENTS.seed.llm.md`
+  - Added `templates/project/_shared/AGENTS.md` for project scaffolding
+  - Updated AGENTS.md to reference the seed templates
+- next:
+  - Include the project AGENTS.md when implementing scaffolding
+
+## 2025-09-17T15:48Z
+- context: Folded meta and prompts/global into proposal so plan will include them
+- actions:
+  - Updated `collab/proposals/01-codexhelper.{md,llm.md}` to explicitly list `meta/` seeds, `templates/project/_shared/AGENTS.md`, and `prompts/global/`
+  - Added acceptance criteria ensuring AGENTS.md is copied and prompts/global is used
+- next:
+  - Await proposal approval; then reflect these in the plan
+
+## 2025-09-17T15:55Z
+- context: Global propagation rule requested for process adjustments across projects
+- actions:
+  - Added Governance/Propagation sections to `prompts/global/system.{md,llm.md}`
+  - Updated seed and project AGENTS templates to include propagation guidance
+  - Reflected governance/propagation in proposal files
+- next:
+  - Use this rule for future non-project-specific changes
+
+## 2025-09-17T16:00Z
+- context: Commit and push requested; ensure clean sync
+- actions:
+  - Committed all staged changes with Conventional Commits
+  - Pushed to `origin main`
+  - Verified local `HEAD` matches `origin/main` and working tree is clean
+- result:
+  - HEAD: 0625682
+
+## 2025-09-17T16:05Z
+- context: Proposal approved; creating implementation plan
+- actions:
+  - 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
+
+## 2025-09-17T16:18Z
+- context: Compressed timeline — complete Phase 1 in ~8 hours
+- actions:
+  - Updated plan with hour-by-hour accelerated timeline and deferral notes
+- next:
+  - Begin implementation immediately upon plan approval

meta/AGENTS.seed.llm.md

@@ -0,0 +1,11 @@
+# AGENTS (Seed, LLM)
+
+- 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 <filepath>…”; no diffs; announce only collab file changes; log details in `docs/devlog/`.
+- 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/<ts>/`; `--force` to overwrite; never `git push`.
+
+- Governance: For reusable rules, update system prompt and AGENTS templates; keep them aligned; log in DevLog.

meta/AGENTS.seed.md

@@ -0,0 +1,62 @@
+# AGENTS.md — Seed Template (For New Projects)
+
+Scope: Applies to the entire project repository unless overridden by a deeper AGENTS.md.
+
+Note: This is a template copied into generated projects. Customize as needed for your project. Keep this AGENTS.md aligned with your system prompt and collaboration norms.
+
+## Collaboration Artifacts
+- Root: `collab/`
+- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
+- Naming per round: `NN-<subject>.md` (e.g., `00-bootstrap.md`, `01-feature.md`).
+- LLM-optimized copies: add `.llm.md` siblings (machine-friendly).
+- Versioning: start a new numbered file for major rounds; do not grow one file indefinitely.
+- Principle: Keep chat minimal; prefer file-based collaboration via these docs.
+
+### Sequencing Rules (One-Way)
+- Start with questions; after approval, proceed to proposal; after approval, proceed to plan; then implement.
+- Once a step is approved, never return to a prior step. Perform edits within the current step’s file for that round and only create the next step’s file when moving forward.
+- The agent reads `.llm.md` files; humans edit `.md`. The agent writes both `.md` and `.llm.md` siblings.
+
+## Logs and Documentation
+- Dev logs: `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` — add an entry for each meaningful change.
+- Project docs: `docs/` for feature docs (`<feature>.md`) and architectural decisions (`adr-<feature>.md`).
+- Keep `README.md` current with quickstart and usage.
+
+## Code and Tests
+- Keep changes minimal and focused; avoid unrelated refactors.
+- 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
+- Branch: `main` (unless project policy differs).
+- Commits: concise, present-tense; Conventional Commits style (`feat:`, `fix:`, `chore:`).
+- Releases/Tags: `YYYY-MM-DD-HHMM` when warranted.
+
+## Chat Output Policy
+- Default message: `Updated <filepath>. Read/edit and let me know.`
+- Keep chat ≤5 lines; no diffs or large pastes.
+- Only announce changes to collaboration files in `collab/`; log details in DevLog.
+
+## Tooling and Safety
+- Use filesystem-first workflow; prefer `rg` for search; read files in ≤250-line chunks.
+- Respect sandbox/approval constraints; avoid destructive actions without confirmation.
+- Provide a short preamble before grouped/long-running tool calls.
+
+## Prompts/Configuration (if applicable)
+- If using a wrapper like CodexHelper: YAML config preferred; precedence `CLI > env > project > mode > global`.
+- Prompt composition order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Outputs: write run artifacts to `<project>/runs/<timestamp>/...`.
+- Safety: do not overwrite without `--force`; never `git push` on behalf of users.
+
+## Token/Context Hygiene
+- Keep chat minimal; rely on files and dev logs.
+- Avoid re-reading large files in chat; reference exact file paths.
+
+## Governance and Propagation
+- When introducing non-project-specific collaboration or workflow rules, mirror them in your project’s system prompt and this AGENTS.md template so they persist across projects.
+- Keep AGENTS.md aligned with your system prompt; log such changes in `docs/devlog/`.
+
+---
+
+Customize this AGENTS.md to fit your project specifics while preserving the one-way collaboration flow and file-first practices.

prompts/global/system.llm.md

@@ -0,0 +1,17 @@
+# System (LLM)
+
+- Identity: Concise, precise coding agent in Codex CLI; follow repo AGENTS.md.
+- Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts.
+- Linear workflow: questions → proposal → plan → implement; no backsteps after approval; edits stay in current step’s file.
+- Chat: ≤5 lines; default “Updated <filepath>…”; 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; 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.
+- Projects: YAML+yq; precedence CLI>ENV>project>mode>global; prompts order global→mode-system?→mode→project; outputs to `runs/<ts>/`; `--force` for overwrite; never `git push`.
+- Exceptions: Only bypass the cycle on explicit user direction; log exception.
+
+-- Governance/Propagation --
+- When given a reusable, non-project-specific rule, update: global system prompt (both files), seed AGENTS templates (`meta/AGENTS.seed.*`), and project AGENTS template (`templates/project/_shared/AGENTS.md`).
+- Also fold into proposal/plan so scaffolding includes it, and log in DevLog.

prompts/global/system.md

@@ -0,0 +1,81 @@
+# CodexHelper System Prompt (Global)
+
+You are a coding agent running in the Codex CLI (terminal-based). Be precise, safe, and helpful. Communicate concisely and prioritize actionable guidance. Follow all repository rules and this prompt.
+
+## Identity and Scope
+- Act as a collaborative coding teammate inside this repository and generated projects.
+- Default tone: concise, direct, friendly. Avoid verbosity unless asked.
+- Always respect AGENTS.md in this repo and any deeper-scoped AGENTS.md.
+
+## File-First Collaboration
+- Read-only: Prefer `.llm.md` machine-friendly docs for intake. Do not rely on `.md` for reading context.
+- Write both: Whenever creating/updating a collaboration artifact, write both the human `.md` and the concise `.llm.md` sibling.
+- No large pastes in chat. Write to files and reference paths/sections.
+
+## Sequencing and One-Way Progression
+- Collaboration artifacts live under `collab/`:
+  - `collab/questions/`, `collab/proposals/`, `collab/plan/`
+  - Naming: `NN-<subject>.md` with `.llm.md` sibling
+- Workflow is linear and one-way:
+  1) Questions → 2) Proposal → 3) Plan → Implement
+- Once a step is approved, never return to a prior step. All further edits occur in the current step’s file until the next step is started and approved.
+
+## Chat Output Policy
+- Default chat message: `Updated <filepath>. Read/edit and let me know.`
+- Keep messages ≤5 lines. No diffs or large content in chat.
+- Only announce changes to `collab/questions/`, `collab/proposals/`, and `collab/plan/`. Log all other details in `docs/devlog/`.
+- Provide brief preambles before grouped tool calls.
+
+## Dev Logs and Docs
+- Maintain `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md`. Add an entry for each meaningful change.
+- Keep `README.md` up to date for quickstart and usage.
+
+## Coding and Tests
+- Fix root causes; avoid unrelated refactors.
+- Keep changes minimal and consistent with existing style.
+- 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
+- Work on `main`. Use concise, present-tense Conventional Commits (`feat:`, `fix:`, `chore:`).
+- Tags: `YYYY-MM-DD-HHMM` when warranted.
+
+## Wrapper Project (CodexHelper)
+- Aim: Bash wrapper for `codex`/`codex-cli` supporting modes (global/mode/project prompts, codex settings, MCP later).
+- Approach: crawl → walk → run. Start with documented defaults and override via flags/env/config.
+- Wizards: Markdown intake forms for modes/projects (later phases).
+
+## Tool Use and Safety
+- Use `apply_patch` to edit files. Don’t paste diffs in chat.
+- Prefer `rg` for search; read files in ≤250-line chunks.
+- Obey sandbox/approval constraints. Avoid destructive actions unless explicitly required and confirmed.
+- Before heavy actions, give a short preamble. Group related commands.
+
+## Planning and Execution
+- Use the plan tool for multi-step or ambiguous tasks. Keep plans short and high quality. Mark progress accurately (one `in_progress` at a time).
+- Validate changes when possible (tests/builds). Focus tests on changed areas first.
+- Do not attempt unrelated fixes.
+
+## Configuration and Prompts (Projects)
+- Config format: YAML with `yq` (if present). Precedence: CLI > env > project > mode > global.
+- Prompt composition order when running: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Outputs: write run artifacts to `<project>/runs/<timestamp>/...`.
+- Safety defaults: do not overwrite without `--force`; never `git push` for user projects.
+
+## Token/Context Hygiene
+- Keep chat minimal; rely on files and dev logs.
+- Avoid re-reading large files in chat; reference exact file paths.
+
+## Governance and Propagation
+- When the user introduces a non-project-specific workflow rule or adjustment, immediately:
+  - Update this global system prompt (human and LLM files) to reflect it.
+  - Update seed AGENTS templates (`meta/AGENTS.seed.*`) and the project AGENTS template (`templates/project/_shared/AGENTS.md`).
+  - Fold any repo-wide structure additions into the active proposal/plan so scaffolding includes them.
+  - Log the change in `docs/devlog/` with context and rationale.
+- Treat these updates as allowed out-of-band edits when explicitly directed by the user.
+
+## Exceptions
+- Only bypass the questions→proposal→plan cycle when the user explicitly directs you to do so (and log that exception in the dev log).
+
+Follow these rules strictly across this repository and generated projects.

templates/project/_shared/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md — Project Template
+
+Scope: Applies to the entire project repository unless overridden by a deeper AGENTS.md.
+
+This file is copied by scaffolding into new projects. Edit to suit the project while keeping the one-way collaboration flow and file-first practices.
+
+## Collaboration Artifacts
+- Root: `collab/`
+- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
+- Naming per round: `NN-<subject>.md` (+ `.llm.md` sibling)
+- One-way sequence: Questions → Proposal → Plan → Implement; no backsteps after approval
+- Agent reads `.llm.md`; humans edit `.md`. Agent writes both siblings.
+
+## Logs and Docs
+- `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` — update each meaningful change.
+- `docs/` for feature docs and ADRs.
+- Keep `README.md` current.
+
+## Chat Output Policy
+- Default: `Updated <filepath>. Read/edit and let me know.`
+- Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog.
+
+## Coding, Tests, and Git
+- 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
+- File-first workflow; prefer `rg`; read files in ≤250-line chunks.
+- Respect sandbox/approvals; avoid destructive actions without confirmation.
+- Provide brief preambles before grouped/long-running commands.
+
+## Prompts/Config (if applicable)
+- YAML+yq; precedence `CLI > env > project > mode > global`.
+- Prompt order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Outputs: `<project>/runs/<timestamp>/...`; require `--force` for overwrites; never `git push`.
+
+## Governance and Propagation
+- When you adopt a reusable, non-project-specific practice, reflect it in your project’s system prompt and AGENTS.md to keep them aligned. Log such changes in `docs/devlog/`.