governance: zero technical debt, production-ready always; safety first across system prompts, AGENTS templates, proposal, and plan
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
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).
|
||||
|
||||
@@ -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` [ ]
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user