Skip to content

Getting Started

This guide walks through a complete first session, from installed package to your first evidence-backed task. It assumes you finished Installation. Every prompt below is ordinary text typed into your host after selecting a Skill. None of it is a Kiyo command.

Prerequisites

Section titled “Prerequisites”
Requirement Detail
Host Claude Code (CLI or VS Code), Codex CLI, or GitHub Copilot (CLI or VS Code), signed in with your own account
Kiyo package Installed from a complete prepared package, with all eight Skills visible
Repository A Git repository. Git is optional for Kiyo, but it makes read-only checks easy to verify
Runtime None. Kiyo ships no executable, so there are no SDK, Node.js, or Python requirements for users

1. Preview onboarding

Section titled “1. Preview onboarding”

Select Init (/kiyo-axiom-framework:init in Claude Code) and send:

Preview onboarding for this repository; report evidence, unknowns and proposed Memory/config/bootstrap changes without writing files.

Init follows its twelve-step procedure. In preview mode it:

  • establishes the project root, the worktree, and the Git state (staged, unstaged, and untracked changes are preserved);
  • looks for existing Kiyo state, .kiyo/policy.md, a Memory index, and CLAUDE.md / AGENTS.md / Copilot instructions;
  • samples at most 16 files and 1,200 lines: instructions and state, manifests and docs, and representative source and tests;
  • reads scripts as text only and never runs your build, tests, or installers;
  • proposes profiles (for example .NET or Angular) only when actual config and source support them.

Verify with git status. Preview must change zero files.

2. Initialize the proposed state

Section titled “2. Initialize the proposed state”

If the proposal looks right, ask for exactly that:

Create only the proposed project-local Memory/config; preserve existing instructions.

For a new, unconfigured project, the defaults are:

  • Directory.kiyo/
    • policy.md project context and preferences (seven logical fields)
    • Directorymemory/
      • index.md navigation by stable entry ID
      • project.md only topic files that have real entries
  • CLAUDE.md optional managed block, only if you asked for persistent guidance

Existing locations are preserved. A legacy .kiyo/project/memory/ store stays where it is, and an established .kiyo/config.md is reused instead of adding a second config. Init never scaffolds application code, installs dependencies, or initializes Git. See Project state and configuration for every field.

The optional managed block is a short, marked section of your host’s own instruction file. It points the agent at your .kiyo/ state and must stay within 250 words:

CLAUDE.md (excerpt, managed block shape)
<!-- KIYO:BEGIN project-context -->
Kiyo project guidance (advisory; respects the actual native instruction hierarchy).
Adapter revision: init-locator-1.
Last reviewed product version: UNKNOWN.
...
<!-- KIYO:END project-context -->

3. Run a first daily task

Section titled “3. Run a first daily task”

A good first task is a read-only review of work you already have:

  1. Make or keep a small uncommitted change in the repository.
  2. Select Review and send: Review my current workspace changes for correctness and authorization. Do not edit files or run build/test scripts.
  3. Check git status again. Review writes nothing, not even a report file.

Then try a scoped change with Implement:

Fix the supplied boundary error and add its regression test; preserve unrelated edits.

Implement inspects the command and its environment before running checks. It runs only checks that fit your request, and it reports anything it could not run as NOT_RUN or BLOCKED rather than PASS.

4. Read the report

Section titled “4. Read the report”

Every Skill closes with the same eight-part report, in chat by default:

Field What to look for
Task/scope What was requested, the inspected boundary, and exclusions
Actions/files changed What was read, changed, or executed, with proposals kept separate
Governance/risk rationale Why the action was in scope, plus any approval used
Verification/evidence One nine-field record per check: PASS, FAIL, NOT_RUN, NOT_APPLICABLE, or BLOCKED
Residual issues Failures, unknowns, and deferred findings
Memory impact NONE, UPDATE_REQUIRED, CONFLICT, or NOT_ASSESSED
Status DONE, PARTIALLY COMPLETE, BLOCKED, or DECISION REQUIRED
Next required action The concrete next step, or none

A DONE review means the bounded review was delivered. It does not mean tests passed. See Checks, completion, reports.

Troubleshooting the first session

Section titled “Troubleshooting the first session”
Symptom Likely cause and next step
The host runs its own /init or /review You invoked a built-in command. Use the Kiyo selector from Host commands
Agent says resources under references/kiyo/ are missing The package is incomplete. Reinstall from a complete ZIP or dist/ package
Agent never mentions Kiyo rules The Core loads only after the Skill is selected. Select the Skill explicitly and state the intent
Preview wrote files That violates the preview contract. Capture the diff and report it as a defect

More in Troubleshooting.

Where to go next

Section titled “Where to go next”