Knowledge Islands Enter Arcadia
Menu

← Docs · Standards

Repository standards

You can tell what a repository is, which standards govern it and how to bring it into line by reading its declarations, choosing the appropriate shape and checking each layer against its own contract.

Interim - Repository metadata is maintained through the review practice described below. Its agreed source direction and topic conventions are applied explicitly; the pinned repository checker covers only the checks identified here.

Repository contract, shapes and overlays An architecture diagram generated by Archify. Universal contract · .ki.toml, root files, identity · Architecture component Universal contract .ki.toml, root files, identity Project kind · Explicit declared core shape · Architecture component Project kind Explicit declared core shape Website shape · Neutral build / dev / clean seam · Architecture component Website shape Neutral build / dev / clean seam Knowledge Base kind · Five indexed zones · Architecture component Knowledge Base kind Five indexed zones Other Project shapes · General, harness, tools, MCP · Architecture component Other Project shapes General, harness, tools, MCP Select one implementation · Content: Eleventy / App: Vite · Architecture component Select one implementation Content: Eleventy / App: Vite Independent hosting overlay · Consumes portable dist/ · Architecture component Independent hosting overlay Consumes portable dist/ declares declares may select may select requires dist/ seam Legend Backend Database Cloud Security
Every repository has a universal contract and an explicit primary shape. Supporting standards add capabilities without changing that identity. Interactive

What it is

A Knowledge Islands repository is a Git repository with .ki.toml at its root. The file declares the standards it follows. It records identity, purpose and ownership alongside one table for each governing skill. A declaration makes a rule applicable; it does not install a tool, activate a runtime or prove compliance.

Every repository explicitly declares repo_type, either project or kb, and primary_shape under [skills.ki-repo]. A Knowledge Base chooses ki-repo-kb; a Project chooses a declared core shape, with ki-repo-project as the general baseline. Neither value is inferred from a folder name.

How it works

The universal contract covers the root README, licence, ignore rules and configuration, alongside repository identity and GitHub settings. A README explains purpose and entry points. Visibility and licence are separate declarations. The applicable shape then governs the artefact the repository holds:

  • A Knowledge Base keeps indexed zones for records, knowledge, references, work and administration, described in Knowledge bases.
  • A general Project supplies the non-Knowledge-Base baseline. A harness holds skills, subagents, evals and hooks, and distinguishes source from a verified installed payload.
  • A tools repository holds one command-line tool and its delivery surface. A Homebrew tap holds formulae for released tools. An MCP repository governs server source, configuration injection and access boundaries.
  • A Specifications repository separates proposals, specifications, schemas, templates, examples, documentation and tooling. A chezmoi repository governs configuration source and rendering discipline.
  • A website declares the neutral build seam, then exactly one content or app implementation. Content uses Eleventy; an app uses React and Vite. Cloudflare hosting is an independent overlay consuming the built dist/.

Supporting declarations compose with the primary shape. A content website can therefore declare the website core, content implementation, hosting, engineering and writing standards without acquiring five different identities. Each standard owns its own table and concern; dependencies make required neighbours explicit.

The directional working areas have the same meaning across shapes: +/ holds inputs for local work, including locally created working records; -/ holds produced outputs. Specialist owners govern such subdirectories as work packages and trades. The ignored tmp/ area is disposable. None is a second home for settled knowledge or an ungoverned roadmap.

Repository metadata in practice

Metadata review begins with .ki.toml under [skills.ki-repo]. Description, repository URL, visibility and licence are checked against their relevant mirrors. Where a root package.json exists, its corresponding values agree. Public repository discovery topics are compared with package keywords where present. These are existing checks; managed topic derivation and territory-specific topics are reviewed explicitly.

The interim practice keeps description, optional homepage and discovery keywords in .ki.toml, then mirrors the intended values to GitHub and the root package manifest. It never promotes a mirror into authority merely because that mirror already contains a value. A homepage identifies this repository's current landing page, including a preview address where appropriate; review it before copying it, and leave workspace packages' own homepages alone. Omitting the declaration does not authorise silently clearing a live value.

Managed GitHub topics use the bare knowledge-islands topic, one ki-territory-<prefix>, one ki-shape-<shape> and a Capital role topic only on the designated Capital. The topic forms are:

knowledge-islands
ki-territory-<prefix>
ki-shape-<shape>
ki-role-capital

Territory comes from the declared Capital's prefix. Shape comes from primary_shape with its leading ki-repo- removed; supporting overlays add no shape topic. A territory can declare additional single-word types under a declared code, yielding <territory-code>-<type>-<value>. Discovery keywords remain separate: managed and territory topics stay out of package keywords. Only non-secret values belong in metadata, including for private repositories.

Educate, audit, conform and re-audit A workflow diagram generated by Archify. 01 / Understand and review 02 / Repair and verify Educate · Establish declared foundations · Understand and review Educate Establish declared foundations Audit · Inspect each applicable layer · Understand and review Audit Inspect each applicable layer Review repairs · Authorise exact changes · Understand and review Review repairs Authorise exact changes Conform · Repair authorised local gaps · Repair and verify Conform Repair authorised local gaps Re-audit · Check convergence · Repair and verify Re-audit Check convergence Reviewed result · Mechanical and judgement evidence · Repair and verify Reviewed result Mechanical and judgement evidence gaps closed authorised Legend Agent logic Policy Context / trace
Educate establishes the foundations, audit names the gaps, conform applies approved repairs and re-audit checks the result. Interactive

How you use it

Mara starts the fictional Tern Holm survey repository by describing its purpose and choosing a general Project shape. She uses first-time setup to establish her local installation, then follows this loop:

  1. Educate: establish the repository's declarative foundations and understand each selected standard. Keep machine-level activation separate from repository declarations.
  2. Audit: inspect the universal contract and every applicable layer. Missing or incompatible capabilities stop execution rather than being guessed into existence.
  3. Conform: review the proposed repairs, apply the authorised local changes and handle judgement-led content gaps. Live GitHub settings require their own explicit approval.
  4. Re-audit: check that the gaps have closed and review the parts a mechanical checker cannot assess, such as whether the description fits the repository.

The repository and territory commands explain how registration, harness selection and repository operations fit together. Registration records a physical checkout; it is inventory, not a compliance verdict.

What it provides

You get a portable statement of what the repository is and which rules apply, with separate owners for universal setup, artefact shape and supporting capabilities. Audits expose drift; the review loop makes correction deliberate and repeatable.

Boundaries

Passing an audit does not grant authority to publish, change provider settings or appoint a Capital. Source shape does not prove runtime health. Metadata review does not change visibility or licence by implication, and the interim topic practice is not presented as an automated check at this pinned revision. Engineering and Git govern implementation and commits; writing governs how the resulting knowledge is expressed.