diff --git a/AGENTS.md b/AGENTS.md index d19361b..3e792cb 100644 --- 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-.md` per round to avoid long single files. - Status style: one-line updates before tool calls; rely on devlog for detail. diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md index 1b1f988..c5e2dc2 100644 --- 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: `/runs//...`. -- Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/system.md`, `modes//{mode.md,system.md?,defaults.yaml}`, `templates/project//...`. -- 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//{mode.md,system.md?,defaults.yaml}`, `templates/project//...`, `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 `/runs//...` [ ] +- 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. diff --git a/collab/proposals/01-codexhelper.md b/collab/proposals/01-codexhelper.md index 87e63c2..6927d9e 100644 --- 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//mode.md` (mode rules) - `modes//system.md` (optional mode-specific system overlay) - `modes//defaults.yaml` (default codex settings, optional MCP placeholders) - `templates/project//...` (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//...`. - 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 `/runs//...`? +6) Repo layout: `CodexHelper`, `prompts/global/system.md`, `modes//{mode.md, system.md?, defaults.yaml}`, `templates/project//...`? +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? diff --git a/docs/devlog/DEVLOG_HUMAN.md b/docs/devlog/DEVLOG_HUMAN.md index 1861ad8..3a9d7dd 100644 --- 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. diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index b569c99..2a1d230 100644 --- 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 diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md new file mode 100644 index 0000000..23c40a0 --- /dev/null +++ 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 …”; 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//`; `--force` to overwrite; never `git push`. + +- Governance: For reusable rules, update system prompt and AGENTS templates; keep them aligned; log in DevLog. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md new file mode 100644 index 0000000..f710c07 --- /dev/null +++ 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-.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 (`.md`) and architectural decisions (`adr-.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 . 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 `/runs//...`. +- 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. diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md new file mode 100644 index 0000000..1288b44 --- /dev/null +++ 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 …”; 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//`; `--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. diff --git a/prompts/global/system.md b/prompts/global/system.md new file mode 100644 index 0000000..642b068 --- /dev/null +++ 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-.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 . 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 `/runs//...`. +- 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. diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md new file mode 100644 index 0000000..a86cca8 --- /dev/null +++ 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-.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 . 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: `/runs//...`; 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/`.