61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# TASK: Docs standards pass — READMEs and docs/ across ukrrs repos
|
|
|
|
## Context
|
|
Charles decreed (2026-08-28 ~21:00): ALL project docs must be informative,
|
|
well-formatted, beautiful, and useful. Current MOPAC harness README is 16
|
|
skeleton lines with a stale Gitea path (says reachableceo/MOPAC; org moved to
|
|
ukrrs/MOPAC). This standard applies to every repo we own from now on.
|
|
|
|
## Scope (in priority order)
|
|
1. `~/projects/meta/MOPAC/harness/` — README.md full rewrite; docs/ polish.
|
|
2. `~/projects/meta/MOPAC/harness/` siblings cloned from Gitea: clone
|
|
`https://git.knownelement.com/ukrrs/mopac-keyproxy` and
|
|
`https://git.knownelement.com/ukrrs/mopac-bitwarden-go` under
|
|
`~/projects/meta/MOPAC/` and upgrade their READMEs (they are spec seeds).
|
|
3. `~/projects/siblings/KNEL-AIMiddleware` (if present) — README audit:
|
|
fix only what is wrong/stale; do not rewrite working docs wholesale.
|
|
|
|
## The doc standard (apply to every README; checklist)
|
|
- **Front matter**: H1 title, one-paragraph purpose (what/why/who-for, no
|
|
throat-clearing), then a `Status:` line — date + one-word state
|
|
(e.g. `Status: 2026-08-28 — skeleton, MVP demo path live`).
|
|
- **Quickstart**: copy-paste commands that actually work, each block followed
|
|
by a short expected-output snippet. Verify every command by RUNNING it
|
|
(e.g. `./bin/harness once --dry-run --demo`, `./bin/harness help`).
|
|
Never document an unverified command.
|
|
- **Architecture**: a mermaid flowchart of the conductor loop
|
|
(intake -> routing -> bounded turn -> REPORT) plus one paragraph of prose.
|
|
- **Reference tables** (not prose walls):
|
|
- CLI: subcommands, flags, exit codes (0/1/2/4) — from actual help output.
|
|
- Config: every `harness.toml` section with one-line meaning (from
|
|
harness.toml.example + internal/config).
|
|
- Model routing: the `[models]` tier map as a table (class -> model).
|
|
- **Status table**: Works / Stubbed / Next — sourced from REPORT.md, kept
|
|
honest.
|
|
- **Formatting**: fenced code with language tags; headings never skip levels;
|
|
consistent terminology (harness, conductor, turn, REPORT capitalized as
|
|
shown); no dead links; no TODO markers without an owner; correct repo
|
|
URLs (git.knownelement.com/ukrrs/...).
|
|
- For keyproxy/bitwarden-go seeds: purpose, scope, non-goals (no admin UI,
|
|
memory-only), license (AGPLv3), status line, and what exists today vs
|
|
planned — the spec READMEs already carry the design; make them navigable.
|
|
|
|
## docs/ polish (MOPAC only)
|
|
- Each PORTING-NOTES-*.md gets the Status front-matter line.
|
|
- DESIGN.md gets a short table of contents after its intro (section list,
|
|
anchor links). Do NOT rewrite or reorder existing sections.
|
|
|
|
## Constraints
|
|
- DOCS ONLY. No source code changes. No new sections in DESIGN.md.
|
|
- This turn runs AFTER pmo-ops and events-receiver complete (dispatch is
|
|
gated); the repo working tree will be clean and pushed when you start.
|
|
- Verify-then-write: read the code/help/config you are documenting.
|
|
- Commit per repo with clear messages; push to ukrrs remotes.
|
|
|
|
## Deliverables
|
|
- Commits + pushes: MOPAC (README + docs/), mopac-keyproxy, mopac-bitwarden-go,
|
|
(KNEL-AIMiddleware if touched).
|
|
- `REPORT-20260828-docs-standards.md` in `~/.coordinate/inbox-pmo/`: per-repo
|
|
summary of changes, the checklist items applied, any doc rot found that you
|
|
could NOT fix in this pass (list for follow-up).
|