From 385945975461a9506569b7d095fc559e38ce83c0 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 10:24:04 -0500 Subject: [PATCH] plan: add Phase 1 implementation plan for CodexHelper (milestones, deliverables, acceptance criteria) --- collab/plan/01-codexhelper.llm.md | 48 +++++++++++++++++++++++ collab/plan/01-codexhelper.md | 65 +++++++++++++++++++++++++++++++ docs/devlog/DEVLOG_HUMAN.md | 27 +++++++++++++ docs/devlog/DEVLOG_LLM.md | 16 ++++++++ 4 files changed, 156 insertions(+) create mode 100644 collab/plan/01-codexhelper.llm.md create mode 100644 collab/plan/01-codexhelper.md diff --git a/collab/plan/01-codexhelper.llm.md b/collab/plan/01-codexhelper.llm.md new file mode 100644 index 0000000..03b59a2 --- /dev/null +++ b/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 `/runs//`. + +- Deliverables: + - `CodexHelper` bash script + - `prompts/global/{system.md,system.llm.md}` (already present) + - `templates/project/_shared/AGENTS.md` (copy into project root) + - `templates/project//...` (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//{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//`. + - 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//`. + - 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. + diff --git a/collab/plan/01-codexhelper.md b/collab/plan/01-codexhelper.md new file mode 100644 index 0000000..5a494a2 --- /dev/null +++ b/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//{mode.md,defaults.yaml,system.md?}` with intake comments. +- Refuse to overwrite unless `--force`. + +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/`) + +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`. + +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 `/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. + +## 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//...`. +- 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 + diff --git a/docs/devlog/DEVLOG_HUMAN.md b/docs/devlog/DEVLOG_HUMAN.md index 3a9d7dd..50da713 100644 --- a/docs/devlog/DEVLOG_HUMAN.md +++ b/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. diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 2a1d230..5c361c2 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/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