docs(changelog): add CHANGELOG.md and link from docs index

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

.config/commitlint.config.cjs

@@ -0,0 +1,4 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+};
+

.gitea/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+    branches: ["**"]
+  push:
+    branches: ["integration", "bootstrap", "bootstrap-cicd"]
+
+jobs:
+  checks:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build CI image
+        run: docker build -f ci.Dockerfile -t local/ci:latest .
+
+      - name: Lint
+        run: docker run --rm -v ${{ github.workspace }}:/workspace local/ci:latest bash -lc "cd /workspace && IN_CI_CONTAINER=1 scripts/ci lint"
+
+      - name: Build validation
+        run: docker run --rm -v ${{ github.workspace }}:/workspace local/ci:latest bash -lc "cd /workspace && IN_CI_CONTAINER=1 scripts/ci build"
+

.gitea/workflows/nightly.yml

@@ -0,0 +1,19 @@
+name: Nightly
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+
+jobs:
+  report:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build CI image
+        run: docker build -f ci.Dockerfile -t local/ci:latest .
+
+      - name: Lint (nightly)
+        run: docker run --rm -v ${{ github.workspace }}:/workspace local/ci:latest bash -lc "cd /workspace && IN_CI_CONTAINER=1 scripts/ci lint"
+

.gitea/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    branches: ["main"]
+
+jobs:
+  tag-and-notes:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build CI image
+        run: docker build -f ci.Dockerfile -t local/ci:latest .
+
+      - name: Compute tag
+        id: tag
+        run: |
+          TZ=UTC date +"v%Y.%m.%d-%H%M" > tag.txt
+          echo "tag=$(cat tag.txt)" >> $GITHUB_OUTPUT
+
+      - name: Create annotated tag
+        run: |
+          git config user.name "ci"
+          git config user.email "ci@local"
+          git tag -a ${{ steps.tag.outputs.tag }} -m "Release ${{ steps.tag.outputs.tag }}"
+          git push origin ${{ steps.tag.outputs.tag }}
+

.githooks/commit-msg

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+scripts/commitlint-hook "$1"
+

.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "> pre-commit: format + lint + commit message check"
+
+# Run format and lint inside the CI container
+scripts/ci format
+scripts/ci lint
+
+echo "pre-commit completed."
+

.githooks/pre-push

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "> pre-push: build validation + placeholders for tests/security"
+
+scripts/ci build
+scripts/ci test
+scripts/ci security
+
+echo "pre-push completed."
+

CCO/.gitkeep

@@ -0,0 +1 @@
+

CODEOWNERS

