diff --git a/collab/plan/01-codexhelper.llm.md b/collab/plan/01-codexhelper.llm.md index 8441376..a52d05a 100644 --- a/collab/plan/01-codexhelper.llm.md +++ b/collab/plan/01-codexhelper.llm.md @@ -17,6 +17,7 @@ - One-way workflow; minimal chat; read `.llm.md`, write both. - 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. - Deliverables: - `CodexHelper` bash script @@ -41,6 +42,7 @@ - Precedence: CLI > env > project > mode > global. - `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. - Open choices (defaulting now): - Include empty `prompts/style.md`: Yes. @@ -50,13 +52,13 @@ - Next: Implement per milestones; add concise README quickstart. - - Accelerated Timeline (8 hours today): +- Accelerated Timeline (8 hours today): - H0–1: test harness + failing smoke tests (CLI, guardrails) - H1–2: CLI skeleton + guardrails (make tests pass) - H2–3: binary detection + pass-through (tests first) - H3–4: new-mode scaffolder (tests first) - H4–6: new-project scaffolder (tests first) - H6–7: run: compose + invoke (tests first) - - H7–8: config precedence (tests first) + minimal docs + - H7–8: config precedence (tests first) + minimal docs - - Defer if needed: expand docs; polish templates. + - No deferral: docs must be completed; templates polished sufficiently for production. diff --git a/collab/plan/01-codexhelper.md b/collab/plan/01-codexhelper.md index 7c85d8a..099a6e4 100644 --- a/collab/plan/01-codexhelper.md +++ b/collab/plan/01-codexhelper.md @@ -31,9 +31,10 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p - Write tests covering precedence: global < mode < project < env < CLI. - Implement merging with `yq` and apply overrides. -7) Docs +7) Docs (no deferral) - Add `docs/wrapper.md` with usage examples and config reference. - Update `README.md` quickstart: installation, basic flows. +- Ensure docs updated in the same commit as features. ## Safety & Policies - Never overwrite without `--force`. @@ -41,7 +42,8 @@ Purpose: Deliver Phase 1 (Crawl) MVP of CodexHelper: subcommands, scaffolding, p - Write outputs to `/runs//...`. - 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. +- 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. ## 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`. @@ -65,8 +67,5 @@ Accelerated (8 hours today): - Hour 3–4: Milestone 3 — new-mode scaffolder (tests first) - Hour 4–6: Milestone 4 — new-project scaffolder (tests first) - Hour 6–7: Milestone 5 — run: compose + invoke (tests first) -- Hour 7–8: Milestone 6 — Config precedence (tests first); write quickstart docs - -Notes: -- If behind schedule, defer non-essential docs to a follow-up commit and prioritize tested functionality. +- Hour 7–8: Milestone 6 — Config precedence (tests first); finalize quickstart docs - Ongoing: Maintain/expand tests with each feature change (TDD). diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md index 2897469..30c79f4 100644 --- a/collab/proposals/01-codexhelper.llm.md +++ b/collab/proposals/01-codexhelper.llm.md @@ -14,7 +14,8 @@ - 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. - - 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. +- 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. - Phase 1 acceptance: - new-mode creates mode skeleton - new-project scaffolds without overwrites @@ -24,6 +25,7 @@ - prompts/global present and used in prompt composition - 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 \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 558e688..22b1fba 100644 --- a/collab/proposals/01-codexhelper.md +++ b/collab/proposals/01-codexhelper.md @@ -39,7 +39,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - `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. - - TDD Governance: enforce test-driven development; require unit/integration tests for all features here and in generated projects. +- 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. ## Project Layout (generated) - `AGENTS.md` (from `templates/project/_shared/AGENTS.md`) @@ -61,9 +62,10 @@ 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). - - 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. + - 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. - 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. ## Safety - Guardrails: @@ -96,9 +98,10 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - 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. - - TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass. + - `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. + - TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass. + - Zero Debt honored: code, tests, and docs complete; no debt items remain. ## Open Items for Confirmation - Template coverage: include `prompts/style.md` by default? (we’ll include as optional, empty file) diff --git a/docs/devlog/DEVLOG_HUMAN.md b/docs/devlog/DEVLOG_HUMAN.md index 09f64c3..6057cb1 100644 --- a/docs/devlog/DEVLOG_HUMAN.md +++ b/docs/devlog/DEVLOG_HUMAN.md @@ -184,3 +184,17 @@ Details: Next Steps: - Execute the plan using TDD, starting with test harness setup and failing tests. + +--- + +Date: 2025-09-17 16:24 (UTC) + +Summary: +- Added governance: zero technical debt and production-ready at all times (safety first, speed second) for this and generated projects. + +Details: +- Updated system prompts and AGENTS templates to mandate zero-debt and remove any doc/test deferrals. +- Updated proposal and plan to include this rule and acceptance criteria. + +Next Steps: +- Maintain zero-debt gate during implementation; no merges without tests and docs. diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index a285425..95855a1 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/docs/devlog/DEVLOG_LLM.md @@ -146,3 +146,11 @@ This log is concise and structured for quick machine parsing and summarization. - Updated plan with hour-by-hour accelerated timeline and deferral notes - next: - Begin implementation immediately upon plan approval + +## 2025-09-17T16:24Z +- context: Governance update — zero technical debt, production-ready always (safety first) +- actions: + - Updated global system prompt and seed/project AGENTS templates with zero-debt rule + - Amended proposal and plan to require docs/tests with every feature; removed any doc deferrals +- next: + - Enforce zero-debt gate throughout implementation diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 84d2111..80eda0d 100644 --- a/meta/AGENTS.seed.llm.md +++ b/meta/AGENTS.seed.llm.md @@ -9,3 +9,5 @@ - 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. + +- Zero Technical Debt: Safety first; no technical debt; always production-ready; no deferring tests/docs/refactors; TDD by default; keep docs current. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index 5b8b6fa..0db4212 100644 --- a/meta/AGENTS.seed.md +++ b/meta/AGENTS.seed.md @@ -57,6 +57,12 @@ Note: This is a template copied into generated projects. Customize as needed for - 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/`. +## Zero Technical Debt, Production-Ready Always +- Safety is top priority; speed is second. Never compromise quality. +- No technical debt allowed. Every commit must be production-ready. +- No deferring tests, documentation, or necessary refactors. +- Adopt TDD (tests first); keep docs current with changes. + --- 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 index b26dbe8..afa6934 100644 --- a/prompts/global/system.llm.md +++ b/prompts/global/system.llm.md @@ -15,3 +15,9 @@ -- 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. + +-- Zero Technical Debt, Production-Ready -- +- Safety first, speed second. No technical debt ever; always production-ready. +- 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. diff --git a/prompts/global/system.md b/prompts/global/system.md index adc17ac..8bf42dc 100644 --- a/prompts/global/system.md +++ b/prompts/global/system.md @@ -75,6 +75,15 @@ 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. +## 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. +- No deferring of tests, documentation, or refactors required for clarity/maintainability. +- Follow TDD: write failing tests first; make them pass; refactor. +- Keep documentation (README, docs/wrapper.md, DevLogs) current with changes. +- Code must be clean, maintainable, and consistent with project style. +- Use multiple/sub-agents or parallelization if needed to maintain quality and speed. + ## 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). diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md index 644eb54..bf78e35 100644 --- a/templates/project/_shared/AGENTS.md +++ b/templates/project/_shared/AGENTS.md @@ -36,3 +36,8 @@ This file is copied by scaffolding into new projects. Edit to suit the project w ## 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/`. + +## Zero Technical Debt, Production-Ready Always +- 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.