From 4f5177d214f96edd6ae9c8233b05dcf5c0697b22 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 11:54:00 -0500 Subject: [PATCH] docs: v0.0.1 contains only NEWSTART artifacts --- NEWSTART.llm.md | 18 ++++++++ NEWSTART.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 NEWSTART.llm.md create mode 100644 NEWSTART.md diff --git a/NEWSTART.llm.md b/NEWSTART.llm.md new file mode 100644 index 0000000..514027e --- /dev/null +++ b/NEWSTART.llm.md @@ -0,0 +1,18 @@ +# NEW START — LLM + +- Non-negotiables: zero-debt; TDD; plan-first; quiet chat; containers-first; CI parity; clean root; audits. +- Gates (human .md phrases): Questions→“Approved for Proposal”; Proposal→“Approved for Plan”; Plan→“Approved to Implement”. +- Chat: announce collab files only; ≤5 lines; no content/diff streaming. +- Quiet tooling: use scripts/toolwrap.sh; success → no chat; failure → append stdout/stderr to docs/devlog/tool.log. +- Audits: run scripts/audit.sh regularly and pre-release; store in docs/audits/. +- CI/containers: Gitea Actions + local Docker Compose; dependencies via images; explicit names; cleanup; mount host config if needed. +- .gitignore: include runs/ + OS files; keep current. +- Layout: collab/, docs/, prompts/global/, modes/, templates/project/_shared/, scripts/, .gitea/. +- Wrapper (MVP): subcommands new-mode (repo-only), new-project (outside), run (outside). Guardrails enforced. +- Prompt order: global system → mode system? → mode rules → project narrative. +- Config via yq: global < mode < project < ENV < CLI. +- Project scaffold: AGENTS.md; prompts/{project.md,style.md?}; prompts/_mode; codex.yaml; codex.sh; CI (gitea); docker/compose.yml + test/Dockerfile; scripts/{test.sh,test.docker.sh,audit.sh}; .gitignore; runs/. +- Tests: bats/internal; cover CLI/guardrails/scaffold/composition/precedence. +- Branching (recommended): trunk-based; protected main; short-lived branches; tags YYYY-MM-DD-HHMM; required checks; Conventional Commits. +- Start checklist: commit clean skeleton; add NEWSTART docs; start with Questions 00; use toolwrap + DevLogs; add audits early. + diff --git a/NEWSTART.md b/NEWSTART.md new file mode 100644 index 0000000..804b396 --- /dev/null +++ b/NEWSTART.md @@ -0,0 +1,113 @@ +# New Start — CodexHelper Project Blueprint + +Purpose +- Capture everything we learned so far and define a clean, production-ready blueprint for a fresh repository using CodexHelper. This document is human-focused; see NEWSTART.llm.md for the compact machine version. + +Guiding Principles (Non-Negotiable) +- Safety first, speed second. Zero technical debt at all times; every commit is production-ready. +- TDD by default. Write failing tests first; make them pass; refactor. +- Plan first, implement second. Strict Questions → Proposal → Plan → Implement. +- Quiet, file-first collaboration. Chat is minimal; files and logs carry the detail. +- Containers-first, with CI parity between local and Gitea. +- Clean repository roots and predictable scaffolding. + +Process & Governance +- Sequencing (Strict Gates) + - Questions → Proposal → Plan → Implement (one-way progression; no backsteps after approval). + - Approvals must use exact phrases in the human .md file: + - Questions approval: “Approved for Proposal” + - Proposal approval: “Approved for Plan” + - Plan approval: “Approved to Implement” + - Agent reads `.llm.md`; humans edit `.md`. Agent writes both siblings for each artifact. +- Chat Output Policy + - Default: “Updated . Read/edit and let me know.” + - ≤5 lines; do not stream file contents or diffs in chat. + - Announce only collab files (questions/proposals/plan). Everything else goes to DevLog. +- Quiet Shell, Tool Logging + - Quiet is mandatory (no toggle). Use silent checks and avoid printing command output. + - Use `scripts/toolwrap.sh` to run host commands quietly. + - On success: no chat output; brief SUCCESS line is logged to `docs/devlog/tool.log`. + - On failure (not sandbox): append full stdout/stderr + timestamp + command to `docs/devlog/tool.log`. +- TDD & Quality + - Tests live under `tests/`; provide `scripts/test.sh` and `scripts/test.docker.sh`. + - Add tests for every feature; keep tests fast and focused. + - No unrelated refactors; fix root causes. +- Architecture & Planning + - Maintain `docs/architecture.md` and ADRs for significant decisions. + - Design module boundaries up front to avoid refactors; if assumptions change, update Questions/Proposal/Plan and docs before changing code. +- Clean Roots & .gitignore Housekeeping + - Keep root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`, `.gitea/`. + - Include `.gitignore` with `runs/` and common OS files; keep it current. +- CI/Containers (Gitea + Docker) + - CI uses Gitea Actions (`.gitea/workflows/`) and must mirror local Docker Compose. + - Do work in containers when appropriate; host is for git/tea and Docker orchestration only. + - Dependencies (e.g., bats, yq) are provided via Docker images; avoid host installs. + - Naming hygiene for containers/networks; explicit names; ensure cleanup. + - Where host auth/config is required (e.g., codex), mount config dirs into the container securely. +- Audits (Regular and Pre-Release) + - Run `scripts/audit.sh` regularly and before any release tag. + - Audit checks: governance compliance (gates, quiet policy), structure, .gitignore, CI parity, tests present. + - Record audits in `docs/audits/` and summarize in DevLogs. + +Branching & Releases (Recommended) +- Trunk-based development: + - `main` is protected, always green, production-ready. + - Short-lived branches by type: `feat/*`, `fix/*`, `chore/*`, `docs/*`, `ci/*`, `refactor/*`. + - Optional `next` only if batching risky work. +- Protections: required checks (audit + Docker tests), PRs required, Conventional Commits, linear history or squash. +- Tags: `YYYY-MM-DD-HHMM` for release-ready commits on `main` only. + +Repository Layout (Clean Start) +- collab/ — questions/, proposals/, plan/ (each step has `NN-.md` + `.llm.md`). +- docs/ — devlog/, audits/, architecture.md, feature docs, ADRs. +- prompts/ — `global/system.md` and `.llm.md` (canonical rules); modes/ live in `modes/`. +- modes/ — `/{mode.md, system.md?, defaults.yaml}`. +- templates/ — project scaffolding, including `_shared` with AGENTS.md, CI, docker, scripts. +- scripts/ — `test.sh`, `test.docker.sh`, `audit.sh`, `toolwrap.sh`. +- .gitea/ — workflows for CI. + +CodexHelper (Wrapper) — MVP Blueprint +- Goals + - Provide modes (global/mode/project prompts), project scaffolding, prompt composition, config precedence, and safe defaults around `codex`/`codex-cli`. +- CLI (subcommands) + - `new-mode` (repo-only): scaffold `modes//{mode.md, defaults.yaml, system.md?}`. + - `new-project` (outside repo): scaffold project structure (see below). + - `run` (outside repo): compose prompts and invoke codex, writing to `runs//`. +- Binary Detection + - `CODEX_BIN` env > `which codex` > `which codex-cli`; fail with a helpful message otherwise. +- Prompt Composition + - Order: Global system → Mode system overlay (optional) → Mode rules → Project narrative. +- Config Precedence (YAML + yq) + - global defaults < mode defaults < project config < ENV < CLI. +- Safety + - Require `--force` to overwrite; never run `git push` for user projects. +- Project Scaffolding (Generated Project Layout) + - `AGENTS.md` (from template) + - `prompts/project.md` (+ optional `prompts/style.md`) + - `prompts/_mode/` (read-only copies of global/mode prompts) + - `codex.yaml` (project settings) + - `codex.sh` (entrypoint to compose and call codex) + - `.gitea/workflows/ci.yml` (CI) + `docker/compose.yml` + `docker/test/Dockerfile` + - `scripts/test.sh` + `scripts/test.docker.sh` + `scripts/audit.sh` + - `.gitignore` (includes `runs/`) + - `runs/` (created on first run; ignored by VCS) + +Acceptance (Phase 1 “Crawl”) +- `new-mode` creates mode skeleton; refuses overwrites unless `--force`. +- `new-project` scaffolds all files above without overwrites; includes CI and Docker artifacts. +- `run` composes prompts in the right order and invokes the detected codex binary; artifacts under `runs//`. +- Config precedence enforced via yq. +- Guardrails: inside the helper repo only `new-mode` is allowed; elsewhere `new-project`/`run` allowed. +- Tests (bats or internal): cover CLI, guardrails, scaffolding, composition, precedence. +- CI: Gitea workflow executes audit and Docker-based tests; local Docker run mirrors CI. + +Start-From-Scratch Checklist (New Repo) +1) Commit clean skeleton: collab/, docs/, prompts/global/, templates/_shared, scripts/, .gitea/. +2) Add `NEWSTART.md` and `NEWSTART.llm.md` (this pair) and `docs/architecture.md`. +3) Begin with `collab/questions/00-bootstrap.{md,llm.md}`; do not proceed without “Approved for Proposal”. +4) Keep chat minimal; use toolwrap and DevLogs. Add audits early. +5) Implement Phase 1 via TDD, following Questions→Proposal→Plan gate for each subject. + +Notes +- This blueprint is the canonical source for repository setup and workflow. Keep it in sync with prompts/global/system.md. +