From cd9653c66a67643c8df0c2cb2e8ea54d2db7adf4 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Thu, 11 Sep 2025 07:05:00 -0500 Subject: [PATCH] chore(repo): clean root; move docs; keep areas for prompts --- .../commitlint.config.cjs | 2 +- README.md | 22 ++++++++++++++++++- ci.Dockerfile => docker/ci.Dockerfile | 1 + docker/ci.compose.yml | 3 +-- docs/README.md | 15 +++++++++++++ RESUME.md => docs/RESUME.md | 15 +++++++------ TODO.md => docs/TODO.md | 9 ++++---- docs/bootstrap-cicd.md | 21 ++++++++++++++++++ docs/docs-style.md | 8 +++++++ {COMMON => docs}/git-workflow.md | 0 docs/history/BOOTSTRAP.md | 16 ++++++++++++++ Makefile => scripts/Makefile | 6 ++--- scripts/commitlint-hook | 3 +-- 13 files changed, 101 insertions(+), 20 deletions(-) rename commitlint.config.cjs => .config/commitlint.config.cjs (73%) rename ci.Dockerfile => docker/ci.Dockerfile (99%) create mode 100644 docs/README.md rename RESUME.md => docs/RESUME.md (73%) rename TODO.md => docs/TODO.md (73%) create mode 100644 docs/bootstrap-cicd.md create mode 100644 docs/docs-style.md rename {COMMON => docs}/git-workflow.md (100%) create mode 100644 docs/history/BOOTSTRAP.md rename Makefile => scripts/Makefile (82%) diff --git a/commitlint.config.cjs b/.config/commitlint.config.cjs similarity index 73% rename from commitlint.config.cjs rename to .config/commitlint.config.cjs index 3acb487..85f0985 100644 --- a/commitlint.config.cjs +++ b/.config/commitlint.config.cjs @@ -1,4 +1,4 @@ -module.exports = { +export default { extends: ['@commitlint/config-conventional'], }; diff --git a/README.md b/README.md index 6a07df4..ff9297c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,23 @@ # LLMScaffolding -TSYS Group LLM Scaffolding. We heavily utilize AI to produce software and other deliverables. \ No newline at end of file +Base scaffolding for AI‑assisted work. Clean root; docs in `docs/`; areas for prompts. + +Layout +- docs/ — human‑readable docs (getting started, workflow, CI, style) +- COMMON/ CTO/ COO/ CCO/ — questions, proposals, and prompt modules only +- scripts/ — Makefile and helper scripts +- docker/ — CI compose and Dockerfile +- dist/prompts/ — generated prompt packs (cto.md, coo.md) +- proposals/, questions/ — repository planning artifacts + +Quickstart +- Install hooks: `make -f scripts/Makefile hooks-setup` +- Run checks: `make -f scripts/Makefile check` +- Build prompt packs: `make -f scripts/Makefile prompts` + +Docs +- Git workflow: [docs/git-workflow.md](docs/git-workflow.md) +- Local CI parity: [docs/bootstrap-cicd.md](docs/bootstrap-cicd.md) +- Documentation style: [docs/docs-style.md](docs/docs-style.md) +- Operational notes: [docs/RESUME.md](docs/RESUME.md), [docs/TODO.md](docs/TODO.md) +- History: [docs/history/BOOTSTRAP.md](docs/history/BOOTSTRAP.md) diff --git a/ci.Dockerfile b/docker/ci.Dockerfile similarity index 99% rename from ci.Dockerfile rename to docker/ci.Dockerfile index 605d76f..54d49ff 100644 --- a/ci.Dockerfile +++ b/docker/ci.Dockerfile @@ -38,3 +38,4 @@ RUN npm --location=global install \ WORKDIR /workspace ENTRYPOINT ["bash","-lc"] CMD ["bash"] + diff --git a/docker/ci.compose.yml b/docker/ci.compose.yml index 6f370e7..88c10e8 100644 --- a/docker/ci.compose.yml +++ b/docker/ci.compose.yml @@ -2,7 +2,7 @@ services: ci: build: context: .. - dockerfile: ci.Dockerfile + dockerfile: docker/ci.Dockerfile working_dir: /workspace volumes: - "../:/workspace:Z" @@ -10,4 +10,3 @@ services: - IN_CI_CONTAINER=1 entrypoint: ["bash","-lc"] command: ["bash"] - diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..bab21ea --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +Repository Docs + +Purpose +- Centralize human‑readable documentation. Area folders (COMMON/CTO/COO/CCO) are reserved for questions, proposals, and prompt modules. + +Key Documents +- Git workflow: [git-workflow.md](git-workflow.md) +- Local CI parity: [bootstrap-cicd.md](bootstrap-cicd.md) +- Documentation style: [docs-style.md](docs-style.md) +- Operational notes: [RESUME.md](RESUME.md), [TODO.md](TODO.md) +- History: [history/BOOTSTRAP.md](history/BOOTSTRAP.md) + +Usage +- Make targets moved to `scripts/Makefile`. Use `make -f scripts/Makefile `. + diff --git a/RESUME.md b/docs/RESUME.md similarity index 73% rename from RESUME.md rename to docs/RESUME.md index 66629ee..1d1c17e 100644 --- a/RESUME.md +++ b/docs/RESUME.md @@ -16,12 +16,12 @@ Branches on remote - Start Docker Desktop/daemon as needed 3) Install hooks locally -- make hooks-setup +- make -f scripts/Makefile hooks-setup 4) Run local checks (Docker-only) -- git switch bootstrap && make quick && make build -- git switch bootstrap-cicd && make quick && make build -- Optional full pass: make check +- git switch bootstrap && make -f scripts/Makefile quick && make -f scripts/Makefile build +- git switch bootstrap-cicd && make -f scripts/Makefile quick && make -f scripts/Makefile build +- Optional full pass: make -f scripts/Makefile check 5) Open PRs (when branches are green locally) - bootstrap → integration: https://git.knownelement.com/KNEL/LLMScaffolding/pulls/new/bootstrap @@ -41,12 +41,13 @@ Branches on remote - git branch -f release main && git push -f origin release 8) Docs & parity -- Git workflow: [COMMON/git-workflow.md](COMMON/git-workflow.md) -- Local CI parity: [COMMON/bootstrap-cicd.md](COMMON/bootstrap-cicd.md) +- Git workflow: [docs/git-workflow.md](git-workflow.md) +- Local CI parity: [docs/bootstrap-cicd.md](bootstrap-cicd.md) 9) Defer CI enablement for two weeks -- Track in [TODO.md](TODO.md): Revisit enabling runners and protected checks on 2025-09-24 +- Track in [docs/TODO.md](TODO.md): Revisit enabling runners and protected checks on 2025-09-24 10) Next tasks - Answer any outstanding questions in questions/* - On approval, implement further proposals and update instructions/* + diff --git a/TODO.md b/docs/TODO.md similarity index 73% rename from TODO.md rename to docs/TODO.md index 422c69e..14f8b66 100644 --- a/TODO.md +++ b/docs/TODO.md @@ -3,7 +3,7 @@ TODO - Git workflow - [x] Questions gathered and answered - [x] Proposal iteration 2 drafted -- [x] Finalize approval and capture in [COMMON/git-workflow.md](COMMON/git-workflow.md) + - [x] Finalize approval and capture in [docs/git-workflow.md](git-workflow.md) - Branches - [x] Create integration, release, bootstrap from main @@ -12,9 +12,9 @@ TODO - CI/CD bootstrap - [x] Create branch bootstrap-cicd from main -- [x] Add questions at [questions/bootstrap-cicd.md](questions/bootstrap-cicd.md) + - [x] Add questions at [questions/bootstrap-cicd.md](../questions/bootstrap-cicd.md) - [x] Draft proposal based on answers - - [x] Implement parity tooling: scripts/ci, ci.Dockerfile, docker/ci.compose.yml + - [x] Implement parity tooling: scripts/ci, docker/ci.Dockerfile, docker/ci.compose.yml - [x] Add .gitea/workflows: ci.yml, release.yml, nightly.yml - [x] Add commitlint.config.cjs, Makefile - [ ] Optional: add .pre-commit-config.yaml (defer for now) @@ -31,4 +31,5 @@ TODO - [ ] Optional: fast-forward release branch to latest tag - Docs -- [ ] Write [docs/engineering/git-workflow.md](docs/engineering/git-workflow.md) with diagrams and examples + - [ ] Write [docs/engineering/git-workflow.md](engineering/git-workflow.md) with diagrams and examples + diff --git a/docs/bootstrap-cicd.md b/docs/bootstrap-cicd.md new file mode 100644 index 0000000..79bc6e2 --- /dev/null +++ b/docs/bootstrap-cicd.md @@ -0,0 +1,21 @@ +Local CI Parity & Bootstrap + +Purpose +- Provide a portable CI toolchain via a Dockerized image and compose file so that format/lint/build checks run identically locally and in CI. + +Components +- `docker/ci.Dockerfile` – builds the CI image with shellcheck, shfmt, hadolint, actionlint, yamllint, Node tools. +- `docker/ci.compose.yml` – runs the CI container mounting the repo at `/workspace`. +- `scripts/ci` – wrapper for phases: `format`, `lint`, `build`, `test`, `security`, `all`. +- Git hooks – `.githooks/*` installed via `scripts/setup-hooks`. + +Usage +- Install hooks: `make -f scripts/Makefile hooks-setup` +- Quick checks: `make -f scripts/Makefile quick` (format + lint) +- Full pass: `make -f scripts/Makefile check` (all phases) + +Notes +- Pre-commit hook runs format/lint and commit message checks. +- Pre-push hook runs build/test/security placeholders. +- CI workflow runs on integration and protected branches when runners are enabled. + diff --git a/docs/docs-style.md b/docs/docs-style.md new file mode 100644 index 0000000..745e0c9 --- /dev/null +++ b/docs/docs-style.md @@ -0,0 +1,8 @@ +Documentation Style Guide + +- When referencing another Markdown file in this repo, use a relative link so it is clickable in Gitea. Example: [docs/git-workflow.md](git-workflow.md). +- Keep titles concise and descriptive; use sentence case unless a proper noun. +- Prefer short bullets (one point per line). Merge related points. +- Use backticks for commands, file paths, env vars, and code identifiers. +- Make documents actionable: lead with outcomes, then steps, then background. + diff --git a/COMMON/git-workflow.md b/docs/git-workflow.md similarity index 100% rename from COMMON/git-workflow.md rename to docs/git-workflow.md diff --git a/docs/history/BOOTSTRAP.md b/docs/history/BOOTSTRAP.md new file mode 100644 index 0000000..5fc550c --- /dev/null +++ b/docs/history/BOOTSTRAP.md @@ -0,0 +1,16 @@ +The purpose of this repository is to create a re-usable set of prompts for use in AI chat intefaces and with agentic AI. + +This file is being created at the very start of the repository in an attempt to provide full traceability. It will be passed to codex as a prompt. + +Codex instructions: + +- Remain in planning mode only. Ask questions and gather data. +- Create a propsoals directory and write out proposals to it for me to review and approve. +- Do not undertake any work unless I ask you for a proposal and I approve the proposal. +- Ask questions with numbers and allow them to be answered like 1:y 2:n or (for multiple choice) 1:a 2:b and so forth. +- Keep the chat message output short. Use proposal files that I can view in my editor (vsCode). +- The directory you are in is one level up from the git repository. This is so that git worktree can be used, to help mitigate issues with git branching. The repository is in a child directory called LLMScaffolding. + +Your first concreate action: +- Please help me establish a git workflow (via the proposal/approval process I have outlined). This workflow should follow best practices, it should presume the use of CI/CD via Gitea (Gitlab/Github are banned, never produce anything for those platforms). + diff --git a/Makefile b/scripts/Makefile similarity index 82% rename from Makefile rename to scripts/Makefile index 817c8db..3fed0e6 100644 --- a/Makefile +++ b/scripts/Makefile @@ -1,6 +1,6 @@ SHELL := /usr/bin/env bash -.PHONY: all check quick format lint build test security ci-image hooks-setup +.PHONY: all check quick format lint build test security ci-image hooks-setup prompts prompts-check all: check @@ -26,14 +26,14 @@ security: ./scripts/ci security ci-image: - docker build -f ci.Dockerfile -t local/ci:latest . + docker build -f docker/ci.Dockerfile -t local/ci:latest . hooks-setup: ./scripts/setup-hooks -.PHONY: prompts prompts-check prompts: ./scripts/prompts all prompts-check: ./scripts/prompts lint + diff --git a/scripts/commitlint-hook b/scripts/commitlint-hook index 021f21c..6c4786e 100755 --- a/scripts/commitlint-hook +++ b/scripts/commitlint-hook @@ -6,5 +6,4 @@ MSG_FILE="${1:-.git/COMMIT_EDITMSG}" # Run commitlint inside the CI container against the commit message file docker compose -f docker/ci.compose.yml run --rm \ -e IN_CI_CONTAINER=1 \ - ci bash -lc "commitlint --edit ${MSG_FILE}" - + ci bash -lc "commitlint --config .config/commitlint.config.cjs --edit ${MSG_FILE}"