Runtime flows

Kiyo has no process of its own. Its “runtime” is the sequence of procedures a host agent follows after you select a Skill. This page traces the main flows with their entry points, participants, data movement, side effects, and failure paths, each tied to the source file that defines it.

1. Primary sequence: a request, end to end

Entry point: you select a Skill in the host. Participants: you, the host agent, the installed package, and your repository.

sequenceDiagram
accTitle: Primary request sequence
accDescr: The user selects a Skill and states intent. The agent reads SKILL.md, the bootstrap, and the selected procedure, orients on Memory, inspects the repository, applies governance, performs permitted effects, verifies, and returns a chat report.
actor U as User
participant H as Host agent
participant K as Installed Kiyo package
participant R as Repository (+ .kiyo/)
U->>H: Select Skill + describe intent
H->>K: Read SKILL.md (modes, access contract)
H->>K: Read KIYO.md + bootstrap (10 rules)
H->>K: Read selected procedure (router if intent is unclear)
H->>R: Read Memory index + relevant entries
H->>R: Inspect code, config, tests (within permissions)
H->>K: Governance Review + relevant checklist
alt approval required and missing
H-->>U: Concrete approval request (only the missing scope)
U->>H: Scoped approval (or decline)
end
opt authorized write / execute
H->>R: Minimal edit / preflighted checks
end
H->>K: Evidence Contract + DoD + one template
H-->>U: Chat report: scope, changes, checks, Memory impact, status

Data movement: instructions flow from the package into the agent’s context. Evidence flows from the repository. Output goes to chat by default; a file is written only within authorized output scope.

Side effects: only those allowed by the Skill’s access contract, your request, policy, and the host. Read-only Skills produce none.

Failure path: a missing package resource is reported with its path, and dependent actions stop. The agent never fetches a replacement. A denied host capability is a limitation, not a reason to use a different tool.

2. Implementation flow

Defined in: workflows/implement-flow.md (KIYO-FLOW-002). Used by: Implement, and the authorized write portions of other Skills, such as Test write.

flowchart TD
accTitle: Implementation flow stages
accDescr: Stages from permission preflight through Memory orientation, understanding, inspection, planning, risk assessment, optional human decision, implementation, verification, review, Memory impact, and completion, with a repair loop from verification.
P[Permission preflight] --> MO[Authorized Memory orientation]
MO --> U[Understand: behavior, AC, unknowns]
U --> IV[Inspect + validate relevant Memory]
IV --> PL[Plan: minimal change, checks]
PL --> RG[Assess risk / governance]
RG --> HD{Policy-defined approval<br/>missing?}
HD -- yes --> AR[Request only the missing scope] --> HD2{Approved?}
HD2 -- no --> STOP[Hold dependent work;<br/>report DECISION REQUIRED]
HD2 -- yes --> IM
HD -- no --> IM[Implement authorized delta]
IM --> VE[Verify: preflight then run permitted checks]
VE -->|failure| RP{Unsuccessful repairs<br/>so far < 2?}
RP -- yes --> IM
RP -- no --> HO[Stop repairs; handoff with evidence]
VE -->|results recorded| RV[Self-review final diff]
RV --> MI[Memory impact / authorized sync]
MI --> DONE[Complete against Implement DoD]

Mutation and execution are separate operations. Permitted code edits can go ahead while a test command waits for an environment check. Approval is checked early for obviously sensitive effects; the later risk stage never postpones a sensitive-data check until after an unsafe read.

3. Read-only flow

Defined in: workflows/read-only-flow.md (KIYO-FLOW-003). Used by: Review, Test assess, Security, Architecture, Requirement discussion, Memory check.

flowchart LR
accTitle: Read-only flow
accDescr: Authorized context, resolve scope, inspect, analyze, findings, Memory drift note, complete; no implementation stage and no writes.
A[Authorized context] --> B[Resolve scope] --> C[Inspect] --> D[Analyze / review] --> E[Findings] --> F[Memory drift note] --> G[Complete in chat]

