AGENTS.md

@@ -1,8 +1,7 @@
 Agent Guidance (Repo Base)
 
 - Use area prompt packs generated under `dist/prompts/`:
-  - CTO: `dist/prompts/cto.md`
-  - COO: `dist/prompts/coo.md`
+  - 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

@@ -5,9 +5,9 @@ Purpose
 - Opinionated but adaptable; intended as a base layer.
 
 Contents (initial)
-- Git workflow (branching, merges, commit style)
-- CI/bootstrap parity guidance
+- 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.
-

COMMON/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: [COMMON/git-workflow.md](COMMON/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.
+

COO/AGENTS.md

@@ -1,6 +1,6 @@
 COO Agent Pack
 
-Use the generated pack for agents: `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
@@ -10,4 +10,3 @@ Includes (via COMMON base):
 
 Notes
 - COO currently uses only COMMON; area‑specific content will be added later.
-

CTO/AGENTS.md

@@ -1,6 +1,6 @@
 CTO Agent Pack
 
-Use the generated pack for agents: `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
@@ -10,4 +10,3 @@ Includes (via COMMON base):
 
 Notes
 - Keep CTO‑specific additions minimal; prefer COMMON as source of truth.
-

DISCUSS.md

@@ -11,7 +11,7 @@ Decisions Confirmed
 
 Open Questions to Confirm
 - Naming conventions within areas
-  - File naming: keep kebab-case (e.g., git-workflow.md) or use TitleCase?
+  - 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?
@@ -33,11 +33,10 @@ Open Questions to Confirm
 - 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, TODO.md)?
+  - 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.
-

RESUME.md

@@ -41,11 +41,11 @@ Branches on remote
   - git branch -f release main && git push -f origin release
 
 8) Docs & parity
-- Git workflow: COMMON/git-workflow.md
-- Local CI parity: COMMON/bootstrap-cicd.md
+- Git workflow: [COMMON/git-workflow.md](COMMON/git-workflow.md)
+- Local CI parity: [COMMON/bootstrap-cicd.md](COMMON/bootstrap-cicd.md)
 
 9) Defer CI enablement for two weeks
-- Track in TODO.md: Revisit enabling runners and protected checks on 2025-09-24
+- Track in [TODO.md](TODO.md): Revisit enabling runners and protected checks on 2025-09-24
 
 10) Next tasks
 - Answer any outstanding questions in questions/*

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
+- [x] Finalize approval and capture in [COMMON/git-workflow.md](COMMON/git-workflow.md)
 
 - Branches
   - [x] Create integration, release, bootstrap from main
@@ -12,7 +12,7 @@ TODO
 
 - CI/CD bootstrap
   - [x] Create branch bootstrap-cicd from main
-  - [x] Add questions at 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] Add .gitea/workflows: ci.yml, release.yml, nightly.yml
@@ -31,4 +31,4 @@ TODO
   - [ ] Optional: fast-forward release branch to latest tag
 
 - Docs
-  - [ ] Write docs/engineering/git-workflow.md with diagrams and examples
+- [ ] Write [docs/engineering/git-workflow.md](docs/engineering/git-workflow.md) with diagrams and examples

proposals/bootstrap-cicd.md

@@ -61,8 +61,8 @@
 **Rollout Plan**
 
 1) Implement local tooling and hooks on `bootstrap-cicd`.
-2) Document quickstart in `docs/engineering/ci-cd.md`.
+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`.
+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).

scripts/prompts

@@ -22,88 +22,18 @@ ci_run() {
   # 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 "$1" </dev/null
+    -e IN_CI_CONTAINER=1 ci bash -lc "cd /workspace && $1" </dev/null
 }
 
 build_manifest() {
   local manifest=$1 out=$2 root
   root="$(repo_root)"
   mkdir -p "$root/dist/prompts"
-  local cmd
-  cmd=$(cat <<'PY'
-python3 - << 'EOF'
-import os, sys, yaml
-
-manifest_path = sys.argv[1]
-out_path = sys.argv[2]
-
-seen = []
-
-def load_manifest(path):
-    with open(path, 'r', encoding='utf-8') as f:
-        return yaml.safe_load(f)
-
-def collect(mod, acc):
-    if mod not in acc:
-        acc.append(mod)
-
-def resolve(path):
-    m = load_manifest(path)
-    includes = m.get('include', []) or []
-    modules = m.get('modules', []) or []
-    for inc in includes:
-        for x in resolve(inc):
-            collect(x, seen)
-    for mod in modules:
-        collect(mod, seen)
-    return seen
-
-mods = resolve(manifest_path)
-if not mods:
-    print(f"No modules resolved from {manifest_path}", 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"
-
-with open(out_path, 'w', encoding='utf-8') as out:
-    out.write("Generated Prompt Pack\n\n")
-    for m in mods:
-        out.write(f"--- {m} ---\n")
-        out.write(read(m))
-
-# Budgets (approximate by word count)
-def words(s):
-    return len(s.split())
-
-with open(out_path, 'r', encoding='utf-8') as f:
-    content = f.read()
-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)
-
-# Per-module budget check
-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)
-
-print(f"Built {out_path} with {total_words} words across {len(mods)} modules.")
-EOF
-PY
-)
-  ci_run "$cmd" <<<"$manifest $out"
+  # 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"
+  mv "$TMP_OUT" "$out"
 }
 
 cmd=${1:-}
@@ -127,4 +57,3 @@ case "$cmd" in
     "$0" all ;;
   *) usage ;;
 esac
-