kyos-cli

kyos-cli is a repo-local CLI for standardizing Claude Code setup across many repositories. It installs a base .claude/ layout and keeps a managed source layer under .kyos/claude/ so updates are repeatable. Repo-owned customizations live in .claude/, and updates are guarded by .kyos/lock.json so local edits aren't overwritten silently.

It also ships workflow prompts like /kyos:architecture and /kyos:hire for bigger planning, plus a feature delivery chain (/kyos:spec -> /kyos:tech -> /kyos:tasks -> /kyos:implement -> /kyos:verify) that works for features and complex bugfixes.

Quickstart

npx kyos-cli --init

Behavior:

• If the repo has no Claude setup yet, --init bootstraps CLAUDE.md, .claude/, and .kyos/.
• It also seeds a default silent-executor agent (Haiku) and its paired silent-executor skill so repos have a concise, execution-first mode available immediately.
• Commands, agents, and skills live under .kyos/claude/ as the managed source of truth; .claude/ contains thin wrappers that link to the managed definitions (so updates are repeatable without overwriting local edits).

CLI commands

Supported entrypoints:

• npx kyos --init [--force] (alias: npx kyos-cli --init [--force])
• npx kyos --update (destructive to .kyos/ only)

Workflow commands

kyos-cli ships workflow prompts under .claude/commands/ for Claude-side usage as slash-style commands:

/kyos:prevalidate
/kyos:architecture

/kyos:hire
/kyos:spec
/kyos:tech
/kyos:tasks
/kyos:implement
/kyos:verify

Foundation commands:

• /kyos:prevalidate runs a quick read-only safety/security scan before you start running tools or changing code.
• /kyos:architecture sets or revises the repo's technical direction.
• /kyos:hire adds missing support around the current stack.

Daily delivery commands:

• /kyos:spec writes a user-facing feature definition.
• /kyos:tech turns the feature into an engineering plan.
• /kyos:tasks breaks the plan into ordered execution slices.
• /kyos:implement executes the plan in verified slices.
• /kyos:verify checks the implementation against the spec and plan.

Recommended flow:

/kyos:spec -> /kyos:tech -> /kyos:tasks -> /kyos:implement -> /kyos:verify

The built-in command definitions are managed under .kyos/claude/commands/. .claude/commands/ is seeded as the user-facing entrypoint folder with short wrapper files that link to the managed definitions, so updates are repeatable while the command surface stays in the standard place.

Managed vs local files

kyos-cli uses a two-layer model:

• .kyos/claude/ holds the managed source layer generated by the framework.
• .claude/ is the repo-owned override and customization layer.
• .kyos/ also holds framework state such as config.json, version.json, and lock.json.

Architecture

This uses a split architecture:

• the CLI handles deterministic mutations in process.cwd().
• the registry or catalog layer stays separate and discoverable.

In this prototype, the catalog layer is represented by catalog/registry.json.

Installed layout

CLAUDE.md
.claude/
  agents/
  commands/
  rules/
  skills/

 .kyos/   (generated by kyos-cli in target repos)
  claude/
    agents/
    commands/
    rules/
    skills/
    settings.json
  config.json
  version.json
  lock.json

.mcp.json

Existing repo behavior

If a repo already contains .claude/ or CLAUDE.md, the default command does not mutate files. It prints proposals such as:

+ would add .claude/skills/README.md
~ would update .claude/settings.json
! CLAUDE.md (unmanaged file already exists with different content)

Multi-repo rollout

Because the CLI runs only in the current working directory, you can apply it repo-by-repo from another script:

$repos = @(".\\repo-a", ".\\repo-b", ".\\repo-c")
foreach ($repo in $repos) {
  Push-Location $repo
  npx kyos-cli --init
  Pop-Location
}