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

governance: add planning/architecture rule (plan ahead, module map, avoid refactors); propagate to system prompts, AGENTS templates, proposal, and plan

Browse Source
This commit is contained in:
Charles N Wyble - admin
2025-09-17 10:33:57 -05:00
parent fae0f5b413
commit c655476699
10 changed files with 47 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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 `<project>/runs/<ts>/`.
- 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/<ModeName>/...` (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.

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

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

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

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

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

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