| name | catgo-campaign-conventions |
| description | Authoring conventions for CatGo md-orchestration campaigns — progressive markdown, README+INDEX pairs and keeping them current, logging interventions to LESSONS, human-readable (never-hash) names, and the progressive (top→stage→calc) plan. Use when creating/editing any campaign markdown (plan/README/INDEX/STATUS/LESSONS) so the file tree stays navigable and resumable. Pairs with catgo-campaign. |
catgo-campaign-conventions — how to author campaign markdown
TL;DR: Progressive md (TL;DR-first, drill down), a README+INDEX pair at every level
kept current, log every intervention to LESSONS, human-readable names (no hashes), and a
top→stage→calc progressive plan. These keep the tree navigable + resumable from disk.
Progressive markdown
Every md opens with # title + a > **TL;DR:** line, details below in greppable sections.
Read INDEX.md first; drill into a branch only when you work it. Keep STATUS.md /
LESSONS.md curated, not append-only logs. Don't pile everything into one big md —
split by concern, stitch with INDEX.
README + INDEX pair (kept current)
Every level has a README (description) + INDEX (pointer/navigation).
- When you add a stage or calc folder, update the parent
INDEX.md (one line + role).
INDEX is the navigation spine — an empty/stale INDEX breaks drill-down.
- Fill the scaffold's stub files — top
README.md (what / goal / current stage),
plan.md, cluster.md. Never leave the <...> placeholders the scaffolder writes.
- README (human: what the project is) vs CLAUDE.md (agent bootstrap) vs INDEX (pointer) —
distinct roles, don't duplicate.
Log every intervention
Any time you cancel / rebuild / retry a calc, change its inputs, or hit a gotcha, record
what changed and why in that calc's LESSONS.md (and the project LESSONS.md if it
generalizes). STATUS.md only holds the CURRENT job — it does not remember a prior
cancelled/failed attempt, so the history lives in LESSONS. (catgo campaign submit updates
STATUS.md automatically; LESSONS is on you.)
Human-readable names (never hashes)
Names are readable; uniqueness comes from the project/stage/calc path hierarchy. A clash
gets a readable -2 suffix, never a digest. The remote work_dir mirrors the local tree.
Progressive plan (top → stage → calc)
- Top
plan.md = only WHAT (goal + the stage list, each line LINKING to that stage's plan).
calc/<stage>/plan.md = mid-level detail + links to its calcs.calc/<stage>/<calc>/plan.md = the FULL recipe (method, params + rationale, convergence,
freq/restart strategy, result to extract, dependencies).
Keep the top short; push specifics down. (Flat campaign with no stages → two levels suffice.)
