plan: add Phase 1 implementation plan for CodexHelper (milestones, deliverables, acceptance criteria)
This commit is contained in:
48
collab/plan/01-codexhelper.llm.md
Normal file
48
collab/plan/01-codexhelper.llm.md
Normal file
@@ -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.
|
||||||
|
|
||||||
65
collab/plan/01-codexhelper.md
Normal file
65
collab/plan/01-codexhelper.md
Normal file
@@ -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
|
||||||
|
|
||||||
@@ -143,3 +143,30 @@ Details:
|
|||||||
|
|
||||||
Next Steps:
|
Next Steps:
|
||||||
- Apply this propagation practice for future non-project-specific instructions.
|
- 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.
|
||||||
|
|||||||
@@ -115,3 +115,19 @@ This log is concise and structured for quick machine parsing and summarization.
|
|||||||
- Reflected governance/propagation in proposal files
|
- Reflected governance/propagation in proposal files
|
||||||
- next:
|
- next:
|
||||||
- Use this rule for future non-project-specific changes
|
- 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
|
||||||
|
|||||||
Reference in New Issue
Block a user