# 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 <filepath>. 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-<subject>.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/ — `<ModeName>/{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/<Name>/{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/<ts>/`.
- 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/<timestamp>/`.
- 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.