From 59e104a57c63a0b6b2dd8f294d7048a6cced6eb7 Mon Sep 17 00:00:00 2001
From: ReachableCEO <charles@turnsys.com>
Date: Wed, 10 Sep 2025 17:39:15 -0500
Subject: [PATCH] docs(agents): add AGENTS.md and area packs

- Add CTO/COO AGENTS.md pointing to dist prompt packs
- Add CODEOWNERS for COMMON/prompt and areas
- Add prompt_build.py used by scripts/prompts (containerized)
---
 AGENTS.md               |  8 ++++++
 CODEOWNERS              |  5 ++++
 COO/AGENTS.md           | 13 +++++++++
 CTO/AGENTS.md           | 13 +++++++++
 scripts/prompt_build.py | 64 +++++++++++++++++++++++++++++++++++++++++
 5 files changed, 103 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CODEOWNERS
 create mode 100644 COO/AGENTS.md
 create mode 100644 CTO/AGENTS.md
 create mode 100644 scripts/prompt_build.py

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..96f8d1d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,8 @@
+Agent Guidance (Repo Base)
+
+- Use area prompt packs generated under `dist/prompts/`:
+  - CTO: `dist/prompts/cto.md`
+  - COO: `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/CODEOWNERS b/CODEOWNERS
new file mode 100644
index 0000000..0602fd1
--- /dev/null
+++ b/CODEOWNERS
@@ -0,0 +1,5 @@
+# Prompt packs
+COMMON/prompt/**   @reachableceo
+CTO/**             @reachableceo
+COO/**             @reachableceo
+
diff --git a/COO/AGENTS.md b/COO/AGENTS.md
new file mode 100644
index 0000000..29fcd17
--- /dev/null
+++ b/COO/AGENTS.md
@@ -0,0 +1,13 @@
+COO Agent Pack
+
+Use the generated pack for agents: `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.
+
diff --git a/CTO/AGENTS.md b/CTO/AGENTS.md
new file mode 100644
index 0000000..08ea220
--- /dev/null
+++ b/CTO/AGENTS.md
@@ -0,0 +1,13 @@
+CTO Agent Pack
+
+Use the generated pack for agents: `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.
+
diff --git a/scripts/prompt_build.py b/scripts/prompt_build.py
new file mode 100644
index 0000000..60353c6
--- /dev/null
+++ b/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()