From 2a7d270062597b75432ebd8aeb1950b12a03280c Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 17:43:37 -0500 Subject: [PATCH] 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 -