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. + diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 75c00ee..983d778 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/docs/devlog/DEVLOG_LLM.md @@ -245,3 +245,10 @@ This log is concise and structured for quick machine parsing and summarization. - Updated system prompts and AGENTS templates to state quiet is required - next: - Continue with quiet operations and filesystem-first logging +## 2025-09-17T16:34Z +- context: Quiet tooling wrapper added; tool.log policy established +- actions: + - Added scripts/toolwrap.sh for quiet execution and failure logging to docs/devlog/tool.log + - Updated system prompts and AGENTS templates to use tool.log +- next: + - Use toolwrap for host-side orchestration commands to keep chat silent diff --git a/docs/devlog/tool.log b/docs/devlog/tool.log new file mode 100644 index 0000000..8c9e1c3 --- /dev/null +++ b/docs/devlog/tool.log @@ -0,0 +1,5 @@ +2025-09-17T16:40:06Z FAILURE: git add -A +--- STDOUT --- +--- STDERR --- +./scripts/toolwrap.sh: line 21: {git: command not found +-------------- diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 5e4b5bb..75d2d3f 100644 --- a/meta/AGENTS.seed.llm.md +++ b/meta/AGENTS.seed.llm.md @@ -5,7 +5,8 @@ - Read `.llm.md` only; write both `.md` and `.llm.md` siblings for collab artifacts. - Chat ≤5 lines; default “Updated …”; no diffs; announce only collab file changes; log details in `docs/devlog/`. - Quiet shell: avoid `cat`/`sed` outputs; use silent checks; log details to DevLog files. - - Quiet is mandatory (no toggle) for this tool. +- Quiet is mandatory (no toggle) for this tool. + - Tool logging: use quiet wrapper; log to `docs/devlog/tool.log` on failures; no chat output. - Keep changes minimal and focused; adopt TDD (tests first); require unit/integration tests for all features; consistent style. - Git: Conventional Commits; branch `main`; optional tags `YYYY-MM-DD-HHMM`. - Tools: file-first; use `rg`; read ≤250 lines; respect sandbox/approvals; preface grouped commands. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index 1dd413b..b26fced 100644 --- a/meta/AGENTS.seed.md +++ b/meta/AGENTS.seed.md @@ -39,7 +39,8 @@ Note: This is a template copied into generated projects. Customize as needed for - Keep chat ≤5 lines; no diffs or large pastes. - Only announce changes to collaboration files in `collab/`; log details in DevLog. - Quiet shell: avoid streaming file contents/diffs; prefer silent checks and log details to DevLog. - - Quiet is mandatory (no toggle) for this tool’s workflows. +- Quiet is mandatory (no toggle) for this tool’s workflows. + - Tool logging: use a quiet wrapper to log to `docs/devlog/tool.log` on failures; keep chat silent. ## Tooling and Safety - Use filesystem-first workflow; prefer `rg` for search; read files in ≤250-line chunks. diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md index d719aeb..1320bc7 100644 --- a/prompts/global/system.llm.md +++ b/prompts/global/system.llm.md @@ -52,4 +52,8 @@ -- Quiet Shell/No Streaming -- - Never stream file contents/diffs in chat. Avoid `cat`/`sed` outputs. - Use silent checks (exit codes, `grep -q`); log details in DevLog files. - - Quiet is mandatory (no toggle); default to minimal, non-chat output. +- Quiet is mandatory (no toggle); default to minimal, non-chat output. + +-- Tool Logging -- +- On success: no chat output; optional one-line summary to `docs/devlog/tool.log`. +- On failure (not sandbox): capture stdout/stderr and append to `docs/devlog/tool.log` with timestamp and command. diff --git a/prompts/global/system.md b/prompts/global/system.md index bf878ff..e498631 100644 --- a/prompts/global/system.md +++ b/prompts/global/system.md @@ -35,7 +35,12 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa - Do not stream file contents or diffs into chat. Avoid `cat`/`sed` output in chat. - Prefer silent checks (e.g., `grep -q`, exit codes) and write details to DevLog files if needed. - If content must be inspected, avoid printing it to chat; summarize findings in DevLog and reference the file. - - Quiet is mandatory (no toggle). Tools and scripts should default to minimal, non-chat output. +- Quiet is mandatory (no toggle). Tools and scripts should default to minimal, non-chat output. + +## Tool Logging (tool.log) +- On command success: do not print to chat; optionally append a one-line summary to `docs/devlog/tool.log`. +- On command failure (not sandbox failures): write full stdout/stderr to `docs/devlog/tool.log` with timestamp and command. +- Use a quiet wrapper script to enforce this behavior. ## Dev Logs and Docs - Maintain `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md`. Add an entry for each meaningful change. diff --git a/scripts/toolwrap.sh b/scripts/toolwrap.sh new file mode 100755 index 0000000..ac2d178 --- /dev/null +++ b/scripts/toolwrap.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Quiet command wrapper: +# - Runs the given command without emitting stdout/stderr to the console. +# - On success: prints nothing; logs an optional one-line summary to tool.log. +# - On failure: writes full stdout/stderr to tool.log and exits non-zero. + +log_file="docs/devlog/tool.log" +mkdir -p "$(dirname "$log_file")" + +ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; } + +cmd=("$@") + +# Capture stdout/stderr +out_file="$(mktemp)" +err_file="$(mktemp)" +rc=0 + +{"${cmd[@]}"} >"$out_file" 2>"$err_file" || rc=$? + +if [ "$rc" -eq 0 ]; then + echo "$(ts) SUCCESS: ${cmd[*]}" >> "$log_file" + rm -f "$out_file" "$err_file" + exit 0 +fi + +{ + echo "$(ts) FAILURE: ${cmd[*]}" + echo "--- STDOUT ---" + cat "$out_file" + echo "--- STDERR ---" + cat "$err_file" + echo "--------------" +} >> "$log_file" + +rm -f "$out_file" "$err_file" +exit "$rc" + diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md index e277e5e..8c4fcc8 100644 --- a/templates/project/_shared/AGENTS.md +++ b/templates/project/_shared/AGENTS.md @@ -20,7 +20,8 @@ This file is copied by scaffolding into new projects. Edit to suit the project w - Default: `Updated . Read/edit and let me know.` - Keep chat ≤5 lines; no diffs; announce only collab file changes; log details in DevLog. - Quiet shell: avoid printing file contents/diffs; prefer silent checks and DevLog summaries. - - Quiet is mandatory (no toggle) in this workflow. +- Quiet is mandatory (no toggle) in this workflow. + - Tool logging: prefer a quiet wrapper that logs to `docs/devlog/tool.log` on failures; keep chat silent. ## Coding, Tests, and Git - Minimal, focused changes; adopt TDD (write tests first) and require unit/integration tests for all features; consistent style.