AI guesses project facts
It may invent a service, route, schema, or architecture because the answer sounds familiar from training data.
Learn
Kiyo is a set of Markdown rules for AI coding tools.
Think of Kiyo as the onboarding guide, safety checklist, workflow router, and verification reminder that an AI must read before helping in your codebase. Claude Code is the native-first host. Codex, GitHub Copilot, and OpenCode CLI remain compatible.
AI changes too much
A small fix can turn into a broad refactor when scope is not explicit.
AI overclaims success
A response can say fixed or tests pass even when no build or test command ran.
AI picks the wrong workflow
Too many similar-sounding commands make it easy to reach for the wrong one for the job.
First project flow
Start with initialization. After that, every mission should read the generated project facts before it reads source code.
Core ideas
The small vocabulary that makes Kiyo work.
Project Memory
A project-local folder of facts the AI must read first.
.kiyo/project/ is created by /kiyo-init. It records structure, detected architecture, conventions, testing patterns, working rules, and onboarding notes.
One mission
One request should become one bounded job.
Kiyo separates broad requests into a current mission plus deferred follow-ups. This keeps diffs reviewable.
Safety Mode
The risk level for the task.
standard is normal focused work. strict requires approval planning. deep is read-only by default.
Verification Status
The honest final status of a code-changing task.
Allowed values are Verified, Implemented but not verified, Not verified, and Could not verify.
Specialist Agent
A Markdown role contract, not a background service.
Kiyo currently ships 8 Specialist Agent contracts: architect-planner, audit-specialist, legacy-specialist, migration-specialist, performance-investigator, refactor-surgeon, security-reviewer, and test-writer.
Auto skill
A discipline rule the host applies from prompt context.
Auto skills cover no hallucination, existing pattern first, token-efficient context, surgical change, runtime verification, compact response, and more.
Without Kiyo discipline
- User asks for a bug fix.
- AI assumes a stack or pattern.
- AI edits nearby code too.
- AI says the fix works.
- No command proves it.
With Kiyo discipline
- User runs /kiyo-bug-fix.
- AI reads Project Memory first.
- AI detects the affected layer.
- AI makes the smallest safe change.
- AI reports the real Verification Status.