KNEL/ChatGPTScaffolding
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Charles N Wyble - admin
2025-09-17 10:31:25 -05:00
parent ff33cb282a
commit fae0f5b413
11 changed files with 72 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
collab/plan/01-codexhelper.llm.md
View File

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

11
collab/plan/01-codexhelper.md
View File

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

4
collab/proposals/01-codexhelper.llm.md
View File

@@ -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` [ ]

15
collab/proposals/01-codexhelper.md
View File

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