governance: zero technical debt, production-ready always; safety first across system prompts, AGENTS templates, proposal, and plan

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 `<project>/runs/<ts>/`.
+  - 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.

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 `<project>/runs/<timestamp>/...`.
 - 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
+- Hour 7–8: Milestone 6 — Config precedence (tests first); finalize quickstart docs
-
-Notes:
-- If behind schedule, defer non-essential docs to a follow-up commit and prioritize tested functionality.
  - Ongoing: Maintain/expand tests with each feature change (TDD).

collab/proposals/01-codexhelper.llm.md

@@ -14,7 +14,8 @@
 - 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.
- - 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` [ ]

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.
+  - 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.
+  - 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.
+  - `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.
+  - 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.
+  - 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)

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.

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

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/<ts>/`; `--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.

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.

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.

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).
 

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.