KNEL/ChatGPTScaffolding
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Files
v0.0.1
ChatGPTScaffolding/NEWSTART.md

6.8 KiB
Raw Permalink Blame History

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-<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.