diff --git a/CodexHelper/CodexHelper.sh b/CodexHelper/CodexHelper.sh new file mode 100755 index 0000000..45fee9b --- /dev/null +++ b/CodexHelper/CodexHelper.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +set -euo pipefail + +# CodexHelper.sh — minimal wrapper to invoke Codex CLI +# - Finds a codex binary (env `CODEX_BIN`, or `codex`, or `codex-cli`) +# - Uses the repository's prompts/system_prompt.md by default +# - Passes through any extra args to the codex binary + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="${SCRIPT_DIR}/.." +SYSTEM_PROMPT_PATH="${REPO_ROOT}/prompts/system_prompt.md" + +if [[ ! -f "${SYSTEM_PROMPT_PATH}" ]]; then + echo "Error: system prompt not found at ${SYSTEM_PROMPT_PATH}" >&2 + exit 1 +fi + +# Binary detection per NEWSTART.md guidance +if [[ -n "${CODEX_BIN:-}" ]]; then + BIN="${CODEX_BIN}" +elif command -v codex >/dev/null 2>&1; then + BIN="$(command -v codex)" +elif command -v codex-cli >/dev/null 2>&1; then + BIN="$(command -v codex-cli)" +else + echo "Error: Could not find codex binary. Set CODEX_BIN or install 'codex'/'codex-cli'." >&2 + exit 1 +fi + +# Try a common flag name for supplying a system prompt. Adjust if needed. +# Additional args are forwarded so callers can customize behavior. +exec "${BIN}" --system-prompt "${SYSTEM_PROMPT_PATH}" "$@" + diff --git a/NEWSTART.llm.md b/NEWSTART.llm.md deleted file mode 100644 index 514027e..0000000 --- a/NEWSTART.llm.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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 deleted file mode 100644 index 804b396..0000000 --- a/NEWSTART.md +++ /dev/null @@ -1,113 +0,0 @@ -# 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/prompts/system_prompt.md b/prompts/system_prompt.md new file mode 100644 index 0000000..58d45cb --- /dev/null +++ b/prompts/system_prompt.md @@ -0,0 +1,8 @@ +Dummy System Prompt (Test Only) + +Note: This is a temporary, demonstration-only system prompt used for testing the CodexHelper wrapper and repo scaffolding. We will iterate on the real system prompt in this session. + +Guidelines (placeholder): +- Be concise, safe, and helpful. +- Prefer actionable steps and clear next actions. +- Defer to repository AGENTS.md and user instructions.