57 lines
4.6 KiB
Markdown
57 lines
4.6 KiB
Markdown
# 01 — CodexHelper — Proposal (LLM)
|
|
|
|
- Tool: `CodexHelper` bash wrapper for codex-cli.
|
|
- CLI (subcommands):
|
|
- new-project: scaffold project files
|
|
- run: compose prompts + call codex
|
|
- new-mode: scaffold mode (repo-only)
|
|
- Where to run: repo → only new-mode; elsewhere → new-project, run.
|
|
- Prompts order: global system → mode system overlay (optional) → mode rules → project narrative.
|
|
- Config: YAML + yq; precedence CLI > env > project > mode > global.
|
|
- Binary: detect `codex` then `codex-cli`; override `CODEX_BIN`.
|
|
- Safety: no overwrites without `--force`; never `git push` for user projects.
|
|
- Outputs: `<project>/runs/<ts>/...`.
|
|
- 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/`, `.gitea/workflows/`, `docker/`, `scripts/`.
|
|
- 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.
|
|
- 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.
|
|
- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`.
|
|
- CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea + Docker orchestration; dependencies via Docker; explicit names/cleanup.
|
|
- .gitignore Governance: maintain `.gitignore` with `runs/` and OS ignores across repos and generated projects.
|
|
- Audits Governance: run audits regularly; prompt before releases; record under `docs/audits/`; enforce via CI step.
|
|
- Phase 1 acceptance:
|
|
- new-mode creates mode skeleton
|
|
- new-project scaffolds without overwrites
|
|
- run composes and calls detected codex; writes under runs/
|
|
- precedence respected; running in repo errors for run/new-project
|
|
- new-project copies `templates/project/_shared/AGENTS.md` into project root as `AGENTS.md`
|
|
- 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
|
|
- planning: architecture/module map documented; module implementations follow approved plan with no unplanned refactors
|
|
- clean root: root remains minimal; scaffolding organizes assets under subdirectories
|
|
- ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
|
|
- project CI: scaffold includes `.gitea/workflows/ci.yml`, `docker/compose.yml`, `docker/test/Dockerfile`, and `scripts/test.docker.sh`
|
|
- audits: audit script present and run in CI; reports recorded in repo when performed
|
|
- ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified
|
|
\n+## Approval — Tick All That Apply
|
|
|
|
- Subcommands approved: `new-project`, `run`, `new-mode` [ ]
|
|
- Scope approved: repo→`new-mode` only; outside→`new-project`/`run` [ ]
|
|
- Prompts order approved: global→mode-system?→mode→project [ ]
|
|
- Config+precedence approved: YAML+yq; CLI>ENV>project>mode>global [ ]
|
|
- Safety approved: `--force` to overwrite; no `git push`; outputs to `<project>/runs/<ts>/...` [ ]
|
|
- Repo layout approved (modes, templates, global prompts) [ ]
|
|
- Project layout approved (prompts, `_mode/`, codex.yaml, codex.sh, .gitignore) [ ]
|
|
- Include empty `prompts/style.md` by default [ ]
|
|
- Binary discovery: `codex`→`codex-cli`; override `CODEX_BIN` [ ]
|
|
- Pass-through flags: `--mode --prompt-file --config --sandbox --full-auto` [ ]
|
|
- Block `run`/`new-project` inside repo with helpful error [ ]
|
|
- Phase 1 (Crawl) scope acceptable [ ]
|
|
- Add `docs/ROADMAP.md`; MCP deferred [ ]
|
|
|
|
Final: Reply in the human doc with “Approved for Plan” when all are checked.
|