docs: v0.0.1 contains only NEWSTART artifacts
This commit is contained in:
18
NEWSTART.llm.md
Normal file
18
NEWSTART.llm.md
Normal file
@@ -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.
|
||||
|
||||
113
NEWSTART.md
Normal file
113
NEWSTART.md
Normal file
@@ -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 <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.
|
||||
|
||||
Reference in New Issue
Block a user