From f91f3814e8fade8d04fc25d7e56be1b2ba965f94 Mon Sep 17 00:00:00 2001
From: ReachableCEO <charles@turnsys.com>
Date: Wed, 17 Sep 2025 09:54:16 -0500
Subject: [PATCH] docs: adopt per-round files + LLM counterparts; add llm
 versions for 00-bootstrap and 01-codexhelper; update AGENTS and SeedPrompt

---
 AGENTS.md                              |  5 +++--
 SeedPrompt.md                          |  6 ++++++
 collab/proposals/01-codexhelper.llm.md | 20 ++++++++++++++++++++
 collab/questions/00-bootstrap.llm.md   | 21 +++++++++++++++++++++
 4 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 collab/proposals/01-codexhelper.llm.md
 create mode 100644 collab/questions/00-bootstrap.llm.md

diff --git a/AGENTS.md b/AGENTS.md
index 0a0e260..e329431 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,8 +5,9 @@ Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.
 ## Collaboration Artifacts
 - Root: `collab/`
 - Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
-- Naming: `<step-or-subject>.md` inside each subdirectory
-  - Examples: `collab/questions/00-bootstrap.md`, `collab/proposals/01-wrapper.md`, `collab/plan/01-wrapper.md`
+- Naming per round: `NN-<subject>.md` inside each subdirectory (e.g., `00-bootstrap.md`, `01-codexhelper.md`).
+- LLM-optimized copies: add `.llm.md` sibling files (e.g., `01-codexhelper.llm.md`) that are concise and machine-friendly.
+- Versioning: start a new numbered file for major rounds rather than expanding one doc indefinitely.
 - Principle: Keep chat minimal; prefer file-based collaboration via these documents.
 
 ### Sequencing Rules
diff --git a/SeedPrompt.md b/SeedPrompt.md
index 7176075..f017c7c 100644
--- a/SeedPrompt.md
+++ b/SeedPrompt.md
@@ -55,3 +55,9 @@ Commit/push everything in the repo now before we get started on the project.
 
 - Start with questions in `collab/questions/` and keep iterating/adding questions until satisfied or instructed to move on.
 - Do not create proposals or plans until the questions file has been edited by the user and the user gives explicit approval.
+
+### Files Per Round + LLM Copies
+
+- Use multiple files per round rather than growing a single document.
+- Naming: `collab/<type>/NN-<subject>.md` (human) and `collab/<type>/NN-<subject>.llm.md` (LLM-optimized).
+- Start a new `NN` for each major round; keep subject consistent across types.
diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md
new file mode 100644
index 0000000..1b1f988
--- /dev/null
+++ b/collab/proposals/01-codexhelper.llm.md
@@ -0,0 +1,20 @@
+# 01 — CodexHelper — Proposal (LLM)
+
+- Tool: `CodexHelper` bash wrapper for codex-cli.
+- CLI (subcommands):
+  - new-project: scaffold project files
+  - run: compose prompts + call codex
+  - new-mode: scaffold mode (repo-only)
+- Where to run: repo → only new-mode; elsewhere → new-project, run.
+- Prompts order: global system → mode system overlay (optional) → mode rules → project narrative.
+- Config: YAML + yq; precedence CLI > env > project > mode > global.
+- Binary: detect `codex` then `codex-cli`; override `CODEX_BIN`.
+- Safety: no overwrites without `--force`; never `git push` for user projects.
+- Outputs: `<project>/runs/<ts>/...`.
+- Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/system.md`, `modes/<Name>/{mode.md,system.md?,defaults.yaml}`, `templates/project/<Name>/...`.
+- Layout (project): `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`.
+- Phase 1 acceptance:
+  - new-mode creates mode skeleton
+  - new-project scaffolds without overwrites
+  - run composes and calls detected codex; writes under runs/
+  - precedence respected; running in repo errors for run/new-project
diff --git a/collab/questions/00-bootstrap.llm.md b/collab/questions/00-bootstrap.llm.md
new file mode 100644
index 0000000..e6046ce
--- /dev/null
+++ b/collab/questions/00-bootstrap.llm.md
@@ -0,0 +1,21 @@
+# 00 — Bootstrap — Questions (LLM)
+
+- Remote: origin main; push enabled.
+- Tagging: local time `YYYY-MM-DD-HHMM`.
+- Commits: Conventional Commits.
+- Codex binary: detect `codex` then `codex-cli`; allow `CODEX_BIN` override.
+- Invocation defaults: user currently uses `codex --sandbox workspace-write --full-auto`; make these configurable.
+- Defaults: accept codex-cli defaults for model/token/reasoning unless overridden.
+- Precedence: CLI > env > project > mode > global.
+- Config files: project-contained; no user home dotfiles.
+- Prompts storage: in this repo — global system + mode rules (and optional mode system overlay). Projects elsewhere.
+- Projects: not inside this repo; wrapper used from external project directories.
+- MCP: mix of per-mode defaults + per-project; defer implementation (track in `docs/ROADMAP.md`).
+- Wizards: basic for now (mode: name/desc/defaults/prompts/MCP; project: name/path/prompt/default mode/overrides).
+- CLI UX: prefer subcommands; inside this repo allow only `new-mode`; outside support `new-project` and `run`.
+- Outputs: write to `<project>/runs/<timestamp>/...`.
+- Safety: never overwrite without `--force`; never run `git push` for user projects.
+- Licensing: repo AGPLv3; user artifacts are user-licensed.
+- OS/Deps: Ubuntu/Debian; bash, git, yq.
+- Install: use `CodexHelper` from PATH; provide optional `bin/install.sh` to symlink.
+- Copy prompts: on project scaffold, copy global/mode prompts into `prompts/_mode/` in project (read-only annotated) and compose: global → mode overlay → mode rules → project narrative.