chore(prompts): host fallback build and minimal manifest parser (no PyYAML)

Squash-merge bootstrap-org into integration

.config/commitlint.config.cjs

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

AGENTS.md

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

COMMON/README.md

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

COO/AGENTS.md

@@ -1,6 +1,6 @@
 COO Agent Pack
 
-Use the generated pack for agents: [dist/prompts/coo.md](../../dist/prompts/coo.md).
+Use the generated pack for agents: [dist/prompts/coo.md](dist/prompts/coo.md).
 
 Includes (via COMMON base):
 - System persona, style, safety

CTO/AGENTS.md

@@ -1,6 +1,6 @@
 CTO Agent Pack
 
-Use the generated pack for agents: [dist/prompts/cto.md](../../dist/prompts/cto.md).
+Use the generated pack for agents: [dist/prompts/cto.md](dist/prompts/cto.md).
 
 Includes (via COMMON base):
 - System persona, style, safety

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

@@ -38,3 +38,4 @@ RUN npm --location=global install \
 WORKDIR /workspace
 ENTRYPOINT ["bash","-lc"]
 CMD ["bash"]
+

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"]
-

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,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 <target>`.
+

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,12 @@ 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/*
+- Answer any outstanding questions in COMMON/questions/*
 - On approval, implement further proposals and update instructions/*

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 [COMMON/questions/bootstrap-cicd.md](../COMMON/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
+

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.

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.

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
+

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}"

scripts/prompt_build.py

@@ -1,9 +1,31 @@
 #!/usr/bin/env python3
-import os, sys, yaml
+import os, sys
 
 def load_manifest(path):
+    # Minimal YAML parser for our simple manifests:
+    # keys: name (ignored), include: [..], modules: [..]
+    data = {"include": [], "modules": []}
+    key = None
     with open(path, 'r', encoding='utf-8') as f:
-        return yaml.safe_load(f)
+        for raw in f:
+            line = raw.rstrip('\n')
+            s = line.strip()
+            if not s or s.startswith('#'):
+                continue
+            if s.startswith('include:'):
+                key = 'include'
+                continue
+            if s.startswith('modules:'):
+                key = 'modules'
+                continue
+            if s.startswith('name:'):
+                key = None
+                continue
+            # list item under current key
+            if key in ('include', 'modules') and s.startswith('- '):
+                item = s[2:].strip()
+                data[key].append(item)
+    return data
 
 def resolve(path, seen):
     m = load_manifest(path)
@@ -28,7 +50,8 @@ def main():
     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)
+    if out_path != '-':
+        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"

scripts/prompts

@@ -7,7 +7,7 @@ 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 dist/prompts
+  pack <area>                 Build known area pack (cto|coo) into area dist/
   all                         Build all known area packs
   lint                        Lint prompts (budgets and includes)
 USAGE
@@ -28,11 +28,15 @@ ci_run() {
 build_manifest() {
   local manifest=$1 out=$2 root
   root="$(repo_root)"
-  mkdir -p "$root/dist/prompts"
   # 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"
+  ci_run "python3 scripts/prompt_build.py '$manifest' -" >"$TMP_OUT" || true
+  # Fallback: if container produced no output, run on host
+  if [[ ! -s "$TMP_OUT" ]]; then
+    python3 scripts/prompt_build.py "$manifest" - >"$TMP_OUT"
+  fi
+  mkdir -p "$(dirname "$out")"
   mv "$TMP_OUT" "$out"
 }
 
@@ -44,12 +48,12 @@ case "$cmd" in
   pack)
     shift; area=${1:-}; root="$(repo_root)"
     case "$area" in
-      cto) build_manifest "$root/COMMON/prompt/manifests/cto.yaml" "$root/dist/prompts/cto.md" ;;
-      coo) build_manifest "$root/COMMON/prompt/manifests/coo.yaml" "$root/dist/prompts/coo.md" ;;
+      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)"; mkdir -p "$root/dist/prompts"
+    root="$(repo_root)"
     "$0" pack cto
     "$0" pack coo ;;
   lint)