diff --git a/collab/questions/00-bootstrap.md b/collab/questions/00-bootstrap.md index aa368d2..096379e 100644 --- a/collab/questions/00-bootstrap.md +++ b/collab/questions/00-bootstrap.md @@ -168,8 +168,13 @@ No ### 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` @@ -178,18 +183,65 @@ No - 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//system.md` (optional overlay), `modes//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 + +## Answers/Explainers 2025-17-09-14:46 + +- Name & install: + - Use `CodexHelper` as the entrypoint script. No system install; user adds repo script to PATH. Provide optional `bin/install.sh` to symlink into `~/bin`. +- Binary discovery: + - Resolve with `which codex` then `which codex-cli`; allow `CODEX_BIN` to override. If missing, print guidance; no auto-install. +- CLI UX: + - Subcommands provide clearer UX and self-documentation; we recommend: `CodexHelper new-project`, `CodexHelper new-mode`, `CodexHelper run`. We can later add flag-only aliases if desired. +- Where to run: + - Outside this repo: support `new-project` and `run` for user projects. Inside this repo: only `new-mode` (to scaffold a mode via markdown intake). +- Project scaffolding contents: + - Generate in project: `prompts/project.md` (narrative), optional `prompts/style.md` (coding/style notes), `codex.yaml` (mode/config/MCP placeholders), `codex.sh` (entrypoint wrapper). Create `runs/` on first run and add to `.gitignore`. + - Copy mode/system prompts into project under `prompts/_mode/` as read-only copies (cannot enforce, but mark with header comment). `codex.sh` will compose prompts in order. +- Prompt composition: + - Stack: Global system rules → Mode rules → Project narrative. The optional mode-specific system overlay is an extra system-level rules file for a mode when it needs to extend or tweak the global system rules. + - Locations: `prompts/global/system.md` (repo-wide), `modes//system.md` (optional overlay), `modes//mode.md` (mode rules), project `prompts/project.md`. +- Config/tooling: + - Use YAML with `yq`. Precedence: CLI > env > project > mode > global defaults. Pass through sandbox/full-auto flags to codex. +- Safety & outputs: + - Never overwrite without `--force`. Never run `git push` for user projects. Write runs to `/runs//...`. Prevent `run` inside this repo except for `new-mode`. +- Licensing: + - Repo (wrapper, modes, prompts) under AGPLv3. User project artifacts (prompts/code generated) are user-licensed; we will not inject a LICENSE into projects. +- OS target: + - Ubuntu 22.04/Debian 12+ with bash/zsh. Dependencies: bash, git, yq. + 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 `/runs//...` (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