ChatGPTScaffolding/collab/questions/00-bootstrap.md

# 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