No stage writes anything: no source, tests, Memory, index, report file, formatter, settings, or approval record. If you later authorize a fix, the agent reports the scope transition and re-runs preflight and routing under the appropriate write procedure.

4. Memory lifecycle

Defined in: workflows/memory-lifecycle.md. An eight-step lifecycle used whenever Memory is read or changed:

flowchart TD
accTitle: Memory lifecycle
accDescr: Check authority and canonical path, read index and entries, check facts, then branch into matching, stale, decision conflict, or insufficient evidence, and assess Memory impact; writes happen only through the authorized delta procedure.
A1[1 · Authority + canonical path] --> A2[2 · Read index + relevant entries]
A2 --> A3[3 · Check facts against current evidence]
A3 --> M{Result}
M -->|matches| A4[4 · Use within verified scope]
M -->|observation contradicted| A5[5 · STALE → propose correction]
M -->|code vs approved decision| A6[6 · Architecture Drift → CONFLICT]
M -->|evidence missing| A7[7 · UNVERIFIED → report gap]
A4 --> A8[8 · Assess Memory impact]
A5 --> A8
A6 --> A8
A7 --> A8
A8 --> W{Necessary delta +<br/>write authority?}
W -- no --> NOOP[No write · no date refresh]
W -- yes --> RR[Reread entry, index, human text] --> AP[Apply minimal patch<br/>or stop on conflict]

The record-status model follows from this lifecycle:

stateDiagram-v2
accTitle: Memory record statuses
accDescr: Observations move from ACTIVE to ARCHIVED. Proposals start PROPOSED and end REJECTED or SUPERSEDED, or become an APPROVED decision only with evidenced approval. Decisions can later be SUPERSEDED or REVOKED.
direction LR
[*] --> ACTIVE: observation recorded
ACTIVE --> ARCHIVED
[*] --> PROPOSED: proposal recorded
PROPOSED --> REJECTED
PROPOSED --> SUPERSEDED
PROPOSED --> APPROVED: evidenced approval authority
[*] --> APPROVED: decision with approval source
APPROVED --> SUPERSEDED: revised with real approval
APPROVED --> REVOKED

Verification status (VERIFIED, STALE, UNVERIFIED) is tracked separately from record status. A decision can be APPROVED and still unverified against code.

5. Governance decision flow

Defined in: governance/ai-usage.md (KIYO-GOV-001) with risk-assessment.md and human-approval.md.

flowchart TD
accTitle: Governance Review outcomes
accDescr: Resolve the concrete action and target, check for prohibitions or host denial leading to DENY, then assess mode and risk, check for missing facts or approval leading to HOLD, otherwise PROCEED with only the stated action.
A[Concrete action, target,<br/>environment, data] --> B{Prohibition or<br/>host denial?}
B -- yes --> DENY[DENY<br/>confirmation cannot override]
B -- no --> C[Governance mode G1–G4<br/>+ risk over 8 dimensions]
C --> D{Missing fact, target,<br/>or required approval?}
D -- yes --> HOLD[HOLD<br/>ask only for the missing item]
D -- no --> PROCEED[PROCEED<br/>stated action only]
HOLD -->|valid scoped approval| PROCEED

6. Failure and handoff

Defined in: workflows/repair-and-handoff.md (KIYO-FLOW-004, KIYO-FLOW-005).

• Classify each failure as baseline, new regression, environment problem, unresolved cause, or evidenced flakiness.
• Repair at most two unsuccessful cycles by default. Each cycle is one hypothesis, one bounded correction, and one recheck.
• Stop earlier if the repair is unsafe, denied, unsupported, blocked, evidence-free, or out of scope.
• Hand off in chat with intent and scope, facts and evidence, decisions and unknowns, approval scope, checks and repairs used, Memory impact, and the next action. A handoff cannot grant access or reset the repair counter.

Related

• Loading and activation
• Skills and routing