From 56aa2a15229e62264a39f6cc3837bfc9f70c019a Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 17:21:26 -0500 Subject: [PATCH 1/5] feat(org): introduce COMMON/CTO/COO/CCO areas - Add uppercase area directories; CCO placeholder only - Move shared docs to COMMON (git workflow, CI bootstrap); update references - Add DISCUSS.md to capture open questions and decisions --- CCO/.gitkeep | 1 + COMMON/README.md | 13 +++++++ COMMON/bootstrap-cicd.md | 21 ++++++++++++ {instructions => COMMON}/git-workflow.md | 20 ++++++----- COO/.gitkeep | 1 + CTO/.gitkeep | 1 + DISCUSS.md | 43 ++++++++++++++++++++++++ RESUME.md | 5 ++- TODO.md | 2 +- instructions/bootstrap-cicd.md | 36 -------------------- proposals/bootstrap-cicd.md | 3 +- 11 files changed, 95 insertions(+), 51 deletions(-) create mode 100644 CCO/.gitkeep create mode 100644 COMMON/README.md create mode 100644 COMMON/bootstrap-cicd.md rename {instructions => COMMON}/git-workflow.md (60%) create mode 100644 COO/.gitkeep create mode 100644 CTO/.gitkeep create mode 100644 DISCUSS.md delete mode 100644 instructions/bootstrap-cicd.md diff --git a/CCO/.gitkeep b/CCO/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CCO/.gitkeep @@ -0,0 +1 @@ + diff --git a/COMMON/README.md b/COMMON/README.md new file mode 100644 index 0000000..365c897 --- /dev/null +++ b/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. + diff --git a/COMMON/bootstrap-cicd.md b/COMMON/bootstrap-cicd.md new file mode 100644 index 0000000..25ee240 --- /dev/null +++ b/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. + diff --git a/instructions/git-workflow.md b/COMMON/git-workflow.md similarity index 60% rename from instructions/git-workflow.md rename to COMMON/git-workflow.md index 127a92f..5aa2774 100644 --- a/instructions/git-workflow.md +++ b/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/`, `fix/`, `chore/` from integration. -- Hotfix: `hotfix/` 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/` 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. + diff --git a/COO/.gitkeep b/COO/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/COO/.gitkeep @@ -0,0 +1 @@ + diff --git a/CTO/.gitkeep b/CTO/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CTO/.gitkeep @@ -0,0 +1 @@ + diff --git a/DISCUSS.md b/DISCUSS.md new file mode 100644 index 0000000..0eef302 --- /dev/null +++ b/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. + diff --git a/RESUME.md b/RESUME.md index 726e303..0f725c7 100644 --- a/RESUME.md +++ b/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/* - diff --git a/TODO.md b/TODO.md index 15933ed..e5f2696 100644 --- a/TODO.md +++ b/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 diff --git a/instructions/bootstrap-cicd.md b/instructions/bootstrap-cicd.md deleted file mode 100644 index 9ccf1fe..0000000 --- a/instructions/bootstrap-cicd.md +++ /dev/null @@ -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 ` 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. - diff --git a/proposals/bootstrap-cicd.md b/proposals/bootstrap-cicd.md index 1c5b44b..57612f7 100644 --- a/proposals/bootstrap-cicd.md +++ b/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`. -- 2.43.0 From d2eb0e1f79c400ab634a9f5c656928cb8556845d Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 17:34:28 -0500 Subject: [PATCH 2/5] feat(prompts): modular agent packs and builder - Add COMMON prompt modules + manifests (base, CTO, COO) - Add scripts/prompts builder (runs in CI container with host uid/gid) - Make targets: prompts, prompts-check --- COMMON/prompt/manifests/base.yaml | 9 ++ COMMON/prompt/manifests/coo.yaml | 4 + COMMON/prompt/manifests/cto.yaml | 4 + COMMON/prompt/modules/execution.md | 9 ++ COMMON/prompt/modules/planning.md | 12 ++ COMMON/prompt/modules/repo-conventions.md | 9 ++ COMMON/prompt/modules/safety.md | 9 ++ COMMON/prompt/modules/style.md | 16 +++ COMMON/prompt/modules/system-persona.md | 18 +++ COMMON/prompt/modules/tools-codex-cli.md | 19 ++++ Makefile | 6 + scripts/prompts | 130 ++++++++++++++++++++++ 12 files changed, 245 insertions(+) create mode 100644 COMMON/prompt/manifests/base.yaml create mode 100644 COMMON/prompt/manifests/coo.yaml create mode 100644 COMMON/prompt/manifests/cto.yaml create mode 100644 COMMON/prompt/modules/execution.md create mode 100644 COMMON/prompt/modules/planning.md create mode 100644 COMMON/prompt/modules/repo-conventions.md create mode 100644 COMMON/prompt/modules/safety.md create mode 100644 COMMON/prompt/modules/style.md create mode 100644 COMMON/prompt/modules/system-persona.md create mode 100644 COMMON/prompt/modules/tools-codex-cli.md create mode 100644 scripts/prompts diff --git a/COMMON/prompt/manifests/base.yaml b/COMMON/prompt/manifests/base.yaml new file mode 100644 index 0000000..9e82339 --- /dev/null +++ b/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 diff --git a/COMMON/prompt/manifests/coo.yaml b/COMMON/prompt/manifests/coo.yaml new file mode 100644 index 0000000..7cfddac --- /dev/null +++ b/COMMON/prompt/manifests/coo.yaml @@ -0,0 +1,4 @@ +name: COO pack v1 +include: + - COMMON/prompt/manifests/base.yaml +modules: [] diff --git a/COMMON/prompt/manifests/cto.yaml b/COMMON/prompt/manifests/cto.yaml new file mode 100644 index 0000000..24ffa18 --- /dev/null +++ b/COMMON/prompt/manifests/cto.yaml @@ -0,0 +1,4 @@ +name: CTO pack v1 +include: + - COMMON/prompt/manifests/base.yaml +modules: [] diff --git a/COMMON/prompt/modules/execution.md b/COMMON/prompt/modules/execution.md new file mode 100644 index 0000000..bc47376 --- /dev/null +++ b/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. + diff --git a/COMMON/prompt/modules/planning.md b/COMMON/prompt/modules/planning.md new file mode 100644 index 0000000..55b36df --- /dev/null +++ b/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. + diff --git a/COMMON/prompt/modules/repo-conventions.md b/COMMON/prompt/modules/repo-conventions.md new file mode 100644 index 0000000..3a67141 --- /dev/null +++ b/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. + diff --git a/COMMON/prompt/modules/safety.md b/COMMON/prompt/modules/safety.md new file mode 100644 index 0000000..def7142 --- /dev/null +++ b/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. + diff --git a/COMMON/prompt/modules/style.md b/COMMON/prompt/modules/style.md new file mode 100644 index 0000000..ccf69bb --- /dev/null +++ b/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. + diff --git a/COMMON/prompt/modules/system-persona.md b/COMMON/prompt/modules/system-persona.md new file mode 100644 index 0000000..a4fd38b --- /dev/null +++ b/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. + diff --git a/COMMON/prompt/modules/tools-codex-cli.md b/COMMON/prompt/modules/tools-codex-cli.md new file mode 100644 index 0000000..1a9d39a --- /dev/null +++ b/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. + diff --git a/Makefile b/Makefile index ff8b74f..817c8db 100644 --- a/Makefile +++ b/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 diff --git a/scripts/prompts b/scripts/prompts new file mode 100644 index 0000000..8607b08 --- /dev/null +++ b/scripts/prompts @@ -0,0 +1,130 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + cat >&2 <<'USAGE' +Usage: scripts/prompts [args] + +Commands: + build Build a flattened prompt from a manifest + pack 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" 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 + -- 2.43.0 From 59e104a57c63a0b6b2dd8f294d7048a6cced6eb7 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 17:39:15 -0500 Subject: [PATCH 3/5] 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 ", 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() -- 2.43.0 From 2a7d270062597b75432ebd8aeb1950b12a03280c Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 17:43:37 -0500 Subject: [PATCH 4/5] docs(style): enforce clickable links for Markdown references - Add COMMON/docs-style.md with linking rule - Convert plain Markdown file references to relative links across docs --- AGENTS.md | 5 +-- COMMON/README.md | 6 +-- COMMON/docs-style.md | 8 ++++ COO/AGENTS.md | 3 +- CTO/AGENTS.md | 3 +- DISCUSS.md | 5 +-- RESUME.md | 6 +-- TODO.md | 6 +-- dist/prompts/coo.md | 0 dist/prompts/cto.md | 0 proposals/bootstrap-cicd.md | 4 +- scripts/prompts | 83 +++---------------------------------- 12 files changed, 31 insertions(+), 98 deletions(-) create mode 100644 COMMON/docs-style.md create mode 100644 dist/prompts/coo.md create mode 100644 dist/prompts/cto.md mode change 100644 => 100755 scripts/prompts diff --git a/AGENTS.md b/AGENTS.md index 96f8d1d..fb7c502 100644 --- a/AGENTS.md +++ b/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. - diff --git a/COMMON/README.md b/COMMON/README.md index 365c897..95c7fe1 100644 --- a/COMMON/README.md +++ b/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. - diff --git a/COMMON/docs-style.md b/COMMON/docs-style.md new file mode 100644 index 0000000..8904a31 --- /dev/null +++ b/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. + diff --git a/COO/AGENTS.md b/COO/AGENTS.md index 29fcd17..2686a53 100644 --- a/COO/AGENTS.md +++ b/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. - diff --git a/CTO/AGENTS.md b/CTO/AGENTS.md index 08ea220..33b9ad1 100644 --- a/CTO/AGENTS.md +++ b/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. - diff --git a/DISCUSS.md b/DISCUSS.md index 0eef302..6bec9a6 100644 --- a/DISCUSS.md +++ b/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. - diff --git a/RESUME.md b/RESUME.md index 0f725c7..66629ee 100644 --- a/RESUME.md +++ b/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/* diff --git a/TODO.md b/TODO.md index e5f2696..422c69e 100644 --- a/TODO.md +++ b/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 diff --git a/dist/prompts/coo.md b/dist/prompts/coo.md new file mode 100644 index 0000000..e69de29 diff --git a/dist/prompts/cto.md b/dist/prompts/cto.md new file mode 100644 index 0000000..e69de29 diff --git a/proposals/bootstrap-cicd.md b/proposals/bootstrap-cicd.md index 57612f7..51e0ddb 100644 --- a/proposals/bootstrap-cicd.md +++ b/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). diff --git a/scripts/prompts b/scripts/prompts old mode 100644 new mode 100755 index 8607b08..b215478 --- a/scripts/prompts +++ b/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" 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 - -- 2.43.0 From 39b53e4554aaa65d5c62832dfd262327f4473aa6 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 17:45:07 -0500 Subject: [PATCH 5/5] docs: restore BOOTSTRAP.md from early bootstrap branch (traceability) --- BOOTSTRAP.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 BOOTSTRAP.md diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md new file mode 100644 index 0000000..5fc550c --- /dev/null +++ b/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). + -- 2.43.0