@@ -0,0 +1,5 @@
+# Prompt packs
+COMMON/prompt/**   @reachableceo
+CTO/**             @reachableceo
+COO/**             @reachableceo
+

COMMON/prompt/manifests/base.yaml

@@ -0,0 +1,9 @@
+name: COMMON base v1
+modules:
+  - COMMON/prompt/modules/system-persona.md
+  - COMMON/prompt/modules/style.md
+  - COMMON/prompt/modules/safety.md
+  - COMMON/prompt/modules/tools-codex-cli.md
+  - COMMON/prompt/modules/planning.md
+  - COMMON/prompt/modules/execution.md
+  - COMMON/prompt/modules/repo-conventions.md

COMMON/prompt/manifests/coo.yaml

@@ -0,0 +1,4 @@
+name: COO pack v1
+include:
+  - COMMON/prompt/manifests/base.yaml
+modules: []

COMMON/prompt/manifests/cto.yaml

@@ -0,0 +1,4 @@
+name: CTO pack v1
+include:
+  - COMMON/prompt/manifests/base.yaml
+modules: []

COMMON/prompt/modules/execution.md

@@ -0,0 +1,9 @@
+Execution Principles
+
+- Solve the user’s request end‑to‑end before yielding.
+- Prefer root‑cause fixes over surface patches.
+- Keep changes minimal and aligned with existing style.
+- Avoid fixing unrelated issues; mention them briefly if relevant.
+- After changes, run focused validation; expand scope only as needed.
+- Summarize results clearly with next actions or options.
+

COMMON/prompt/modules/planning.md

@@ -0,0 +1,12 @@
+Planning and Checkpoints
+
+- When work spans multiple steps or has ambiguity, write a brief plan.
+- Steps are 1 sentence, action‑oriented, and verifiable.
+- Keep exactly one `in_progress` step; mark completed before moving on.
+- Update the plan when reality changes; add rationale for plan changes.
+- Don’t pad trivial tasks with plans.
+
+Progress updates
+- For longer tasks, share concise updates (≤10 words) before heavy work.
+- State what’s done, what’s next, and any blockers.
+

COMMON/prompt/modules/repo-conventions.md

@@ -0,0 +1,9 @@
+Repo Conventions (This Base)
+
+- Use `apply_patch` for edits; don’t commit or branch unless asked.
+- No license headers unless explicitly requested.
+- No one‑letter variable names; no inline code comments unless asked.
+- Keep filenames and structure stable; avoid renames unless necessary.
+- Don’t re‑read files after an edit; the tool confirms success.
+- Never output broken inline citations; prefer clickable filepaths.
+

COMMON/prompt/modules/safety.md

@@ -0,0 +1,9 @@
+Safety and Guardrails
+
+- Don’t execute destructive actions without explicit instruction.
+- When unsure, ask targeted questions before acting.
+- Respect confidentiality; don’t expose secrets or guess credentials.
+- Validate assumptions with quick, cheap checks before heavy work.
+- Prefer reversible changes; keep diffs minimal and focused.
+- Surface limitations (permissions, sandbox, network) and offer alternatives.
+

COMMON/prompt/modules/style.md

@@ -0,0 +1,16 @@
+Style and Formatting Rules
+
+- Use short, imperative sentences. Avoid hedging.
+- Prefer bullets with one point per line.
+- Wrap commands, paths, env vars, and code identifiers in backticks.
+- Use section headers only when they improve scanability.
+- Keep lists to 4–6 bullets; merge related points.
+- Default to present tense; active voice.
+- For multi‑step work, summarize outcomes and next actions.
+- Never output ANSI codes. Avoid decorative formatting.
+
+Outputs must be self‑contained
+- Don’t reference “above/below”.
+- Include minimal context necessary to act.
+- Call out assumptions explicitly.
+

COMMON/prompt/modules/system-persona.md

@@ -0,0 +1,18 @@
+System Persona
+
+You are an engineering partner: concise, direct, and pragmatic with a healthy skepticism. You optimize for:
+- Actionable guidance over exposition. State assumptions and next steps.
+- Minimal context usage. Prefer modular prompts and small, composable chunks.
+- Safety and correctness. Don’t guess; ask when uncertain.
+
+Tone and behavior
+- Friendly but no fluff. Use active voice and present tense.
+- Default to brief bullets. Keep lists short and ordered by importance.
+- Provide rationale only when it informs action.
+- Call out risks, edge cases, and trade‑offs explicitly.
+
+Boundaries
+- Do not invent facts about the codebase or environment.
+- If a step could mutate state, confirm intent or simulate when unclear.
+- Escalate ambiguity with targeted questions; avoid open‑ended queries.
+

COMMON/prompt/modules/tools-codex-cli.md

@@ -0,0 +1,19 @@
+Environment and Tools (Codex CLI)
+
+- Shell usage
+  - Prefer `rg` for search and `sed -n` with 250‑line chunks.
+  - Print concise preambles before tool calls; group related actions.
+  - Use `apply_patch` for file edits; avoid unrelated changes.
+
+- Planning
+  - Use `update_plan` for multi‑step tasks; keep steps short (≤7 words).
+  - Exactly one step `in_progress` until done; mark completion as you go.
+
+- Approvals and sandbox
+  - Assume workspace‑write, network enabled, approvals on‑request unless told otherwise.
+  - Request escalation only when necessary (network installs, destructive ops).
+
+- Validation
+  - Run targeted checks for changed areas; escalate to broader tests as confidence grows.
+  - Don’t add formatters or miscellaneous tooling unless requested.
+

COMMON/proposals/bootstrap-cicd.md

@@ -0,0 +1,68 @@
+**Bootstrap CI/CD Proposal (Phase 1)**
+
+- Scope: Local developer parity via Docker-first tooling and hooks, minimal CI placeholders (no runners required yet). Applies to this repo (docs/scripts/docker-compose), with an easy path to template for others.
+
+**Checks To Implement Now (Local via Docker)**
+
+- Stacks: shell, Dockerfiles/Compose, Markdown/Docs, YAML; Python/Node optional later.
+- Formatters/Linters:
+  - shell: shfmt + shellcheck
+  - docker: hadolint
+  - markdown: markdownlint + prettier
+  - yaml: yamllint + actionlint (for workflows)
+- Tests: none for now (lint-only baseline).
+- Security: skip for this repo now.
+
+**Execution Model**
+
+- Docker-only: all checks run inside a pinned `ci` image. Host only orchestrates Docker/Compose.
+- Single entrypoint: `scripts/ci` with phases: `format`, `lint`, `build` (compose validate), `test` (no-op for now), `security` (no-op), `all`.
+- Compose file: `docker/ci.compose.yml` defines `ci` service that mounts repo and executes `scripts/ci <phase>`.
+
+**Hooks Parity**
+
+- Provide Git hooks via pre-commit framework and native Git hooks:
+  - pre-commit: run `format`, `lint`, and commit message check (Conventional Commits).
+  - pre-push: run `build` (compose config validation) and keep `test`/`security` as no-ops for now.
+- Commit message style: Conventional Commits via `commitlint` rule-set; enforce in CI later and locally via `commit-msg` hook.
+
+**Minimal CI (Deferred Enablement)**
+
+- Workflows will be prepared but can stay disabled until runners are available:
+  - `.gitea/workflows/ci.yml`: mirrors local `lint` + `build` using the same `ci` image; triggered on PRs when enabled.
+  - `.gitea/workflows/release.yml`: on `main` merges, tags with `vYYYY.MM.DD-HHMM` and (optionally) creates release notes; can be enabled later.
+  - `.gitea/workflows/nightly.yml`: scheduled dependency/lint refresh; optional for later.
+- All jobs execute inside the `ci` container image; no host package installs.
+
+**Caching & Matrix**
+
+- Matrix: single Linux image for now.
+- Caching: enable Docker layer cache when CI runners are available; no special local caching required.
+
+**Concurrency & Timeouts (defaults for later)**
+
+- Cancel in-progress on same ref: enabled for PRs.
+- Job timeout: 30 minutes.
+
+**Protected Check Names (for later enforcement)**
+
+- `ci / lint`, `ci / build`, `ci / commitlint`. Tests/Security can be added when introduced.
+
+**Files To Add (upon approval)**
+
+- `scripts/ci` (bash) — phases and Docker/host detection (host executes Docker only).
+- `ci.Dockerfile` — pinned versions: shfmt, shellcheck, hadolint, yamllint, markdownlint-cli, prettier, actionlint, commitlint.
+- `docker/ci.compose.yml` — `ci` service to run checks.
+- `.pre-commit-config.yaml` — wire to `scripts/ci` phases; enable `commit-msg` hook for commitlint.
+- `commitlint.config.cjs` — Conventional Commits rules.
+- `.gitea/workflows/ci.yml`, `release.yml`, `nightly.yml` — prepared but can be disabled until runners are ready.
+- `Makefile` — `check`, `quick`, `lint`, `format`, `build` targets mapping to scripts.
+
+**Rollout Plan**
+
+1) Implement local tooling and hooks on `bootstrap-cicd`.
+2) Document quickstart in [docs/engineering/ci-cd.md](docs/engineering/ci-cd.md).
+3) Later: enable Gitea workflows when runners are ready; add protected checks.
+4) Optionally expand with tests/security scanners and language stacks per repo.
+
+If this matches your intent, I will scaffold the above on `bootstrap-cicd` and then capture the finalized process in [COMMON/bootstrap-cicd.md](COMMON/bootstrap-cicd.md).

COMMON/questions/bootstrap-cicd.md

@@ -0,0 +1,110 @@
+Bootstrap CI/CD – Questions
+
+Goal: define initial CI/CD checks and local Docker-parity hooks for this repo (docs/site, scripts, docker-compose), and a template usable by other repos.
+
+Answer style: short codes + notes, e.g. `1:a,c 2:b 3:docker`.
+
+1) Stacks present now (select all):
+   - a) Shell scripts
+   - b) Dockerfiles/Compose
+   - c) Markdown/Docs
+   - d) YAML (workflows/config)
+   - e) Python
+   - f) Node/JS
+   - g) Other (specify)
+
+   a,b,c,d potentially e. 
+
+2) Formatters/linters per stack:
+   - shell: a) shfmt b) shellcheck c) both
+   - docker: a) hadolint
+   - markdown: a) markdownlint b) prettier c) both
+   - yaml: a) yamllint b) actionlint (for workflows) c) both
+   - python (if used): a) black b) ruff c) pytest (tests)
+   - node (if used): a) eslint b) prettier c) jest (tests)
+   
+   shell: c
+   docker: a
+   markdown: c
+   yaml: c
+
+   I will leave python/node testing up to you. It isn't needed for this repo unless you create python scripts at some point.
+
+3) Testing scope now:
+   - a) none (docs/scripts only)
+   - b) smoke tests for scripts (bats/pytest-sh)
+   - c) unit tests for scripts (specify framework)
+
+   A (other then linting)
+
+4) Security scanning:
+   - a) trivy fs
+   - b) grype
+   - c) bandit (python)
+   - d) npm audit (node)
+   - e) skip for this repo
+
+   e
+
+5) Execution environment for CI:
+   - a) run inside repo’s `ci.Dockerfile`
+   - b) run on runner host with packages
+   - c) mix (specify)
+
+   All execution MUST be done in docker containers. Absolutely no work must be done on the host beyond git operations and docker orchestration.
+
+6) Matrix needs (now):
+   - a) none (single Linux image)
+   - b) multiple language versions (specify)
+   - c) OS matrix (Linux only for now?)
+
+   Um. I don't know. I think just a simle Linux environment can be assumed? 
+
+7) Caching:
+   - a) enable tool caches (pip/npm) in CI
+   - b) enable Docker layer cache
+   - c) none
+
+   I guess docker layer cache? It will be two weeks before I'm working on software (and therefore setup gitea CI runners etc). 
+
+8) Check names to protect on branches (final labels):
+   - a) ci / lint
+   - b) ci / test
+   - c) ci / build
+   - d) ci / security
+   - e) ci / commitlint
+
+   I don't know, leave it up to you
+
+9) Hooks parity:
+   - pre-commit: run format+lint+commitlint? (y/n) y
+   - pre-push: run test+build+security (fast profile)? (y/n) y
+
+10) Concurrency & timeouts:
+   - cancel in-progress on new commits to same PR? (y/n)
+   - default job timeout (minutes)?
+
+11) Release flow details:
+   - generate release notes from merged PRs since last tag? (y/n)
+   - attach built artifacts (site tarball, etc)? (y/n)
+
+12) Coverage gates (if tests exist):
+   - threshold % to require? (number or skip)
+
+13) Auto-merge bot to `integration`:
+   - bot account/name (or use Gitea built-in)?
+   - automerge conditions beyond green checks? (labels, size)
+
+14) Notifications:
+   - a) none
+   - b) email
+   - c) webhook/Chat (specify)
+
+15) Future extensibility:
+   - template these workflows for other repos? (y/n)
+   - segregate language-specific jobs behind conditions? (y/n)
+
+Notes: add any constraints about runners, container registry, or build tools.
+
+
+Lets just ignore all things CI for now? I'm brand new to CI. Use your best judgement/adopt best practices and/or ignore CI as needed. Do track that it's an outstanding item to go in depth on though. I don't want it to block moving forward with the dozen or so docs repos I need to use this LLM workflow with though.

COO/.gitkeep

@@ -0,0 +1 @@
+

COO/AGENTS.md

@@ -0,0 +1,12 @@
+COO Agent Pack
+
+Use the generated pack for agents: [dist/prompts/coo.md](dist/prompts/coo.md).
+
+Includes (via COMMON base):
+- System persona, style, safety
+- Codex CLI environment and tools
+- Planning and execution principles
+- Repo conventions
+
+Notes
+- COO currently uses only COMMON; area‑specific content will be added later.

CTO/.gitkeep

@@ -0,0 +1 @@
+

CTO/AGENTS.md

@@ -0,0 +1,12 @@
+CTO Agent Pack
+
+Use the generated pack for agents: [dist/prompts/cto.md](dist/prompts/cto.md).
+
+Includes (via COMMON base):
+- System persona, style, safety
+- Codex CLI environment and tools
+- Planning and execution principles
+- Repo conventions
+
+Notes
+- Keep CTO‑specific additions minimal; prefer COMMON as source of truth.

README.md

@@ -1,3 +1,23 @@
 # LLMScaffolding
 
-TSYS Group LLM Scaffolding. We heavily utilize AI to produce software and other deliverables.
+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
+- CTO/dist/prompts/ and COO/dist/prompts/ — generated prompt packs
+- COMMON/proposals/, COMMON/questions/ — 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)

docker/ci.Dockerfile

@@ -0,0 +1,41 @@
+FROM debian:12-slim
+
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates curl git bash coreutils findutils file python3 python3-pip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install shfmt, hadolint, actionlint (static), shellcheck, yamllint, node tools
+RUN set -eux; \
+    # shellcheck
+    apt-get update && apt-get install -y --no-install-recommends shellcheck && rm -rf /var/lib/apt/lists/*; \
+    # shfmt
+    SHFMT_VER=3.7.0; curl -fsSL -o /usr/local/bin/shfmt https://github.com/mvdan/sh/releases/download/v${SHFMT_VER}/shfmt_v${SHFMT_VER}_linux_amd64 && chmod +x /usr/local/bin/shfmt; \
+    # hadolint
+    HADOLINT_VER=2.12.0; curl -fsSL -o /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VER}/hadolint-Linux-x86_64 && chmod +x /usr/local/bin/hadolint; 
+
+# actionlint
+RUN set -eux; \
+    AL_VER=1.7.1; \
+    curl -fsSL -o /usr/local/bin/actionlint https://github.com/rhysd/actionlint/releases/download/v${AL_VER}/actionlint_${AL_VER}_linux_amd64.tar.gz; \
+    tar -C /usr/local/bin -xzf /usr/local/bin/actionlint; \
+    rm -f /usr/local/bin/actionlint
+
+# yamllint via pip (allow install on Debian's externally-managed Python)
+RUN pip3 install --break-system-packages --no-cache-dir yamllint==1.35.1
+
+# Node + npm for prettier, markdownlint, commitlint
+RUN set -eux; \
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get update && apt-get install -y --no-install-recommends nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN npm --location=global install \
+    prettier@3.3.3 \
+    markdownlint-cli@0.39.0 \
+    @commitlint/cli@19.5.0 @commitlint/config-conventional@19.5.0
+
+WORKDIR /workspace
+ENTRYPOINT ["bash","-lc"]
+CMD ["bash"]
+

docker/ci.compose.yml

@@ -0,0 +1,12 @@
+services:
+  ci:
+    build:
+      context: ..
+      dockerfile: docker/ci.Dockerfile
+    working_dir: /workspace
+    volumes:
+      - "../:/workspace:Z"
+    environment:
+      - IN_CI_CONTAINER=1
+    entrypoint: ["bash","-lc"]
+    command: ["bash"]

docs/CHANGELOG.md

@@ -0,0 +1,12 @@
+Changelog
+
+v0.0.1-Bootstrap — 2025-09-11
+- Clean root: only README/LICENSE, allowed dotfiles, and directories.
+- Docs consolidated under docs/ with clickable links.
+- COMMON/CTO/COO/CCO reserved for prompts, questions, and proposals.
+- Modular prompt packs: COMMON base + area manifests; packs in CTO/dist/prompts and COO/dist/prompts.
+- CI image at docker/ci.Dockerfile; compose at docker/ci.compose.yml.
+- Make targets in scripts/Makefile; hooks installed via scripts/setup-hooks.
+- Commitlint config in .config/commitlint.config.cjs; hook updated.
+- Tags/releases reset to this baseline; previous tags removed.
+

docs/DISCUSS.md

@@ -0,0 +1,42 @@
+DISCUSSION – Areas, Structure, Ownership
+
+Context
+- This repo hosts generic, foundational practices reusable across projects.
+- Areas: COMMON (shared practices), CTO (shared technical standards), COO (business ops), CCO (deferred; placeholder only).
+
+Decisions Confirmed
+- Area directories are uppercase: COMMON, CTO, COO, CCO.
+- Shared practices and base guidance live under COMMON.
+- CCO is deferred for now; placeholder directory only.
+
+Open Questions to Confirm
+- Naming conventions within areas
+  - File naming: keep kebab-case (e.g., [COMMON/git-workflow.md](COMMON/git-workflow.md)) or use TitleCase?
+  - Per-area `README.md` vs. `INDEX.md` expectations.
+- Scope boundaries
+  - COMMON: include Git workflow, CI/bootstrap parity, templates (PR/issue), documentation style guide, ADR pattern, security/privacy baselines?
+  - CTO: preferred tech stacks, language/runtime versions, container base image policy, local dev environment patterns (devcontainers/Make), testing strategy, quality bars?
+  - COO: operating rhythm (cadences, ceremonies), roles/RACI, OKR/KPI templates, onboarding, procurement/vendor-lite guidance, documentation templates?
+  - CCO: when in scope, include customer journey templates, support/SLA baselines, enablement playbooks, feedback loops? Any overlap rules with COO/CTO?
+- Consumers and audience
+  - Internal only or some content public-facing? Any confidentiality/compliance constraints (esp. COO/CCO)?
+- Reuse strategy
+  - Copy into new repos vs. reference centrally? Provide “adoption guides” per area? Offer minimal vs. advanced profiles?
+- Ownership & change control
+  - CODEOWNERS per area? Who approves updates across COMMON/CTO/COO?
+  - Labels and PR templates per area; contribution guidelines?
+- Document shape and standards
+  - Prescriptive checklists vs. narrative guidance; include “10-minute quickstart” per area?
+  - Standardize front‑matter, headers, and ADR structure?
+- Cross‑cutting policies
+  - Where to maintain shared policies (security, privacy, accessibility) — under COMMON?
+- CI for docs
+  - Keep current markdown/yaml linters repo‑wide; add link checker/spellcheck?
+- Migration of existing docs
+  - Which existing files beyond Git workflow and CI bootstrap should move under COMMON now vs. later (e.g., proposals, questions, [RESUME.md](RESUME.md), [TODO.md](TODO.md))?
+
+Proposed Next Steps (pending answers)
+- Seed per‑area README with scope, audiences, adoption guidance.
+- Create COMMON/templates/ for reusable checklists, PR/issue templates, ADRs.
+- Map/move additional shared docs into COMMON and update references.
+- Define CODEOWNERS and contribution norms per area.

docs/README.md

@@ -0,0 +1,16 @@
+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)
+ - Changelog: [CHANGELOG.md](CHANGELOG.md)
+ - Weekly recap: [RECAP-2025-09-11.md](RECAP-2025-09-11.md)
+
+Usage
+- Make targets moved to `scripts/Makefile`. Use `make -f scripts/Makefile <target>`.

docs/RECAP-2025-09-11.md

@@ -0,0 +1,58 @@
+Weekly Recap – 2025-09-11
+
+Scope
+- Capture of structural, CI, and prompt‑system work to resume quickly next week.
+
+Highlights
+- Clean root policy enforced: only `README.md`, `LICENSE`, allowed dotfiles, and directories.
+- Docs consolidated under `docs/` with clickable relative links.
+- Areas (COMMON/CTO/COO/CCO) reserved for prompts, questions, and proposals.
+- Modular prompt packs: COMMON modules + CTO/COO manifests; builder runs in container with host fallback.
+- CI image moved to `docker/ci.Dockerfile`; compose updated.
+- Make targets moved to `scripts/Makefile`.
+- Commitlint config moved to `.config/commitlint.config.cjs`; hook updated.
+- Baseline tag and release: `v0.0.1-Bootstrap` from current main; all other tags/releases removed.
+
+Current Layout (top‑level)
+- docs/ — human docs ([README](README.md), [git‑workflow](git-workflow.md), [bootstrap‑cicd](bootstrap-cicd.md), [docs‑style](docs-style.md), [RESUME](RESUME.md), [TODO](TODO.md), [DISCUSS](DISCUSS.md), history)
+- COMMON/ — prompts ([prompt/*]), questions ([../COMMON/questions](../COMMON/questions/)), proposals ([../COMMON/proposals](../COMMON/proposals/))
+- CTO/ — [AGENTS.md](../CTO/AGENTS.md), packs in [CTO/dist/prompts](../CTO/dist/prompts)
+- COO/ — [AGENTS.md](../COO/AGENTS.md), packs in [COO/dist/prompts](../COO/dist/prompts)
+- docker/ — compose + CI Dockerfile
+- scripts/ — Makefile, hooks, CI, prompts builder
+
+Prompt System
+- Modules in `COMMON/prompt/modules/*` (persona, style, safety, tools, planning, execution, repo‑conventions)
+- Manifests in `COMMON/prompt/manifests/*` (base, cto, coo)
+- Packs built to `CTO/dist/prompts/cto.md` and `COO/dist/prompts/coo.md`
+- Builder: `scripts/prompts` calls `scripts/prompt_build.py`
+  - Runs inside CI container; falls back to host if container stdout is empty
+  - No PyYAML dependency (minimal manifest parser)
+
+CI/Tooling
+- CI Dockerfile at `docker/ci.Dockerfile` (shellcheck, shfmt, hadolint, actionlint, yamllint, prettier/markdownlint/commitlint)
+- Compose at `docker/ci.compose.yml` mounts repo at `/workspace`
+- Hooks via `scripts/setup-hooks`; pre‑commit (format/lint/commitlint), pre‑push (build/test/security)
+- `scripts/ci` detaches stdin for container runs to avoid pre‑push stdin issues
+
+Git Workflow (recap)
+- Protect `main` and `release/*`; leave `integration` unprotected (auto‑merge on green once runners enabled)
+- See [docs/git‑workflow.md](git-workflow.md)
+
+Tags/Releases
+- Present: `v0.0.1-Bootstrap` only (current clean baseline)
+- Removed: v0.0.2/3/4/5 and their releases
+
+Next Steps (recommended)
+- Enable Gitea Actions runner; add protected checks on `main`/`release/*`; auto‑merge for PRs into `integration`
+- Optionally add link checker/spellcheck to prompts/docs
+- Seed CTO/COO area‑specific modules (small deltas from COMMON)
+- Consider docs/CHANGELOG.md; for now, this recap is the source
+
+Quick Resume Checklist
+1) Pull: `git fetch --all --prune && git switch main && git pull`
+2) Install hooks: `make -f scripts/Makefile hooks-setup`
+3) Rebuild packs: `make -f scripts/Makefile prompts`
+4) Run checks: `make -f scripts/Makefile check`
+5) Start with [docs/DISCUSS.md](DISCUSS.md) and [docs/TODO.md](TODO.md)
+

docs/RESUME.md

@@ -0,0 +1,52 @@
+Resume Guide
+
+Purpose
+- Quick checklist to pick up work after restarting Codex CLI with expanded permissions.
+
+Branches on remote
+- main (default), integration, release, bootstrap, bootstrap-cicd
+
+1) Pull latest
+- git fetch --all --prune
+- git switch bootstrap && git pull
+- git switch bootstrap-cicd && git pull
+- git switch integration && git pull
+
+2) Ensure Docker is available
+- Start Docker Desktop/daemon as needed
+
+3) Install hooks locally
+- make -f scripts/Makefile hooks-setup
+
+4) Run local checks (Docker-only)
+- 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
+- bootstrap-cicd → integration: https://git.knownelement.com/KNEL/LLMScaffolding/pulls/new/bootstrap-cicd
+
+6) Merge to integration
+- Use squash merge, allow auto-merge on green where configured
+
+7) Release to main
+- Open PR: integration → main (require 1 approval)
+- After merge, tag manually (until CI runners are enabled):
+  - git switch main && git pull
+  - TAG=$(date -u +"v%Y.%m.%d-%H%M")
+  - git tag -a "$TAG" -m "Release $TAG"
+  - git push origin "$TAG"
+- Optional: fast-forward release branch pointer:
+  - git branch -f release main && git push -f origin release
+
+8) Docs & parity
+- 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 [docs/TODO.md](TODO.md): Revisit enabling runners and protected checks on 2025-09-24
+
+10) Next tasks
+- Answer any outstanding questions in COMMON/questions/*
+- On approval, implement further proposals and update instructions/*

docs/TODO.md

@@ -0,0 +1,35 @@
+TODO
+
+- Git workflow
+  - [x] Questions gathered and answered
+  - [x] Proposal iteration 2 drafted
+  - [x] Finalize approval and capture in [docs/git-workflow.md](git-workflow.md)
+
+- Branches
+  - [x] Create integration, release, bootstrap from main
+  - [x] Push bootstrap to origin
+  - [ ] Decide whether to maintain a fast-forwarded release branch to the latest tag
+
+- CI/CD bootstrap
+  - [x] Create branch bootstrap-cicd from main
+  - [x] Add questions at [COMMON/questions/bootstrap-cicd.md](../COMMON/questions/bootstrap-cicd.md)
+  - [x] Draft proposal based on answers
+  - [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)
+  - [ ] Optional: add CODEOWNERS
+
+- Protections & settings (in Gitea UI)
+  - [ ] Protect main and release/* with required checks
+  - [ ] Leave integration unprotected; allow auto-merge on green
+  - [ ] Require 1 approval for integration→main
+  - [ ] Revisit enabling CI and protections after runners are ready (target: 2025-09-24)
+
+- Releases
+  - [ ] Tag format vYYYY.MM.DD-HHMM (UTC) in release workflow
+  - [ ] Optional: fast-forward release branch to latest tag
+
+- Docs
+  - [ ] Write [docs/engineering/git-workflow.md](engineering/git-workflow.md) with diagrams and examples
+

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

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

docs/git-workflow.md

@@ -0,0 +1,38 @@
+Git Workflow – Finalized Instructions
+
+Scope
+- Applies across projects. Contributors work via branches/PRs. CI/CD is Gitea‑native.
+
+Branches
+- main: production; default branch. Protected.
+- integration: development (unprotected; merges auto on green).
+- Working branches: `feature/<topic>`, `fix/<topic>`, `chore/<topic>` from integration.
+- Hotfix: `hotfix/<date>` from main; PR back to main, then forward‑merge into integration.
+- Release branch: ephemeral or lightweight `release/*`. Protect when present; may fast‑forward to latest tag via CI.
+
+Merges & Approvals
+- Feature → integration: squash merge; auto‑merge on green (no human approval). Self‑merge allowed.
+- integration → main: squash merge; require 1 approval; self‑merge not allowed.
+- Force pushes disabled on protected branches (`main`, `release/*`); PRs required.
+
+Commit Style
+- Conventional Commits for PR titles and commit messages.
+
+Versioning & Tags
+- Calendar tags: `vYYYY.MM.DD-HHMM` (UTC) for traceability.
+- Release tags: semantic or milestone tags (e.g., `v0.0.1-Bootstrap`).
+
+Release Flow
+1) Feature branches PR into integration; checks pass → auto‑merge.
+2) PR integration → main; 1 approval required; on merge, deploy and tag release.
+3) Optional: CI fast‑forwards a `release` branch pointer to the new tag.
+
+Protected Checks (enable when runners are ready)
+- On protected branches (`main`, `release/*`): ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security when introduced.
+
+CODEOWNERS
+- Keep minimal; require review for integration → main.
+
+Notes
+- No secrets in this base repo. Future repos should integrate Vault for secrets.
+

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

scripts/Makefile

@@ -0,0 +1,39 @@
+SHELL := /usr/bin/env bash
+
+.PHONY: all check quick format lint build test security ci-image hooks-setup prompts prompts-check
+
+all: check
+
+check:
+	./scripts/ci all
+
+quick:
+	./scripts/ci format && ./scripts/ci lint
+
+format:
+	./scripts/ci format
+
+lint:
+	./scripts/ci lint
+
+build:
+	./scripts/ci build
+
+test:
+	./scripts/ci test
+
+security:
+	./scripts/ci security
+
+ci-image:
+	docker build -f docker/ci.Dockerfile -t local/ci:latest .
+
+hooks-setup:
+	./scripts/setup-hooks
+
+prompts:
+	./scripts/prompts all
+
+prompts-check:
+	./scripts/prompts lint
+

scripts/ci

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PHASE="${1:-}"
+
+usage() {
+  echo "Usage: scripts/ci <format|lint|build|test|security|all>" >&2
+  exit 2
+}
+
+if [[ -z "${PHASE}" ]]; then
+  usage
+fi
+
+repo_root() {
+  git rev-parse --show-toplevel 2>/dev/null || pwd
+}
+
+run_outside_container() {
+  local phase="$1"
+  local root
+  root="$(repo_root)"
+  if ! command -v docker >/dev/null 2>&1; then
+    echo "Docker is required to run CI tasks locally." >&2
+    exit 1
+  fi
+  if ! command -v docker-compose >/dev/null 2>&1 && ! docker compose version >/dev/null 2>&1; then
+    echo "Docker Compose v2+ is required (docker compose)." >&2
+    exit 1
+  fi
+  # Build ci image if needed and run the requested phase inside the container
+  (cd "$root" && docker compose -f docker/ci.compose.yml run --rm \
+    -e IN_CI_CONTAINER=1 \
+    ci bash -lc "cd /workspace && scripts/ci --inside ${phase}")
+}
+
+run_format() {
+  echo ">> Formatting"
+  # shell: format in-place
+  shfmt -bn -ci -i 2 -w .
+  # prettier for markdown/yaml/json/etc
+  prettier --log-level warn --write \
+    "**/*.md" "**/*.yaml" "**/*.yml" "**/*.json" \
+    "**/*.css" "**/*.html" 2>/dev/null || true
+}
+
+run_lint() {
+  echo ">> Linting"
+  # shellcheck
+  mapfile -t sh_files < <(git ls-files -z | xargs -0 file --mime-type | awk -F: '/(x-shellscript|text\/x-shellscript)/{print $1}'; git ls-files "*.sh")
+  if [[ ${#sh_files[@]} -gt 0 ]]; then
+    shellcheck -x "${sh_files[@]}" || (echo "Shellcheck failed" && exit 1)
+    shfmt -d .
+  fi
+  # hadolint on Dockerfiles
+  if ls Dockerfile* docker/*Dockerfile* 1>/dev/null 2>&1; then
+    hadolint Dockerfile* docker/*Dockerfile* 2>/dev/null || true
+  fi
+  # yamllint
+  if git ls-files "*.yml" "*.yaml" | grep -q .; then
+    yamllint -s $(git ls-files "*.yml" "*.yaml")
+  fi
+  # markdownlint
+  if git ls-files "*.md" | grep -q .; then
+    markdownlint $(git ls-files "*.md")
+  fi
+  # actionlint for workflow files if present
+  if [ -d .gitea/workflows ]; then
+    actionlint -color
+  fi
+}
+
+run_build() {
+  echo ">> Build checks"
+  # Validate docker compose configs if present
+  if [ -f docker-compose.yml ] || [ -f docker/compose.yml ]; then
+    docker compose config -q
+  fi
+}
+
+run_test() {
+  echo ">> Tests (none defined)"
+}
+
+run_security() {
+  echo ">> Security checks (skipped for this repo)"
+}
+
+run_inside_container() {
+  local phase="$1"
+  case "$phase" in
+    format) run_format ;;
+    lint) run_lint ;;
+    build) run_build ;;
+    test) run_test ;;
+    security) run_security ;;
+    all) run_format; run_lint; run_build; run_test; run_security ;;
+    *) usage ;;
+  esac
+}
+
+if [[ "${1:-}" == "--inside" ]]; then
+  shift
+  PHASE="${1:-}"
+  [[ -z "$PHASE" ]] && usage
+  run_inside_container "$PHASE"
+  exit 0
+fi
+
+if [[ "${IN_CI_CONTAINER:-}" != "1" ]]; then
+  run_outside_container "$PHASE"
+else
+  run_inside_container "$PHASE"
+fi
+

scripts/commitlint-hook

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+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 --config .config/commitlint.config.cjs --edit ${MSG_FILE}"

scripts/prompt_build.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+import os, sys, yaml
+
+def load_manifest(path):
+    with open(path, 'r', encoding='utf-8') as f:
+        return yaml.safe_load(f)
+
+def resolve(path, seen):
+    m = load_manifest(path)
+    includes = m.get('include', []) or []
+    modules = m.get('modules', []) or []
+    for inc in includes:
+        resolve(inc, seen)
+    for mod in modules:
+        if mod not in seen:
+            seen.append(mod)
+    return seen
+
+def words(s: str) -> int:
+    return len(s.split())
+
+def main():
+    if len(sys.argv) != 3:
+        print("Usage: prompt_build.py <manifest> <out>", file=sys.stderr)
+        sys.exit(2)
+    manifest, out_path = sys.argv[1], sys.argv[2]
+    mods = resolve(manifest, [])
+    if not mods:
+        print(f"No modules resolved from {manifest}", file=sys.stderr)
+        sys.exit(1)
+    os.makedirs(os.path.dirname(out_path), exist_ok=True)
+    def read(p):
+        with open(p, 'r', encoding='utf-8') as f:
+            return f.read().strip() + "\n\n"
+    parts = ["Generated Prompt Pack\n\n"]
+    for m in mods:
+        parts.append(f"--- {m} ---\n")
+        parts.append(read(m))
+    content = "".join(parts)
+    # budgets
+    total_words = words(content)
+    BASE_BUDGET = 1200
+    if total_words > BASE_BUDGET:
+        print(f"ERROR: Pack exceeds budget: {total_words} > {BASE_BUDGET}", file=sys.stderr)
+        sys.exit(3)
+    ERRORS = 0
+    MOD_BUDGET = 400
+    for m in mods:
+        with open(m, 'r', encoding='utf-8') as f:
+            wc = words(f.read())
+            if wc > MOD_BUDGET:
+                print(f"ERROR: Module {m} exceeds budget: {wc} > {MOD_BUDGET}", file=sys.stderr)
+                ERRORS += 1
+    if ERRORS:
+        sys.exit(4)
+    if out_path == '-':
+        sys.stdout.write(content)
+    else:
+        with open(out_path, 'w', encoding='utf-8') as out:
+            out.write(content)
+    print(f"Built {out_path} with {total_words} words across {len(mods)} modules.", file=sys.stderr)
+
+if __name__ == '__main__':
+    main()

scripts/prompts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: scripts/prompts <command> [args]
+
+Commands:
+  build <manifest> <output>   Build a flattened prompt from a manifest
+  pack <area>                 Build known area pack (cto|coo) into area dist/
+  all                         Build all known area packs
+  lint                        Lint prompts (budgets and includes)
+USAGE
+  exit 2
+}
+
+repo_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
+
+ci_run() {
+  local root; root="$(repo_root)"
+  # Ensure ci image is available by invoking a no-op build via scripts/ci
+  # Use compose to run with current uid:gid to avoid file ownership issues
+  docker compose -f "$root/docker/ci.compose.yml" run --rm \
+    --user "$(id -u):$(id -g)" \
+    -e IN_CI_CONTAINER=1 ci bash -lc "cd /workspace && $1" </dev/null
+}
+
+build_manifest() {
+  local manifest=$1 out=$2 root
+  root="$(repo_root)"
+  # Write on host to avoid ownership issues; container prints to stdout.
+  TMP_OUT=$(mktemp)
+  trap '[[ -n "${TMP_OUT:-}" ]] && rm -f "$TMP_OUT"' EXIT
+  ci_run "python3 scripts/prompt_build.py '$manifest' -" >"$TMP_OUT"
+  mkdir -p "$(dirname "$out")"
+  mv "$TMP_OUT" "$out"
+}
+
+cmd=${1:-}
+case "$cmd" in
+  build)
+    shift; [[ $# -eq 2 ]] || usage
+    build_manifest "$1" "$2" ;;
+  pack)
+    shift; area=${1:-}; root="$(repo_root)"
+    case "$area" in
+      cto) build_manifest "$root/COMMON/prompt/manifests/cto.yaml" "$root/CTO/dist/prompts/cto.md" ;;
+      coo) build_manifest "$root/COMMON/prompt/manifests/coo.yaml" "$root/COO/dist/prompts/coo.md" ;;
+      *) echo "Unknown area: $area" >&2; exit 2 ;;
+    esac ;;
+  all)
+    root="$(repo_root)"
+    "$0" pack cto
+    "$0" pack coo ;;
+  lint)
+    # Rebuild and rely on budget checks to fail if over
+    "$0" all ;;
+  *) usage ;;
+esac

scripts/setup-hooks

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+mkdir -p "$root_dir/.git/hooks"
+
+for hook in pre-commit pre-push commit-msg; do
+  src="$root_dir/.githooks/$hook"
+  dest="$root_dir/.git/hooks/$hook"
+  if [[ -f "$src" ]]; then
+    cp "$src" "$dest"
+    chmod +x "$dest"
+    echo "Installed hook: $hook"
+  fi
+done
+
+echo "Git hooks installed."
+