Skip to content

Add a stack profile

Goal: add evidence-bound guidance for a technology Kiyo does not cover yet, such as React or Java, without forcing it on any project. Contract: profiles/extension-contract.md (KIYO-PROF-001) · Audience: framework maintainers

What a profile is

Section titled “What a profile is”

A profile supplements the shared engineering checks for a specific stack. It never replaces Core, never implies a project uses that stack, and never installs anything. The existing profiles are .NET, Angular, Python, and PostgreSQL. React, Java, and company profiles exist only as synthetic proposal outlines in the contract.

Agents select a profile only after inspecting actual versions, config, toolchain, and architecture. Init, for example, confirms global.json and .csproj files before choosing the .NET profile.

The six required parts

Section titled “The six required parts”

The extension contract requires every new profile to state:

  1. Identity: maintainer or source, and accepted scope.
  2. Entry discovery: how to establish the stack from evidence, with version ranges only where evidenced.
  3. Conditional checks: engineering and security checks, expected output evidence, and explicit non-goals. Presets are proposals or opt-in, never automatic installs.
  4. Package-contained references: relative links inside the package, plus optional dated provenance. No developer paths, symlinks, scripts, runtime, or secrets.
  5. Support status: authored, static review, executed, or per-target.
  6. Scoped maintenance: a change process that keeps stable control IDs.

Steps

Section titled “Steps”
  1. Author the profile as src/kiyo/profiles/<stack>.md in the canonical source. Never edit a generated copy under dist/.
  2. Link it from the engineering selection reference, framework/engineering/index.md, so agents can find it when relevant.
  3. Update the input allowlist. The packager rejects product files that are not in tools/packaging-inputs.json, with the error “Product tree differs from reviewed input allowlist”. Add the new path intentionally.
  4. Regenerate the packages into fresh output paths (see Developer tooling).
  5. Run the checks. Static contracts verify links, anchors, budgets, and neutral content; packaging tests verify parity across all eight Skill snapshots.

The product file count (currently 105) and some counts asserted by the tests will change. Update the related documentation and evidence records rather than editing tests to match.

Writing guidance that fits the framework

Section titled “Writing guidance that fits the framework”
  • Tell agents to inspect first: which files establish the version and configuration.
  • Preserve existing choices. Kiyo’s .NET profile, for example, treats xUnit, Mapperly, FluentValidation, and ProblemDetails as recommendations or opt-in preset choices only, and imposes no architecture on legacy code.
  • Keep “creating a file” separate from “executing an operation”. The PostgreSQL profile keeps migration authoring separate from running it.
  • Cite external documentation with a check date and DOCUMENTED_ONLY status. Do not claim fixture execution you did not perform.
Section titled “Related”