kyos-cli

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.

Prerequisites

• Node.js 18 or later
• npm / npx (bundled with Node)
• Claude Code installed

Quickstart

bash / zsh:

npx kyos-cli --init

PowerShell:

npx kyos-cli --init

Behavior:

• If the repo has no Claude setup yet, --init bootstraps CLAUDE.md, .claude/, and .kyos/.
• Running npx kyos-cli with no flags also runs --init.
• It seeds a silent-executor agent (Haiku) and its paired silent-execution 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 reference

Command	Description
kyos-cli --init	Bootstrap or analyze existing setup (default when no flag is given)
kyos-cli --init --force	Destructively reset .claude/, .kyos/, and CLAUDE.md to baseline
kyos-cli --apply	Write only missing managed files — never overwrites existing files
kyos-cli --update	Force-rewrite .kyos/ to current baseline (.claude/ is untouched)
kyos-cli --add <type> <name>	Add a skill, agent, or MCP from the catalog
kyos-cli --doctor	Check managed file integrity and report drift

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. (minimal stub — add repo-specific guidance in .claude/commands/architecture.md)
• /kyos:hire adds missing support around the current stack. (minimal stub — add repo-specific guidance in .claude/commands/hire.md)

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.

Catalog

Add capabilities from the built-in registry with --add:

kyos-cli --add skill release-notes
kyos-cli --add skill security-audit
kyos-cli --add skill path-safety
kyos-cli --add skill mcp-hardening
kyos-cli --add skill secrets-and-supply-chain

kyos-cli --add agent triage

kyos-cli --add mcp context7
kyos-cli --add mcp filesystem

Each --add skill or --add agent creates a local stub under .claude/ that you can fill with repo-specific guidance. Each --add mcp registers the server in .mcp.json.

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.

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   (created by --add mcp)

Existing repo behavior

If a repo already contains .claude/ or CLAUDE.md, --init switches to analysis mode and prints proposals without changing files:

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

To apply only the missing files (safe, never overwrites):

npx kyos-cli --apply

To reset everything to baseline (destructive):

npx kyos-cli --init --force

Conflict and blocked states

• conflict — the file is tracked in .kyos/lock.json but its content has changed since it was last managed. The file has local edits kyos won't overwrite.
• blocked — a file exists at a managed path but was never recorded in the lock file, so kyos treats it as unmanaged and won't touch it.

In both cases, resolve by either accepting the baseline (--init --force) or keeping your version (no action needed — kyos will leave the file alone).

Multi-repo rollout

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

bash / zsh:

for repo in ./repo-a ./repo-b ./repo-c; do
  (cd "$repo" && npx kyos-cli --init)
done

PowerShell:

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

Security

• Zero runtime dependencies — no third-party code runs when you install or use kyos-cli.
• No install scripts — package.json declares no preinstall, postinstall, or install hooks. Nothing executes at install time.
• Publish provenance — every release is published with npm provenance attestation via GitHub Actions, so the build source is cryptographically verifiable.
• Lockfile committed — package-lock.json is committed and regenerated on every release to prevent dependency drift.
• Path traversal protection — all file I/O is validated in src/core/fs.js: relative paths only, no .. segments, no symlinks escaping the repo root.

To report a vulnerability, see SECURITY.md.