Skip to content

Loading and activation

Defined in the developer contract docs/architecture/content-loading.md and the product protocol framework/context-loading.md. For the user-level explanation, see Activation and loading.

Ordered instruction use

Section titled “Ordered instruction use”
flowchart TD
accTitle: Bootstrap and progressive loading chain
accDescr: Host discovers name and description, user or host selects, SKILL.md instructs reading KIYO.md, the compact bootstrap establishes authority and scope, the selected workflow runs, relevant references and one template are read, and output goes to the authorized project location or chat.
D[Host discovers name + description] --> S[User selection or host relevance matching]
S --> E[SKILL.md entry:<br/>read packaged KIYO.md before workflow actions]
E --> B[Compact bootstrap:<br/>authority, scope, context pointers, budgets]
B --> W[Selected Skill mode + shared workflow]
W --> R[Relevant Core / policies / profile]
R --> T[One selected template]
T --> O[Chat report, or authorized project output]

Key properties:

  • Links are locators, not imports. Markdown links carry no native include guarantee. The bootstrap does not recursively read what it links.
  • Relative to the installed file. Paths resolve from the actual SKILL.md, never the shell’s current directory, the author checkout, or a guessed cache path.
  • Re-establish after context loss. An already-read, unchanged bootstrap need not be reread in the same task. After context loss or a changed bundle identity, it must be.
  • Memory First is bounded. The agent consults the established index and relevant entries, then checks material facts against current code. It does not load every Memory file.

Context budgets (ADR-002)

Section titled “Context budgets (ADR-002)”

ADR-002 keeps both metrics, so that no one can meet an entry budget by hiding mandatory text in another file:

Layer Ceiling Verification
Project adapter block ≤ 250 whitespace-delimited words per Kiyo-owned block Static count after rendering, excluding human instructions
Product bootstrap KIYO.md + framework/bootstrap.md ≤ 120 lines and 600 words Static count; no hidden mandatory includes
Selected SKILL.md ≤ 250 lines and 1,200 words, including native frontmatter Static count after rendering
Task references Only named applicable sections Behavioral trace (not yet run)

These are Kiyo design ceilings, not host limits or token measurements. Current measurements are on Context budgets.

Per-host project adapters

Section titled “Per-host project adapters”
Target Project instruction candidate Disposition
Claude Code CLI Existing CLAUDE.md or .claude/CLAUDE.md Scoped project-relative locator only through authorized Init; a plugin-root CLAUDE.md is not a Core loader
Claude Code VS Code Same Claude project mechanism Separate loading test; CLI behavior is not evidence
Codex CLI Applicable AGENTS.md / AGENTS.override.md Preserve the instruction chain and its documented context cap; never edit AGENTS.override.md or global config
Codex IDE extension Native project guidance exists separately Native plugin route UNSUPPORTED; no fallback generated
Copilot CLI .github/copilot-instructions.md or AGENTS.md No cache paths through @ includes; native precedence uncertainty retained
Copilot VS Code .github/copilot-instructions.md or AGENTS.md Respect harness and settings; plugin rules are not an established Core loader

The managed block contains only:

  • the working identity and adapter revision;
  • a note that it is advisory;
  • project-relative state locators;
  • guidance to select the discovered Skill;
  • what to do when Kiyo is unavailable: report the limit, preserve state, and never claim a Kiyo workflow ran.

Recorded sample blocks measured 114 words (Claude), 108 words (Codex), and 116 words (Copilot).

Managed-block lifecycle

Section titled “Managed-block lifecycle”
stateDiagram-v2
accTitle: Managed instruction block lifecycle
accDescr: The block is absent until an authorized Init proposes and inserts it. It becomes user-owned. Re-running Init compares and either no-ops or proposes a scoped update. Human-modified blocks are reconciled. Plugin update or uninstall never touch it; only a separately authorized cleanup removes just the block.
[*] --> Absent
Absent --> Proposed: Init preview
Proposed --> Inserted: authorized Init
Inserted --> UserOwned: after insertion
UserOwned --> UserOwned: plugin update / uninstall (no change)
UserOwned --> Reconcile: human edits detected
Reconcile --> UserOwned: agreed scoped update
UserOwned --> Removed: separately authorized cleanup of the block only
  • Re-running Init compares the proposal with the current content. An unchanged equivalent block is a no-op.
  • Duplicate, missing-end, or nested markers, or ambiguous ownership, need a decision before any write.
  • Uninstall leaves policy, Memory, and the block intact. There is no Kiyo cleanup hook.

Required future checks

Section titled “Required future checks”

The architecture specifies checks that remain NOT_TESTED:

  • bootstrap-before-actions;
  • avoiding irrelevant references;
  • read-only modes, and missing or poisoned Memory;
  • preserving human edits;
  • per-target explicit and implicit selection, with and without bootstrap;
  • relocation, update, and uninstall behavior.
Section titled “Related”