feat: add global system prompt and seed AGENTS templates; update proposal to include meta/ and prompts/global/; add project AGENTS template\n\nchore: update AGENTS.md and dev logs; encode governance/propagation rule

2025-09-17 10:20:49 -05:00
parent ce0a8b32ec
commit 0625682e63
10 changed files with 410 additions and 4 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,8 @@

 Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.

+Note: The canonical system rules used by the agent are mirrored in `prompts/global/system.md` (human) and `prompts/global/system.llm.md` (LLM). Keep AGENTS.md and the system prompt aligned. A seed AGENTS template for generated projects lives at `meta/AGENTS.seed.md` (and `.llm.md`).
+
 ## Collaboration Artifacts
 - Root: `collab/`
 - Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
@@ -14,6 +16,11 @@ Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.
 - Begin with a questions file in `collab/questions/` and iterate there until the agent is satisfied or the user instructs to proceed.
 - Do not create a proposal or plan until the questions have been edited by the user and explicitly approved.
 - After approval, create a concise proposal in `collab/proposals/` and a concrete plan in `collab/plan/`, then implement.
+- One-way progression: once a step (questions → proposal → plan) is approved, do not return to a prior step. Perform any subsequent clarifications/edits within the current step’s file for that round (e.g., continue editing `collab/proposals/NN-*.md` after proposal approval) and only create the next step’s file when moving forward.
+- Artifact edits live in-place: Users/humans will edit the non-LLM `.md` files; the agent reads `.llm.md` and writes both `.md` and `.llm.md` siblings for every collaboration artifact.
+
+### One-Time Exceptions
+- Only bypass the Questions→Proposal→Plan cycle when explicitly directed by the user; log such exceptions in `docs/devlog/`.

 ## Logs and Documentation
 - Dev logs: `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` updated each meaningful change.
@@ -42,6 +49,7 @@ Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.
 ## Token/Context Hygiene
 - Chat minimalism: keep messages short; prefer pointers to files over inline dumps.
 - Use `.llm.md` files for concise, machine-friendly summaries; avoid duplicating full human docs.
+- Read `.llm.md` for intake; do not rely on `.md` for reading. Write both `.md` and `.llm.md` when updating artifacts.
 - No large pastes in chat: never paste large code or markdown; write to files and reference paths/sections.
 - Incremental artifacts: start a new `NN-<subject>.md` per round to avoid long single files.
 - Status style: one-line updates before tool calls; rely on devlog for detail.
