Architecture overview

Kiyo’s architecture is set out in ADR-001: one canonical static specification with contained Skill resources. Everything a user installs is generated from a single authored source. Nothing is executed, and all mutable state stays in the user’s repository.

Architectural style

Static and advisory. Markdown instructions only: no runtime, CLI, MCP server, hook, LSP server, service, database, or telemetry.
Single source of truth. Product rules are authored once under src/kiyo/. Long rules live in shared files and are referenced by stable control IDs, never copied into Skills.
Build-time derivation. Developer-only Python tools render host packages. Users never run them.
Self-contained packages. Each installed Skill carries a complete snapshot of the shared rules, so every link resolves inside that Skill’s folder.
Host sovereignty. The host agent enforces permissions and decides what loads; Kiyo never claims otherwise.

System context

flowchart LR
accTitle: System context
accDescr: A maintainer authors canonical source and runs developer tools that produce packages. Catalog files expose packages to hosts. A developer uses a host agent which loads the package and works in the developer's repository, where Kiyo project state lives.
subgraph Maintainer side
M([Maintainer]) --> SRC[src/kiyo<br/>canonical product content]
M --> OV[platforms/*<br/>host overlays]
SRC --> TOOLS[tools/*.py<br/>developer-only packagers]
OV --> TOOLS
TOOLS --> DIST[dist/<br/>generated packages + ZIPs]
DIST --> CAT[root catalogs<br/>.claude-plugin · .agents · .github]
end
subgraph User side
DEV([Developer]) --> HOST[Host agent<br/>Claude Code · Codex · Copilot]
HOST -->|installs / loads| PKG[Installed Kiyo package<br/>read-only]
HOST -->|reads / writes within permissions| REPO[(User repository<br/>code + .kiyo/ state)]
end
CAT -. install route .-> HOST

The left side exists only in the framework repository. The right side is what users see: a host, an immutable installed package, and their own repository. The dotted line is the only connection between the two sides, and it is a native install route, not a Kiyo installer.

Five ownership boundaries

From framework-layout.md:

Boundary	Location	Ownership and lifetime	Installed?
Product content	`src/kiyo/`	Maintainer-authored, versioned, immutable within a released bundle	Yes, as generated copies
Project-local state	The consumer repository’s `.kiyo/` paths (or established equivalents)	User/project-owned; mutable only with authorization	Never part of a plugin payload
Platform overlays	`platforms/claude/`, `platforms/codex/`, `platforms/copilot/`	Maintainer-authored native metadata and instruction adapters	Only the resulting host metadata and adapter
Developer material	`docs/`, `tools/`, `tests/`	Research, decisions, build, test, and release tooling, and evidence	Excluded from payloads
Generated distributions	`dist/<ecosystem>/`	Disposable derivatives; never hand-edited	The native package itself

Content layers and dependency direction

flowchart TD
accTitle: Content layers and allowed references
accDescr: Skills reference the bootstrap and shared workflows. Workflows reference Core framework rules, governance and security policies, profiles, and templates. Core does not depend on skills.
SK[skills/*/SKILL.md<br/>intent · modes · access contract] --> KB[KIYO.md + framework/bootstrap.md]
SK --> WF[workflows/<br/>router · flows · procedures]
WF --> FW[framework/<br/>authority · evidence · DoD · reporting · Memory]
WF --> GOV[governance/ · agent-security/<br/>policies and review procedures]
WF --> PR[profiles/<br/>optional stack guidance]
WF --> TP[templates/<br/>neutral artifacts]
GOV --> FW
PR --> FW
KB --> FW

References point inward: Skills → workflows → Core. Core never depends on a Skill, and shared content never depends on another Skill’s SKILL.md. A profile supplements engineering checks and never replaces Core.

Content	Owns	References (never duplicates)
Core (`framework/`)	Authority, evidence and check records, completion, reporting, scope vocabulary, Memory protocol, stable controls	Other Core sections; no native schema details
Policies (`governance/`, `agent-security/`)	Governance, data, action policies; security review procedures and limits	Core IDs and templates; no claim of host enforcement
Workflows	Routing, task sequence, repair limits, closure	Core, policies, profiles, templates
Engineering (`framework/engineering/`)	Requirements, architecture, coding, testing, quality, change-scope checks	Core, governance, security, profiles
Profiles	.NET, Angular, Python, PostgreSQL guidance	Engineering controls; no forced stack
Templates	Neutral artifact structure with evidence and unknown fields	Stable IDs; no developer project knowledge
Skills	Intent, mode, read/write/execute contract, entry sequence	Bootstrap and shared procedure links

Framework versus application responsibilities

Kiyo framework provides	The application team and host provide
Procedures for eight workflows and when to use each	The request, scope, and business decisions
Access contracts (advisory read, write, execute boundaries)	Actual permissions, sandboxing, network controls
Evidence, completion, and reporting formats	The build, test, and CI infrastructure the agent runs
The Memory record format and safe update procedure	The `.kiyo/` content itself, reviewed and owned
Security assessment procedures and the AST mapping	Incident response, disclosure, revocation
Neutral policy and preset templates	Accepted, authoritative policy