From ca8905fa4e7bf476d545bcd9c4710c261ae1f827 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 18:00:50 -0500 Subject: [PATCH] chore(repo): clean root and move docs - Move docs to docs/; keep areas for prompts only - Relocate Makefile to scripts/Makefile; update docs to use it - Move ci.Dockerfile to docker/ci.Dockerfile; update compose - Move commitlint config to .config and update hook - Remove root AGENTS.md (use area AGENTS.md) --- .../commitlint.config.cjs | 2 +- AGENTS.md | 7 ------ COMMON/README.md | 13 ----------- 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 ++++---- {COMMON => docs}/bootstrap-cicd.md | 8 +++---- {COMMON => docs}/docs-style.md | 2 +- {COMMON => docs}/git-workflow.md | 0 BOOTSTRAP.md => docs/history/BOOTSTRAP.md | 0 Makefile => scripts/Makefile | 6 ++--- scripts/commitlint-hook | 3 +-- 15 files changed, 61 insertions(+), 45 deletions(-) rename commitlint.config.cjs => .config/commitlint.config.cjs (73%) delete mode 100644 AGENTS.md delete mode 100644 COMMON/README.md 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%) rename {COMMON => docs}/bootstrap-cicd.md (68%) rename {COMMON => docs}/docs-style.md (79%) rename {COMMON => docs}/git-workflow.md (100%) rename BOOTSTRAP.md => docs/history/BOOTSTRAP.md (100%) 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/AGENTS.md b/AGENTS.md deleted file mode 100644 index fb7c502..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,7 +0,0 @@ -Agent Guidance (Repo Base) - -- Use area prompt packs generated under `dist/prompts/`: - - CTO: [dist/prompts/cto.md](dist/prompts/cto.md) - - COO: [dist/prompts/coo.md](dist/prompts/coo.md) -- To rebuild packs locally: `make prompts` (runs inside CI container). -- Keep prompts modular and concise; favor COMMON modules and minimal area deltas. diff --git a/COMMON/README.md b/COMMON/README.md deleted file mode 100644 index 95c7fe1..0000000 --- a/COMMON/README.md +++ /dev/null @@ -1,13 +0,0 @@ -COMMON - -Purpose -- Foundational, shared practices usable across projects. -- Opinionated but adaptable; intended as a base layer. - -Contents (initial) -- Git workflow: [COMMON/git-workflow.md](git-workflow.md) -- CI/bootstrap parity: [COMMON/bootstrap-cicd.md](bootstrap-cicd.md) -- Documentation style: [COMMON/docs-style.md](docs-style.md) - -Notes -- Keep content generic and reusable; project-specific overrides should live in the target repo. 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/COMMON/bootstrap-cicd.md b/docs/bootstrap-cicd.md similarity index 68% rename from COMMON/bootstrap-cicd.md rename to docs/bootstrap-cicd.md index 25ee240..79bc6e2 100644 --- a/COMMON/bootstrap-cicd.md +++ b/docs/bootstrap-cicd.md @@ -4,15 +4,15 @@ 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 -- `ci.Dockerfile` – builds the CI image with shellcheck, shfmt, hadolint, actionlint, yamllint, Node tools. +- `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 hooks-setup` -- Quick checks: `make quick` (format + lint) -- Full pass: `make check` (all phases) +- 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. diff --git a/COMMON/docs-style.md b/docs/docs-style.md similarity index 79% rename from COMMON/docs-style.md rename to docs/docs-style.md index 8904a31..745e0c9 100644 --- a/COMMON/docs-style.md +++ b/docs/docs-style.md @@ -1,6 +1,6 @@ Documentation Style Guide -- When referencing another Markdown file in this repo, use a relative link so it is clickable in Gitea. Example: [COMMON/git-workflow.md](COMMON/git-workflow.md). +- 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. 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/BOOTSTRAP.md b/docs/history/BOOTSTRAP.md similarity index 100% rename from BOOTSTRAP.md rename to docs/history/BOOTSTRAP.md 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}"