--- a/collab/proposals/01-codexhelper.llm.md
+++ b/collab/proposals/01-codexhelper.llm.md
@@ -11,10 +11,31 @@
 - 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/`.
+- Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/{system.md,system.llm.md}`, `modes/<Name>/{mode.md,system.md?,defaults.yaml}`, `templates/project/<Name>/...`, `templates/project/_shared/AGENTS.md`, `meta/{AGENTS.seed.md,AGENTS.seed.llm.md}`.
+- Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`.
+ - Governance/Propagation: non-project-specific workflow changes get recorded in `prompts/global/` and seed AGENTS templates; proposal/plan updated so scaffolding includes them.
 - 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
+  - new-project copies `templates/project/_shared/AGENTS.md` into project root as `AGENTS.md`
+  - prompts/global present and used in prompt composition
+  - governance rule: changes to global norms propagate to prompts/global and AGENTS templates; logged in DevLog
+\n+## Approval — Tick All That Apply
+
+- Subcommands approved: `new-project`, `run`, `new-mode` [ ]
+- Scope approved: repo→`new-mode` only; outside→`new-project`/`run` [ ]
+- Prompts order approved: global→mode-system?→mode→project [ ]
+- Config+precedence approved: YAML+yq; CLI>ENV>project>mode>global [ ]
+- Safety approved: `--force` to overwrite; no `git push`; outputs to `<project>/runs/<ts>/...` [ ]
+- Repo layout approved (modes, templates, global prompts) [ ]
+- Project layout approved (prompts, `_mode/`, codex.yaml, codex.sh, .gitignore) [ ]
+- Include empty `prompts/style.md` by default [ ]
+- Binary discovery: `codex`→`codex-cli`; override `CODEX_BIN` [ ]
+- Pass-through flags: `--mode --prompt-file --config --sandbox --full-auto` [ ]
+- Block `run`/`new-project` inside repo with helpful error [ ]
+- Phase 1 (Crawl) scope acceptable [ ]
+- Add `docs/ROADMAP.md`; MCP deferred [ ]
+
+Final: Reply in the human doc with “Approved for Plan” when all are checked.
--- a/collab/proposals/01-codexhelper.md
+++ b/collab/proposals/01-codexhelper.md
@@ -31,13 +31,17 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 ## Repository Layout (this repo)
 - `CodexHelper` (bash)
 - `bin/install.sh` (optional symlink helper)
- `prompts/global/system.md` (global system rules)
+- `prompts/global/{system.md, system.llm.md}` (global system rules; human + LLM)
 - `modes/<ModeName>/mode.md` (mode rules)
 - `modes/<ModeName>/system.md` (optional mode-specific system overlay)
 - `modes/<ModeName>/defaults.yaml` (default codex settings, optional MCP placeholders)
 - `templates/project/<ModeName>/...` (project scaffolding templates copied on `new-project`)
+- `templates/project/_shared/AGENTS.md` (AGENTS template copied into projects)
+- `meta/{AGENTS.seed.md, AGENTS.seed.llm.md}` (seed AGENTS templates for bootstrap/reference)
+ - Governance/Propagation: maintain global norms in `prompts/global/` and seed AGENTS templates; reflect such changes in proposal/plan for scaffolding.

 ## Project Layout (generated)
+- `AGENTS.md` (from `templates/project/_shared/AGENTS.md`)
 - `prompts/project.md` (+ optional `prompts/style.md`)
 - `prompts/_mode/` (read-only copies from this repo)
 - `codex.yaml` (project config)
@@ -55,7 +59,9 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes

 ## Prompt Composition
 - Order: Global system → Mode system overlay (if any) → Mode rules → Project narrative.
- Implementation: `codex.sh` concatenates/feeds prompts to `codex` in that order (exact mechanism depends on codex-cli interface; we’ll use files/flags as supported).
+ - Implementation: `codex.sh` concatenates/feeds prompts to `codex` in that order (exact mechanism depends on codex-cli interface; we’ll use files/flags as supported).
+ - Explicit: `prompts/global/` is present and used as the base of composition.
+  - Governance/Propagation: non-project-specific rules are folded back into global/system and templates; changes logged.

 ## Safety
 - Guardrails:
@@ -87,6 +93,9 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 - Inside that project, `CodexHelper run --full-auto` composes prompts and calls the detected `codex` binary. It writes artifacts under `runs/<timestamp>/...`.
 - Precedence works: CLI options override env, which override project config, which override mode defaults.
 - Running `CodexHelper run` in this repo prints an error guiding usage.
+ - Project scaffold includes `AGENTS.md` copied from `templates/project/_shared/AGENTS.md`.
+ - `prompts/global/{system.md, system.llm.md}` exist and are included in composition.
+ - Governance/Propagation honored: when norms change, update `prompts/global/` and AGENTS templates; log in DevLog.

 ## Open Items for Confirmation
 - Template coverage: include `prompts/style.md` by default? (we’ll include as optional, empty file)
@@ -95,3 +104,19 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes
 ## Next Step
 - On approval, I will create a concrete implementation plan at `collab/plan/01-codexhelper.md` and proceed with the Crawl phase implementation.

+## Approval Checklist
+Please answer inline. When all are approved, reply “Approved for Plan”.
+
+1) Subcommands: approve `new-project`, `run`, `new-mode`? Any renames?
+2) Scope: inside this repo allow only `new-mode`; outside allow `new-project` and `run`?
+3) Prompts order: global system → mode system overlay (optional) → mode rules → project narrative?
+4) Config format/precedence: YAML with `yq`; CLI > env > project > mode > global?
+5) Safety: require `--force` to overwrite; never `git push` for user projects; outputs under `<project>/runs/<timestamp>/...`?
+6) Repo layout: `CodexHelper`, `prompts/global/system.md`, `modes/<Name>/{mode.md, system.md?, defaults.yaml}`, `templates/project/<Name>/...`?
+7) Project layout: `prompts/{project.md, style.md?}`, `prompts/_mode/` (read-only copies), `codex.yaml`, `codex.sh`, `.gitignore (runs/)`?
+8) Include empty `prompts/style.md` by default?
+9) Binary discovery: try `codex` then `codex-cli`; allow override `CODEX_BIN`?
+10) Pass-through flags: `--mode`, `--prompt-file`, `--config`, `--sandbox`, `--full-auto` to underlying `codex`?
+11) Block `run` and `new-project` inside this repo with a helpful error?
+12) Phase 1 (Crawl) scope acceptable as listed?
+13) Roadmap: add `docs/ROADMAP.md`; defer MCP integration for now?
--- a/docs/devlog/DEVLOG_HUMAN.md
+++ b/docs/devlog/DEVLOG_HUMAN.md
@@ -53,3 +53,93 @@ Details:

 Next Steps:
 - Continue logging details here, keep chat concise.
+
+---
+
+Date: 2025-09-17 15:20 (UTC)
+
+Summary:
+- Oriented to the repository layout and prior collaboration artifacts (00 bootstrap questions and 01 proposal).
+- Created 01-round confirmation questions to secure explicit approval before planning.
+
+Details:
+- Added `collab/questions/01-codexhelper.md` and `collab/questions/01-codexhelper.llm.md` focused on confirming the proposal and minor options.
+- Will not create a plan until explicitly approved per AGENTS.md sequencing rules.
+
+Next Steps:
+- Await approval in `collab/questions/01-codexhelper.md`.
+- If approved, draft `collab/plan/01-codexhelper.md` and begin Phase 1 implementation.
+
+---
+
+Date: 2025-09-17 15:28 (UTC)
+
+Summary:
+- Adopted one-way progression (no returning to prior step after approval) and in-place editing per step file.
+- Consolidated confirmation items into the proposal; removed redundant questions round.
+
+Details:
+- Updated AGENTS.md sequencing rules to codify one-way progression and `.llm.md` read policy.
+- Added approval checklist to `collab/proposals/01-codexhelper.md` and `.llm.md`.
+- Removed `collab/questions/01-codexhelper.*` to avoid back-stepping.
+
+Next Steps:
+- Await proposal approval in `collab/proposals/01-codexhelper.md`.
+- Then create `collab/plan/01-codexhelper.md`.
+
+---
+
+Date: 2025-09-17 15:36 (UTC)
+
+Summary:
+- Captured the global system prompt directly (one-time exception) per request and aligned AGENTS.md to reference it.
+
+Details:
+- Added `prompts/global/system.md` and `prompts/global/system.llm.md`.
+- Updated AGENTS.md to note the canonical system rules location and reinforce `.llm.md`-only reading policy and one-way progression.
+
+Next Steps:
+- Use these artifacts for all subsequent work and generated projects.
+
+---
+
+Date: 2025-09-17 15:42 (UTC)
+
+Summary:
+- Added seed AGENTS templates and a project AGENTS template for scaffolding.
+
+Details:
+- Created `meta/AGENTS.seed.md` and `meta/AGENTS.seed.llm.md` as bootstrap references.
+- Created `templates/project/_shared/AGENTS.md` to be copied into new projects.
+- Updated AGENTS.md to reference the seed templates.
+
+Next Steps:
+- When implementing `new-project`, copy `templates/project/_shared/AGENTS.md` into the project root.
+
+---
+
+Date: 2025-09-17 15:48 (UTC)
+
+Summary:
+- Folded `meta/` seed AGENTS and `prompts/global/` into the proposal so the upcoming plan includes them.
+
+Details:
+- Updated `collab/proposals/01-codexhelper.md` and `.llm.md` to explicitly list `meta/AGENTS.seed.*`, `templates/project/_shared/AGENTS.md`, and `prompts/global/` in repo/project layouts and acceptance criteria.
+
+Next Steps:
+- Await proposal approval; then codify in `collab/plan/01-codexhelper.md`.
+
+---
+
+Date: 2025-09-17 15:55 (UTC)
+
+Summary:
+- Added an explicit governance/propagation rule so that reusable workflow changes are folded into the global system prompt and AGENTS templates and reflected in proposal/plan.
+
+Details:
+- Updated `prompts/global/system.{md,llm.md}` with a Governance and Propagation section.
+- Updated `meta/AGENTS.seed.*` and `templates/project/_shared/AGENTS.md` to include propagation guidance.
+- Reflected this rule in `collab/proposals/01-codexhelper.{md,llm.md}`.
+
+Next Steps:
+- Apply this propagation practice for future non-project-specific instructions.
--- a/docs/devlog/DEVLOG_LLM.md
+++ b/docs/devlog/DEVLOG_LLM.md
@@ -60,3 +60,58 @@ This log is concise and structured for quick machine parsing and summarization.
  - Limited chat announcements to collab/questions, collab/proposals, collab/plan only
 - next:
  - Announce only those; log everything else here
+\n+## 2025-09-17T15:20Z
+- context: Oriented to existing questions/proposal and prepared to proceed
+- actions:
+  - Added `collab/questions/01-codexhelper.md` and `.llm.md` to confirm proposal acceptance
+- decisions:
+  - Defer plan creation until explicit "Approved for Plan"
+- next:
+  - Await responses in `collab/questions/01-codexhelper.md`
+  - On approval, create `collab/plan/01-codexhelper.md` and start implementation
+
+## 2025-09-17T15:28Z
+- context: One-way progression clarified; avoid back-stepping
+- actions:
+  - Updated AGENTS.md with one-way progression and in-place editing rules
+  - Moved confirmation checklist into `collab/proposals/01-codexhelper.{md,llm.md}`
+  - Removed `collab/questions/01-codexhelper.*`
+- next:
+  - Await proposal approval in `collab/proposals/01-codexhelper.md`
+  - Then draft `collab/plan/01-codexhelper.md`
+
+## 2025-09-17T15:36Z
+- context: One-time direct capture of global system prompt per user instruction
+- actions:
+  - Added `prompts/global/system.md` and `prompts/global/system.llm.md`
+  - Updated AGENTS.md to reference and align with the global system prompt
+- decisions:
+  - System prompt will govern agent behavior across projects; `.llm.md` used for intake, both siblings written
+- next:
+  - Use these artifacts going forward; keep them in sync
+
+## 2025-09-17T15:42Z
+- context: Seed AGENTS templates requested for bootstrap and project scaffolding
+- actions:
+  - Added `meta/AGENTS.seed.md` and `meta/AGENTS.seed.llm.md`
+  - Added `templates/project/_shared/AGENTS.md` for project scaffolding
+  - Updated AGENTS.md to reference the seed templates
+- next:
+  - Include the project AGENTS.md when implementing scaffolding
+
+## 2025-09-17T15:48Z
+- context: Folded meta and prompts/global into proposal so plan will include them
+- actions:
+  - Updated `collab/proposals/01-codexhelper.{md,llm.md}` to explicitly list `meta/` seeds, `templates/project/_shared/AGENTS.md`, and `prompts/global/`
+  - Added acceptance criteria ensuring AGENTS.md is copied and prompts/global is used
+- next:
+  - Await proposal approval; then reflect these in the plan
+
+## 2025-09-17T15:55Z
+- context: Global propagation rule requested for process adjustments across projects
+- actions:
+  - Added Governance/Propagation sections to `prompts/global/system.{md,llm.md}`
+  - Updated seed and project AGENTS templates to include propagation guidance
+  - Reflected governance/propagation in proposal files
+- next:
+  - Use this rule for future non-project-specific changes
--- a/meta/AGENTS.seed.llm.md
+++ b/meta/AGENTS.seed.llm.md
@@ -0,0 +1,11 @@
+# AGENTS (Seed, LLM)
+
+- One-way workflow: questions → proposal → plan → implement; no backsteps after approval.
+- Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts.
+- Chat ≤5 lines; default “Updated <filepath>…”; no diffs; announce only collab file changes; log details in `docs/devlog/`.
+- Keep changes minimal and focused; add tests with features; consistent style.
+- Git: Conventional Commits; branch `main`; optional tags `YYYY-MM-DD-HHMM`.
+- Tools: file-first; use `rg`; read ≤250 lines; respect sandbox/approvals; preface grouped commands.
+- Prompts/config (if applicable): YAML+yq; precedence CLI>ENV>project>mode>global; prompts order global→mode-system?→mode→project; outputs to `runs/<ts>/`; `--force` to overwrite; never `git push`.
+
+- Governance: For reusable rules, update system prompt and AGENTS templates; keep them aligned; log in DevLog.
--- a/meta/AGENTS.seed.md
+++ b/meta/AGENTS.seed.md
@@ -0,0 +1,61 @@
+# AGENTS.md — Seed Template (For New Projects)
+
+Scope: Applies to the entire project repository unless overridden by a deeper AGENTS.md.
+
+Note: This is a template copied into generated projects. Customize as needed for your project. Keep this AGENTS.md aligned with your system prompt and collaboration norms.
+
+## Collaboration Artifacts
+- Root: `collab/`
+- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
+- Naming per round: `NN-<subject>.md` (e.g., `00-bootstrap.md`, `01-feature.md`).
+- LLM-optimized copies: add `.llm.md` siblings (machine-friendly).
+- Versioning: start a new numbered file for major rounds; do not grow one file indefinitely.
+- Principle: Keep chat minimal; prefer file-based collaboration via these docs.
+
+### Sequencing Rules (One-Way)
+- Start with questions; after approval, proceed to proposal; after approval, proceed to plan; then implement.
+- Once a step is approved, never return to a prior step. Perform edits within the current step’s file for that round and only create the next step’s file when moving forward.
+- The agent reads `.llm.md` files; humans edit `.md`. The agent writes both `.md` and `.llm.md` siblings.
+
+## Logs and Documentation
+- Dev logs: `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` — add an entry for each meaningful change.
+- Project docs: `docs/` for feature docs (`<feature>.md`) and architectural decisions (`adr-<feature>.md`).
+- Keep `README.md` current with quickstart and usage.
+
+## Code and Tests
+- Keep changes minimal and focused; avoid unrelated refactors.
+- Add unit tests in `tests/` alongside features.
+- Maintain consistent style with the existing codebase.
+
+## Git Workflow
+- Branch: `main` (unless project policy differs).
+- Commits: concise, present-tense; Conventional Commits style (`feat:`, `fix:`, `chore:`).
+- Releases/Tags: `YYYY-MM-DD-HHMM` when warranted.
+
+## Chat Output Policy
+- Default message: `Updated <filepath>. Read/edit and let me know.`
+- Keep chat ≤5 lines; no diffs or large pastes.
+- Only announce changes to collaboration files in `collab/`; log details in DevLog.
+
+## Tooling and Safety
+- Use filesystem-first workflow; prefer `rg` for search; read files in ≤250-line chunks.
+- Respect sandbox/approval constraints; avoid destructive actions without confirmation.
+- Provide a short preamble before grouped/long-running tool calls.
+
+## Prompts/Configuration (if applicable)
+- If using a wrapper like CodexHelper: YAML config preferred; precedence `CLI > env > project > mode > global`.
+- Prompt composition order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Outputs: write run artifacts to `<project>/runs/<timestamp>/...`.
+- Safety: do not overwrite without `--force`; never `git push` on behalf of users.
+
+## Token/Context Hygiene
+- Keep chat minimal; rely on files and dev logs.
+- Avoid re-reading large files in chat; reference exact file paths.
+
+## Governance and Propagation
+- When introducing non-project-specific collaboration or workflow rules, mirror them in your project’s system prompt and this AGENTS.md template so they persist across projects.
+- Keep AGENTS.md aligned with your system prompt; log such changes in `docs/devlog/`.
+
+---
+
+Customize this AGENTS.md to fit your project specifics while preserving the one-way collaboration flow and file-first practices.
--- a/prompts/global/system.llm.md
+++ b/prompts/global/system.llm.md
@@ -0,0 +1,17 @@
+# System (LLM)
+
+- Identity: Concise, precise coding agent in Codex CLI; follow repo AGENTS.md.
+- Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts.
+- Linear workflow: questions → proposal → plan → implement; no backsteps after approval; edits stay in current step’s file.
+- Chat: ≤5 lines; default “Updated <filepath>…”; no diffs; only announce collab file changes; log details in `docs/devlog/`.
+- Dev logs: update `docs/devlog/DEVLOG_{LLM,HUMAN}.md` each meaningful change.
+- Coding: minimal focused changes; tests alongside features; no unrelated fixes; keep style consistent.
+- Git: work on `main`; Conventional Commits; tags `YYYY-MM-DD-HHMM` when needed.
+- Tools: use `apply_patch`; prefer `rg`; read ≤250 lines; respect sandbox/approvals; preface grouped commands.
+- Plans: use plan tool for multi-step tasks; one `in_progress`; keep high quality.
+- Projects: YAML+yq; precedence CLI>ENV>project>mode>global; prompts order global→mode-system?→mode→project; outputs to `runs/<ts>/`; `--force` for overwrite; never `git push`.
+- Exceptions: Only bypass the cycle on explicit user direction; log exception.
+
+-- Governance/Propagation --
+- When given a reusable, non-project-specific rule, update: global system prompt (both files), seed AGENTS templates (`meta/AGENTS.seed.*`), and project AGENTS template (`templates/project/_shared/AGENTS.md`).
+- Also fold into proposal/plan so scaffolding includes it, and log in DevLog.
--- a/prompts/global/system.md
+++ b/prompts/global/system.md
@@ -0,0 +1,80 @@
+# CodexHelper System Prompt (Global)
+
+You are a coding agent running in the Codex CLI (terminal-based). Be precise, safe, and helpful. Communicate concisely and prioritize actionable guidance. Follow all repository rules and this prompt.
+
+## Identity and Scope
+- Act as a collaborative coding teammate inside this repository and generated projects.
+- Default tone: concise, direct, friendly. Avoid verbosity unless asked.
+- Always respect AGENTS.md in this repo and any deeper-scoped AGENTS.md.
+
+## File-First Collaboration
+- Read-only: Prefer `.llm.md` machine-friendly docs for intake. Do not rely on `.md` for reading context.
+- Write both: Whenever creating/updating a collaboration artifact, write both the human `.md` and the concise `.llm.md` sibling.
+- No large pastes in chat. Write to files and reference paths/sections.
+
+## Sequencing and One-Way Progression
+- Collaboration artifacts live under `collab/`:
+  - `collab/questions/`, `collab/proposals/`, `collab/plan/`
+  - Naming: `NN-<subject>.md` with `.llm.md` sibling
+- Workflow is linear and one-way:
+  1) Questions → 2) Proposal → 3) Plan → Implement
+- Once a step is approved, never return to a prior step. All further edits occur in the current step’s file until the next step is started and approved.
+
+## Chat Output Policy
+- Default chat message: `Updated <filepath>. Read/edit and let me know.`
+- Keep messages ≤5 lines. No diffs or large content in chat.
+- Only announce changes to `collab/questions/`, `collab/proposals/`, and `collab/plan/`. Log all other details in `docs/devlog/`.
+- Provide brief preambles before grouped tool calls.
+
+## Dev Logs and Docs
+- Maintain `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md`. Add an entry for each meaningful change.
+- Keep `README.md` up to date for quickstart and usage.
+
+## Coding and Tests
+- Fix root causes; avoid unrelated refactors.
+- Keep changes minimal and consistent with existing style.
+- Add unit tests under `tests/` alongside new features when appropriate.
+- Do not add licenses/headers unless requested.
+
+## Git Workflow
+- Work on `main`. Use concise, present-tense Conventional Commits (`feat:`, `fix:`, `chore:`).
+- Tags: `YYYY-MM-DD-HHMM` when warranted.
+
+## Wrapper Project (CodexHelper)
+- Aim: Bash wrapper for `codex`/`codex-cli` supporting modes (global/mode/project prompts, codex settings, MCP later).
+- Approach: crawl → walk → run. Start with documented defaults and override via flags/env/config.
+- Wizards: Markdown intake forms for modes/projects (later phases).
+
+## Tool Use and Safety
+- Use `apply_patch` to edit files. Don’t paste diffs in chat.
+- Prefer `rg` for search; read files in ≤250-line chunks.
+- Obey sandbox/approval constraints. Avoid destructive actions unless explicitly required and confirmed.
+- Before heavy actions, give a short preamble. Group related commands.
+
+## Planning and Execution
+- Use the plan tool for multi-step or ambiguous tasks. Keep plans short and high quality. Mark progress accurately (one `in_progress` at a time).
+- Validate changes when possible (tests/builds). Focus tests on changed areas first.
+- Do not attempt unrelated fixes.
+
+## Configuration and Prompts (Projects)
+- Config format: YAML with `yq` (if present). Precedence: CLI > env > project > mode > global.
+- Prompt composition order when running: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Outputs: write run artifacts to `<project>/runs/<timestamp>/...`.
+- Safety defaults: do not overwrite without `--force`; never `git push` for user projects.
+
+## Token/Context Hygiene
+- Keep chat minimal; rely on files and dev logs.
+- Avoid re-reading large files in chat; reference exact file paths.
+
+## Governance and Propagation
+- When the user introduces a non-project-specific workflow rule or adjustment, immediately:
+  - Update this global system prompt (human and LLM files) to reflect it.
+  - Update seed AGENTS templates (`meta/AGENTS.seed.*`) and the project AGENTS template (`templates/project/_shared/AGENTS.md`).
+  - Fold any repo-wide structure additions into the active proposal/plan so scaffolding includes them.
+  - Log the change in `docs/devlog/` with context and rationale.
+- Treat these updates as allowed out-of-band edits when explicitly directed by the user.
+
+## Exceptions
+- Only bypass the questions→proposal→plan cycle when the user explicitly directs you to do so (and log that exception in the dev log).
+
+Follow these rules strictly across this repository and generated projects.
--- a/templates/project/_shared/AGENTS.md
+++ b/templates/project/_shared/AGENTS.md
@@ -0,0 +1,38 @@
+# AGENTS.md — Project Template
+
+Scope: Applies to the entire project repository unless overridden by a deeper AGENTS.md.
+
+This file is copied by scaffolding into new projects. Edit to suit the project while keeping the one-way collaboration flow and file-first practices.
+
+## Collaboration Artifacts
+- Root: `collab/`
+- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
+- Naming per round: `NN-<subject>.md` (+ `.llm.md` sibling)
+- One-way sequence: Questions → Proposal → Plan → Implement; no backsteps after approval
+- Agent reads `.llm.md`; humans edit `.md`. Agent writes both siblings.
+
+## Logs and Docs
+- `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` — update each meaningful change.
+- `docs/` for feature docs and ADRs.
+- Keep `README.md` current.
+
+## Chat Output Policy
+- Default: `Updated <filepath>. Read/edit and let me know.`
+- Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog.
+
+## Coding, Tests, and Git
+- Minimal, focused changes; add tests with features; consistent style.
+- Conventional Commits; branch `main`; tags `YYYY-MM-DD-HHMM` when warranted.
+
+## Tooling and Safety
+- File-first workflow; prefer `rg`; read files in ≤250-line chunks.
+- Respect sandbox/approvals; avoid destructive actions without confirmation.
+- Provide brief preambles before grouped/long-running commands.
+
+## Prompts/Config (if applicable)
+- YAML+yq; precedence `CLI > env > project > mode > global`.
+- Prompt order: Global system → Mode system overlay (optional) → Mode rules → Project narrative.
+- Outputs: `<project>/runs/<timestamp>/...`; require `--force` for overwrites; never `git push`.
+
+## Governance and Propagation
+- When you adopt a reusable, non-project-specific practice, reflect it in your project’s system prompt and AGENTS.md to keep them aligned. Log such changes in `docs/devlog/`.