Skip to content

Init

Logical ID: kiyo.init · Entry: src/kiyo/skills/init/SKILL.md · Procedure: workflows/init.md (KIYO-INIT-001)

Purpose

Section titled “Purpose”

Init onboards Kiyo to a repository. It performs a bounded initial analysis, creates or incrementally updates Project Memory and the local Kiyo configuration, and reports setup readiness. It is the only Skill that creates Kiyo project state from nothing.

Use it when you explicitly want onboarding, an initial project analysis, Memory creation, or a setup-readiness check. Do not use it just because you are adding a feature or fixing a bug, or because Memory is missing. Init does not run automatically for every feature, and an ordinary change request never triggers it.

Modes and access contract

Section titled “Modes and access contract”
Mode / access Boundary
Preview / readiness / initial analysis Authorized inspection and chat output only; no source, Memory, config, bootstrap, or report-file writes
Initialize / incremental update Write only the necessary project-local Memory and config, plus a needed managed bootstrap block, within the actual request. An explicit initialize request already covers these bounded state writes
Read Applicable instructions, existing Kiyo state, and a bounded sample of manifests, docs, and representative source and test text
Execute Only inspected non-mutating metadata, file, or Git checks; never your build, test, install, migration, or deploy scripts
Forbidden writes Application source, dependencies, manifests, lockfiles, tests, global settings, credentials; no Git init, reset, clean, stash, scaffolding, installs, or runtime components

Procedure

Section titled “Procedure”

The twelve-step procedure orders work so nothing is written before root, existing state, and scope are known:

flowchart TD
accTitle: Init procedure
accDescr: Twelve steps from establishing the root and Git baseline through discovery, sampling, proposals, authority, scoped writes, optional bootstrap, and verification.
S1[1 · Root, scope, Git baseline] --> S2[2 · Discover existing Kiyo state<br/>and instructions]
S2 --> S3{3 · Incremental update<br/>or no-op?}
S3 --> S4[4 · Sample evidence<br/>≤16 files / 1,200 lines]
S4 --> S5[5 · Evidence-backed observations]
S5 --> S6[6 · Separate facts, unknowns,<br/>proposals, constraints]
S6 --> S7[7 · Select profiles / presets<br/>from evidence only]
S7 --> S8{8 · Missing authority?}
S8 -- preview --> R[Report proposal · zero writes]
S8 -- authorized --> S9[9 · Apply scoped state changes]
S9 --> S10[10 · Managed bootstrap block<br/>only if needed and authorized]
S10 --> S11[11 · Preserve human / native instructions]
S11 --> S12[12 · Verify and report readiness]

Preview stops at step 8 with a proposal. Initialization proceeds only for the authorized delta, and rereads target files immediately before writing.

Bounded discovery

Section titled “Bounded discovery”

From framework/init-discovery.md: start with at most 16 project text files / 1,200 inspected lines in total.

Priority Initial allocation
Instructions and state orientation Up to 6 files / 300 lines
Project definition (manifests, config, docs) Up to 6 files / 500 lines
Representative implementation and tests Up to 4 files / 400 lines

Generated, vendor, and build output, binaries, and bulk lockfiles are skipped. Credentials and secret environment values are never read. An empty repository stays “stack Unknown”. Init does not invent a language or start application code.

What it creates (new, unconfigured project)

Section titled “What it creates (new, unconfigured project)”
  • .kiyo/policy.md: the project-context record (template). An existing .kiyo/config.md is reused instead; never both.
  • .kiyo/memory/index.md, plus only topic files that have real entries (for example project.md). No empty topic set is created.
  • Optionally, one managed block in CLAUDE.md, AGENTS.md, or Copilot instructions, only if persistent guidance was requested and the host facility is evidenced.

Rerunning Init on unchanged state is a no-op: no rewrite, reformatting, or date change.

Output

Section titled “Output”

Init reports, in chat:

  • an evidence-backed summary of the inspected component and current state;
  • unknowns and uninspected areas;
  • proposals kept separate from sourced constraints;
  • selected profiles;
  • the exact Memory, config, and bootstrap delta, or no-op;
  • activation readiness, with its limits;
  • check records, Memory impact, status, and next action.

Activation readiness keeps these facts separate: package installed or discovered, agent-directed Core read, project guidance present, and actual automatic loading. Creating files never proves automatic loading.

Edge cases

Section titled “Edge cases”
Situation Behavior
Multiple candidate roots or stores Decision required before any write
Legacy .kiyo/project/memory/ store exists Preserved; no .kiyo/memory/ is created alongside
Human-modified managed block Reconciled with you; never overwritten from the template
Instruction files inaccessible Treated as unknown, not as an unconfigured repository
Requested setup cannot be fully completed PARTIALLY COMPLETE or BLOCKED, not DONE

Source and tests

Section titled “Source and tests”
Section titled “Related”