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

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

CCO/.gitkeep

@@ -0,0 +1 @@
+

CODEOWNERS

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

COMMON/README.md

@@ -0,0 +1,13 @@
+COMMON
+
+Purpose
+- Foundational, shared practices usable across projects.
+- Opinionated but adaptable; intended as a base layer.
+
+Contents (initial)
+- Git workflow (branching, merges, commit style)
+- CI/bootstrap parity guidance
+
+Notes
+- Keep content generic and reusable; project-specific overrides should live in the target repo.
+

COMMON/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
+- `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)
+
+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.
+

COMMON/git-workflow.md

@@ -1,14 +1,14 @@
 Git Workflow – Finalized Instructions
 
 Scope
-- Applies to this repo. Users typically consume tagged releases; contributors work via branches/PRs. CI/CD config is Gitea‑native; no GitHub/GitLab.
+- 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; optionally fast‑forward to latest tag via CI.
+- 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.
@@ -19,18 +19,20 @@ Commit Style
 - Conventional Commits for PR titles and commit messages.
 
 Versioning & Tags
-- Calendar tags: vYYYY.MM.DD-HHMM (UTC). Annotated tags only on main after release.
+- 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.
+3) Optional: CI fast‑forwards a `release` branch pointer to the new tag.
 
-Protected Checks (to enable when runners are ready)
-- On protected branches (`main`, `release/*`): ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security if/when introduced.
+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 your review for integration → main.
+- Keep minimal; require review for integration → main.
 
 Notes
-- No secrets required for this repo. Future repos should integrate Vault for secrets.
+- No secrets in this base repo. Future repos should integrate Vault for secrets.
+

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

COO/.gitkeep

@@ -0,0 +1 @@
+

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

CTO/.gitkeep

@@ -0,0 +1 @@
+

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

DISCUSS.md

@@ -0,0 +1,43 @@
+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., 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, 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.
+

Makefile

@@ -31,3 +31,9 @@ ci-image:
 hooks-setup:
 	./scripts/setup-hooks
 
+.PHONY: prompts prompts-check
+prompts:
+	./scripts/prompts all
+
+prompts-check:
+	./scripts/prompts lint

RESUME.md

@@ -41,8 +41,8 @@ Branches on remote
   - git branch -f release main && git push -f origin release
 
 8) Docs & parity
-- Git workflow: instructions/git-workflow.md
-- Local CI parity: instructions/bootstrap-cicd.md
+- Git workflow: COMMON/git-workflow.md
+- Local CI parity: 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
@@ -50,4 +50,3 @@ Branches on remote
 10) Next tasks
 - Answer any outstanding questions in questions/*
 - On approval, implement further proposals and update instructions/*
-

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 instructions/git-workflow.md
+- [x] Finalize approval and capture in COMMON/git-workflow.md
 
 - Branches
   - [x] Create integration, release, bootstrap from main

instructions/bootstrap-cicd.md

@@ -1,36 +0,0 @@
-Bootstrap CI/CD – Finalized Instructions (Phase 1)
-
-Goal
-- Provide Docker‑only local checks and Git hooks with parity to future CI. CI workflows are prepared but may remain disabled until runners are ready.
-
-Requirements
-- Docker + Docker Compose v2 on the development machine. No host packages beyond Docker are required.
-
-Local Checks
-- Entry point: `scripts/ci <phase>` where phase ∈ {format, lint, build, test, security, all}.
-- Always runs inside the ci container using `docker/ci.compose.yml`.
-- Tools pinned in `ci.Dockerfile`: shfmt, shellcheck, hadolint, yamllint, actionlint, prettier, markdownlint, commitlint.
-
-Hooks
-- Install hooks: `make hooks-setup` (copies .githooks/* into .git/hooks).
-- pre-commit: runs format + lint.
-- commit-msg: runs commitlint (Conventional Commits).
-- pre-push: runs build; test and security are present but currently no‑ops.
-
-Convenience Targets
-- `make quick` → format + lint.
-- `make check` → all phases.
-- `make build` → compose validation.
-
-CI (Prepared, optional enablement later)
-- .gitea/workflows/ci.yml: builds ci image; runs lint + build.
-- .gitea/workflows/release.yml: on pushes to main, creates annotated tag vYYYY.MM.DD-HHMM (UTC).
-- .gitea/workflows/nightly.yml: nightly lint run.
-- All jobs run inside the ci image; no runner host package installs.
-
-Protected Checks (when CI is enabled)
-- Protect: ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security when they exist.
-
-Future Extensions
-- Add tests/security phases per repo stack; enable CI branch protections once runners are ready; optionally add pre-commit framework as an alternative to native hooks.
-

proposals/bootstrap-cicd.md

@@ -65,5 +65,4 @@
 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 `instructions/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`.

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,130 @@
+#!/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 dist/prompts
+  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 "$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"
+}
+
+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/dist/prompts/cto.md" ;;
+      coo) build_manifest "$root/COMMON/prompt/manifests/coo.yaml" "$root/dist/prompts/coo.md" ;;
+      *) echo "Unknown area: $area" >&2; exit 2 ;;
+    esac ;;
+  all)
+    root="$(repo_root)"; mkdir -p "$root/dist/prompts"
+    "$0" pack cto
+    "$0" pack coo ;;
+  lint)
+    # Rebuild and rely on budget checks to fail if over
+    "$0" all ;;
+  *) usage ;;
+esac
+