plan: add Phase 1 implementation plan for CodexHelper (milestones, deliverables, acceptance criteria)

collab/plan/01-codexhelper.llm.md

@@ -0,0 +1,48 @@
+# 01 — CodexHelper — Implementation Plan (LLM)
+
+- 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
+
+- 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
+
+- 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.
+
+- 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/`).
+
+- Next: Implement per milestones; add concise README quickstart.
+

collab/plan/01-codexhelper.md

@@ -0,0 +1,65 @@
+# 01 — CodexHelper — Implementation Plan
+
+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`.
+
+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.
+
+3) new-mode (repo-only)
+- Create `modes/<Name>/{mode.md,defaults.yaml,system.md?}` with intake comments.
+- Refuse to overwrite unless `--force`.
+
+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/`)
+
+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`.
+
+6) Config precedence (YAML + yq)
+- Load `codex.yaml`; merge with mode defaults and global defaults.
+- Apply ENV overrides; apply CLI overrides last.
+
+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.
+
+## 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.
+
+## 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.
+
+## Timeline (targeted)
+- Day 1: Milestones 1–3
+- Day 2: Milestones 4–5
+- Day 3: Milestone 6 + Docs
+

docs/devlog/DEVLOG_HUMAN.md

@@ -143,3 +143,30 @@ Details:
 
 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.

docs/devlog/DEVLOG_LLM.md

@@ -115,3 +115,19 @@ This log is concise and structured for quick machine parsing and summarization.
   - 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