From c655476699974a6e58d528bb9052c37a1837a33a Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 10:33:57 -0500 Subject: [PATCH] governance: add planning/architecture rule (plan ahead, module map, avoid refactors); propagate to system prompts, AGENTS templates, proposal, and plan --- collab/plan/01-codexhelper.llm.md | 3 +++ collab/plan/01-codexhelper.md | 8 +++++++- collab/proposals/01-codexhelper.llm.md | 4 +++- collab/proposals/01-codexhelper.md | 4 +++- docs/devlog/DEVLOG_LLM.md | 8 ++++++++ meta/AGENTS.seed.llm.md | 2 ++ meta/AGENTS.seed.md | 5 +++++ prompts/global/system.llm.md | 5 +++++ prompts/global/system.md | 6 ++++++ templates/project/_shared/AGENTS.md | 5 +++++ 10 files changed, 47 insertions(+), 3 deletions(-) diff --git a/collab/plan/01-codexhelper.llm.md b/collab/plan/01-codexhelper.llm.md index a52d05a..8138f40 100644 --- a/collab/plan/01-codexhelper.llm.md +++ b/collab/plan/01-codexhelper.llm.md @@ -18,6 +18,7 @@ - Governance/propagation: update prompts/global and seed/project AGENTS when norms change. - Safety: `--force` for overwrite; never `git push`; runs under `/runs//`. - Zero Technical Debt: production-ready always; no deferring docs/tests/refactors. + - Planning/Architecture: plan ahead; maintain architecture/module map; implement module-by-module; avoid refactors unless plans/docs updated due to new info. - Deliverables: - `CodexHelper` bash script @@ -26,6 +27,7 @@ - `templates/project//...` (optional mode-specific add-ons; start minimal) - `docs/wrapper.md` and README updates - Test harness (`bats`), `tests/` with coverage of all CLI paths + - `docs/architecture.md` and ADRs for key decisions - Implementation details: - Guard where running: inside repo → only `new-mode` allowed. @@ -43,6 +45,7 @@ - `prompts/global/` used in composition. - Tests: all features covered by unit/integration tests (bats); TDD observed (tests committed alongside implementation); CI/local test script present. - Zero Debt: docs updated; no pending TODOs/deferrals; production-ready criteria met. + - Planning/Architecture: architecture/module map exists and matches implemented modules; no unplanned refactors. - Open choices (defaulting now): - Include empty `prompts/style.md`: Yes. diff --git a/collab/plan/01-codexhelper.md b/collab/plan/01-codexhelper.md index 099a6e4..7353108 100644 --- a/collab/plan/01-codexhelper.md +++ b/collab/plan/01-codexhelper.md @@ -7,6 +7,10 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p - Add `tests/` directory and `scripts/test.sh` using bats-core (document installation/usage). - Write initial smoke tests that will fail until implementation exists. +0a) Architecture & Module Map +- Create `docs/architecture.md` summarizing global architecture, module boundaries, and responsibilities for Phase 1. +- Add or update ADRs as needed for key decisions. + 1) CLI skeleton + guardrails (tests first) - Write tests for `--help`, subcommands, and location guardrails. - Implement `CodexHelper` with `new-project`, `run`, `new-mode` and enforce location rules. @@ -43,7 +47,8 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p - Minimal chat; read `.llm.md`, write both `.md` and `.llm.md` for collab artifacts. - Governance/Propagation: reflect future non-project-specific norms into `prompts/global/` and AGENTS templates; log in DevLog. - TDD default: write failing tests before implementing features; require unit/integration tests for all new functionality in this repo and generated projects. - - Zero Technical Debt: safety first; no technical debt; always production-ready; do not defer tests/docs/refactors; use sub-agents as needed to maintain quality and speed. +- Zero Technical Debt: safety first; no technical debt; always production-ready; do not defer tests/docs/refactors; use sub-agents as needed to maintain quality and speed. + - Planning/Architecture: align via Questions→Proposal→Plan; maintain `docs/architecture.md` and ADRs; avoid refactors except when plans/docs are updated due to new information. ## Acceptance Criteria - Inside this repo: `CodexHelper new-mode --name Demo` creates `modes/Demo/{mode.md,defaults.yaml}` (and optional `system.md`) and refuses overwrites without `--force`. @@ -62,6 +67,7 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p ## Timeline (targeted) Accelerated (8 hours today): - Hour 0–1: Test harness setup; write failing smoke tests (CLI, guardrails) +- Hour 0–1 (parallel): Draft `docs/architecture.md` (module map) and commit - Hour 1–2: Milestone 1 — CLI skeleton + guardrails (make tests pass) - Hour 2–3: Milestone 2 — Binary detection + pass-through (tests first) - Hour 3–4: Milestone 3 — new-mode scaffolder (tests first) diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md index 30c79f4..77737c5 100644 --- a/collab/proposals/01-codexhelper.llm.md +++ b/collab/proposals/01-codexhelper.llm.md @@ -15,7 +15,8 @@ - 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. - TDD Governance: adopt test-driven development with full unit/integration tests for all features in this repo and generated projects; tests written first and required for acceptance. - - Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed. +- Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed. + - Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated. - Phase 1 acceptance: - new-mode creates mode skeleton - new-project scaffolds without overwrites @@ -26,6 +27,7 @@ - governance rule: changes to global norms propagate to prompts/global and AGENTS templates; logged in DevLog - tests: unit/integration tests (bats) cover CLI flows and guardrails; TDD observed - zero debt: docs/tests included with every feature; no pending TODOs/deferrals; production-ready criteria met + - planning: architecture/module map documented; module implementations follow approved plan with no unplanned refactors \n+## Approval — Tick All That Apply - Subcommands approved: `new-project`, `run`, `new-mode` [ ] diff --git a/collab/proposals/01-codexhelper.md b/collab/proposals/01-codexhelper.md index 22b1fba..b00ff45 100644 --- a/collab/proposals/01-codexhelper.md +++ b/collab/proposals/01-codexhelper.md @@ -40,7 +40,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - `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. - TDD Governance: enforce test-driven development; require unit/integration tests for all features here and in generated projects. - - Zero Technical Debt: safety first; always production-ready; no deferring tests/docs/refactors; leverage sub-agents when needed. +- Zero Technical Debt: safety first; always production-ready; no deferring tests/docs/refactors; leverage sub-agents when needed. + - Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; keep a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated. ## Project Layout (generated) - `AGENTS.md` (from `templates/project/_shared/AGENTS.md`) @@ -66,6 +67,7 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - Governance/Propagation: non-project-specific rules are folded back into global/system and templates; changes logged. - TDD: tests are written first and required for acceptance. - Zero Debt: no pending TODOs/deferrals; docs updated alongside code; production-ready gate on each change. + - Planning/Architecture: architecture/module map documented; implementations follow plan without unplanned refactors. ## Safety - Guardrails: diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 95855a1..0c0f4de 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/docs/devlog/DEVLOG_LLM.md @@ -154,3 +154,11 @@ This log is concise and structured for quick machine parsing and summarization. - Amended proposal and plan to require docs/tests with every feature; removed any doc deferrals - next: - Enforce zero-debt gate throughout implementation + +## 2025-09-17T16:30Z +- context: Governance update — plan ahead and maintain global architecture; avoid refactors +- actions: + - Updated system prompts and AGENTS templates to encode planning/architecture rule + - Updated proposal/plan to add architecture/module map deliverable and acceptance +- next: + - Add `docs/architecture.md` early in implementation per plan diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 80eda0d..a12b864 100644 --- a/meta/AGENTS.seed.llm.md +++ b/meta/AGENTS.seed.llm.md @@ -11,3 +11,5 @@ - Governance: For reusable rules, update system prompt and AGENTS templates; keep them aligned; log in DevLog. - Zero Technical Debt: Safety first; no technical debt; always production-ready; no deferring tests/docs/refactors; TDD by default; keep docs current. + +- Planning/Architecture: Plan via Questions→Proposal→Plan; maintain global architecture/module map; implement module-by-module; avoid refactors unless assumptions change and plans/docs are updated. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index 0db4212..168049b 100644 --- a/meta/AGENTS.seed.md +++ b/meta/AGENTS.seed.md @@ -66,3 +66,8 @@ Note: This is a template copied into generated projects. Customize as needed for --- Customize this AGENTS.md to fit your project specifics while preserving the one-way collaboration flow and file-first practices. + +## Planning and Architecture +- Plan ahead: use Questions → Proposal → Plan to align before coding. +- Maintain a project architecture/module map and document boundaries. +- Implement module-by-module per plan; avoid refactors, except when new info requires plan/doc updates. diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md index afa6934..3dc6146 100644 --- a/prompts/global/system.llm.md +++ b/prompts/global/system.llm.md @@ -21,3 +21,8 @@ - No deferring tests/docs/refactors needed for clarity/maintainability. - TDD by default (tests first). Keep docs current. - Use sub-agents/parallelization to maintain quality and speed. +- +-- Planning/Architecture -- +- Plan before coding via Questions → Proposal → Plan. +- Maintain a global architecture/module map; document boundaries. +- Implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated. diff --git a/prompts/global/system.md b/prompts/global/system.md index 8bf42dc..1833b7b 100644 --- a/prompts/global/system.md +++ b/prompts/global/system.md @@ -75,6 +75,12 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa - 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. +## Planning and Architecture +- Plan first, implement second. Use the Questions → Proposal → Plan cycle to reach alignment before coding. +- Maintain a global architecture and module map; document boundaries and responsibilities up front. +- Implement module-by-module using the cycle; avoid refactors by designing ahead. Refactors occur only when new information invalidates assumptions and must be reflected in updated proposals/plans and docs. +- Keep ADRs or an architecture summary under `docs/` current. + ## Zero Technical Debt, Production-Ready Always - Safety first, speed second. Never compromise correctness, security, or data safety. - No technical debt allowed at any time. Every commit must be production-ready. diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md index bf78e35..70e545e 100644 --- a/templates/project/_shared/AGENTS.md +++ b/templates/project/_shared/AGENTS.md @@ -41,3 +41,8 @@ This file is copied by scaffolding into new projects. Edit to suit the project w - Safety first; speed second. No technical debt, ever. - Do not defer tests, docs, or clarity/maintainability refactors. - Practice TDD (tests first) and keep docs up to date with changes. + +## Planning and Architecture +- Plan ahead via Questions → Proposal → Plan to align before coding. +- Maintain an architecture/module map and clear module boundaries. +- Implement module-by-module; refactor only when new information requires plan/doc updates.