Role primers: distill specs into per-role primer library

[koad]

Context

startup.sh now loads role-specific primers from ~/.koad-io/harness/primers/<role>/. Each entity declares KOAD_IO_ENTITY_ROLE=<word> in its .env. Every .md file in the matching role directory is loaded into the entity's system prompt at session start.

The job

94 specs exist in ~/.vesta/specs/. Each one should be considered:

1. Which roles need to know about this spec? Not every spec matters to every role. An engineer needs cascade-environment and commands-system; an orchestrator needs trust-bond-protocol and inter-entity-comms.
2. Distill, don't copy. A role primer is not the full spec — it's the operational knowledge that role needs. What to do, what not to do, what commands exist, what the conventions are.
3. One primer per topic, filed in every role that needs it. A primer about the env cascade might live in both engineer/ and orchestrator/. Symlinks or copies — your call.

Known roles so far

Role	Entity examples
orchestrator	Juno
engineer	Vulcan
curator	Vesta, Veritas
researcher	Sibyl
communicator	Mercury, Faber
designer	Muse
diagnostician	Argus
curriculum	Chiron

Roles are single words. New ones can be added as needed.

Directory structure

~/.koad-io/harness/primers/
├── orchestrator/
│   ├── trust-bonds.md
│   ├── inter-entity-comms.md
│   └── ...
├── engineer/
│   ├── cascade-environment.md
│   ├── commands-system.md
│   ├── start-and-stop-processes.md
│   ├── creating-projects-from-skeletons.md
│   └── ...
└── ...

This is ongoing

As new specs land, they need primers distilled and filed. This is a standing responsibility — not a one-shot task.

🤖 Generated with Claude Code

[koad]

Next-action plan — 2026-04-14

This is a large standing task. Breaking into concrete phases so it can be executed incrementally.

Current state

• 104 specs in ~/.vesta/specs/, 60 canonical
• ~/.koad-io/harness/primers/ directory does not yet exist
• No role primers have been written yet

Phase 1 — Bootstrap (prerequisite)

Create the primers directory structure and a skeleton for each known role. No content yet — just the directories and a README per role describing what primers go there.

~/.koad-io/harness/primers/
├── orchestrator/
│   └── README.md
├── engineer/
│   └── README.md
├── curator/
│   └── README.md
├── researcher/
│   └── README.md
├── communicator/
│   └── README.md
├── designer/
│   └── README.md
├── diagnostician/
│   └── README.md
└── curriculum/
    └── README.md

Owner: Vulcan (this is a ~/.koad-io/ framework change, not a Vesta-owned spec file)
Blocking: Nothing. Can start now.

Phase 2 — High-value specs first (Vesta-owned spec selection)

Not all 60 canonical specs need primers. The high-value set for each role:

orchestrator (Juno):

• SPEC-007 Trust Bond Protocol (who to trust, how to verify)
• SPEC-012 Session Start Protocol (what Juno checks at boot)
• SPEC-074 Harness Command Family (how to invoke entities)
• SPEC-096 Post-Flight Report (how to read flight reports)
• SPEC-104 Coordination Review Cadence (weekly/quarterly/annual reviews)

engineer (Vulcan):

• SPEC-001 Entity Model (what an entity is, directory structure)
• SPEC-005 Cascade Environment (env load order, KOAD_IO_ prefix)
• SPEC-006 Commands System (command discovery and resolution)
• SPEC-034 Package Layer (what packages exist, Npm.depends model)
• SPEC-039 Gestation Protocol / Trust Public Chain (building new entities)

curator (Vesta, Veritas):

• SPEC-007 Trust Bond Protocol (bond types, signing format)
• SPEC-077 Sanity Manifest (file attestation, CID computation)
• SPEC-082 Context Composition Model (how system prompts are assembled)
• SPEC-103 Memory Lifecycle (fidelity floor, consolidation)
• SPEC-104 Coordination Review Cadence (running the review)

researcher (Sibyl):

• SPEC-005 Cascade Environment (reading kingdom state)
• SPEC-072 Entity-Dir-as-Harness-Container (what files exist and where)
• SPEC-098 Brief Lifecycle (how research requests arrive, how to close them)

This mapping is approximate — the phase 2 executor should read each spec and decide relevance per role, not just trust this list.

Owner: Vesta (selecting which specs matter per role and writing the distilled primer content)
Blocking: Phase 1 (needs the directory structure first)

Phase 3 — Distill and file (the actual work)

For each spec × role pair identified in Phase 2: write a primer file. A primer is NOT the full spec — it's:

• What the entity in this role needs to do
• What commands exist
• What the conventions are
• What NOT to do

~1–2 pages per primer. Expect 20–30 primers to start.

Owner: Vesta
Effort: This is multi-flight work. Aim for 5 primers per flight.

Phase 4 — Ongoing

As new specs land, distill primers for affected roles. This is a standing responsibility, not a one-shot task. New specs should include a "role applicability" note in their frontmatter going forward.

---

Next concrete action: Assign Phase 1 to Vulcan as a koad/vulcan issue. Phase 2 waits on Phase 1. This issue stays open as the tracking issue.

— Vesta, 2026-04-14 backlog sweep