Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

kyos-cli

Package Overview
Dependencies
Maintainers
1
Versions
22
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

kyos-cli - npm Package Compare versions

Comparing version
0.3.4
 to
0.3.5
+6
-4
catalog/claude-base/claude/commands/implement.md

@@ -17,8 +17,10 @@ # /kyos:implement

- feature context
- technical plan
- execution task file (if provided)
- current repo state
- available specialists/agents, skills, and MCPs
- `docs/execution/<spec-slug>/spec.md` — read automatically if it exists
- `docs/execution/<spec-slug>/tech.md` — read automatically if it exists
- `docs/execution/<spec-slug>/tasks.md` — read automatically if it exists (treated as the execution task file)
Derive the slug from the argument if provided; otherwise glob `docs/execution/*/` and use the most recently modified folder.
## Workflow

@@ -78,3 +80,3 @@

1. Review the feature and technical context.
1. Locate the execution folder (from argument or most recently modified `docs/execution/*/`). Read `spec.md`, `tech.md`, and `tasks.md` from that folder — all that exist. Treat `tasks.md` as the source of truth for progress and remaining work.
2. Select the next concrete slice (or small set of independent slices).

@@ -81,0 +83,0 @@ 3. Search for relevant specialists/agents and spawn multiple in parallel when the slices are independent.

+17
-0
catalog/claude-base/claude/commands/spec.md

@@ -57,7 +57,24 @@ # /kyos:spec

5. Save the result into a local planning note.
6. After saving, check whether `tech.md` or `tasks.md` already exist in the same execution folder. If either exists, append a **Related** section to spec.md with links to the existing sibling artefacts.
## Next in flow
If the context meter is at 50% or more, run `/compact` before continuing — the spec is saved to disk so nothing is lost.
Continue with [`/kyos:tech`](./tech.md) to turn the feature behavior into an engineering approach.
## Related section format
The **Related** section belongs at the bottom of the artefact, above any trailing notes. Use this shape:
```markdown
## Related
- [Spec](./spec.md)
- [Tech](./tech.md)
- [Tasks](./tasks.md)
```
Only include links that exist. When updating a sibling artefact, append the section if absent or insert the missing link into an existing section — do not duplicate entries.
## Where to save the result

@@ -64,0 +81,0 @@ 

+32
-3
catalog/claude-base/claude/commands/tasks.md

@@ -18,7 +18,9 @@ # /kyos:tasks

- the current feature spec
- the technical plan
- current repo context and obvious code hotspots
- existing test setup (test runner, frameworks, and CI checks), if any
- `docs/execution/<spec-slug>/spec.md` — read automatically if it exists
- `docs/execution/<spec-slug>/tech.md` — read automatically if it exists
Derive the slug from the argument if provided; otherwise glob `docs/execution/*/` and use the most recently modified folder.
## How to break work down

@@ -48,2 +50,19 @@

## Before writing tasks
Before breaking work down, Claude should:
1. Locate the execution folder (from argument or most recently modified `docs/execution/*/`).
2. Read `spec.md` if it exists — use it to anchor scope and acceptance criteria.
3. Read `tech.md` if it exists — use it to anchor sequencing, interfaces, and risks.
4. If neither exists, proceed but note the missing context.
## Cross-linking
After saving tasks.md, Claude should:
1. Include a **Related** section in tasks.md with links to `spec.md` and `tech.md` (both required; note if one is missing).
2. Open `spec.md` in the same execution folder and add or update a link to `tasks.md` in its **Related** section (create the section if absent).
3. Open `tech.md` in the same execution folder and add or update a link to `tasks.md` in its **Related** section (create the section if absent).
## What Claude should return

@@ -67,4 +86,14 @@

Continue with [`/kyos:implement`](./implement.md) to execute the slices one by one.
Run `/clear` to drop accumulated context, then kick off implementation with the saved tasks file:
```text
/kyos:implement @docs/execution/<spec-slug>/tasks.md
```
This gives the implementation run the full context window and a direct reference to the task list.
## Related section format
See [`/kyos:spec`](./spec.md#related-section-format) for the canonical **Related** section shape. Follow the same format: a `## Related` block at the bottom with markdown links to sibling artefacts that exist. When updating a sibling, insert only the missing link — do not duplicate.
## Where to save the result

@@ -71,0 +100,0 @@ 

+10
-2
catalog/claude-base/claude/commands/tech.md

@@ -17,5 +17,5 @@ # /kyos:tech

- the current feature description or spec
- `.claude/commands/project-context.md`
- the existing codebase
- `docs/execution/<spec-slug>/spec.md` — read automatically if it exists (derive the slug from the argument, or scan `docs/execution/` and use the most recently modified folder)

@@ -49,3 +49,3 @@ ## Workflow

1. Load the feature context and inspect relevant code.
1. Locate the execution folder: if a slug or file path is provided as an argument, derive it from there; otherwise glob `docs/execution/*/` and pick the most recently modified folder. Then read `spec.md` from that folder if it exists — treat it as the primary feature context.
2. Draft a specific implementation approach.

@@ -55,7 +55,15 @@ 3. Make assumptions visible and reviewable.

5. Suggest `/kyos:hire` if the design introduces uncovered capabilities.
6. Include a **Related** section in tech.md with a link to `spec.md` (required) and to `tasks.md` if it already exists.
7. After saving tech.md, open `spec.md` in the same execution folder and add or update a link to `tech.md` in its **Related** section (create the section if absent).
## Next in flow
If the context meter is at 50% or more, run `/compact` before continuing — the plan is saved to disk so nothing is lost.
Continue with [`/kyos:tasks`](./tasks.md) to break the plan into ordered execution slices.
## Related section format
See [`/kyos:spec`](./spec.md#related-section-format) for the canonical **Related** section shape. Follow the same format: a `## Related` block at the bottom with markdown links to sibling artefacts that exist. When updating a sibling, insert only the missing link — do not duplicate.
## Where to save the result

@@ -62,0 +70,0 @@ 

+11
-7
catalog/claude-base/claude/commands/verify.md

@@ -18,14 +18,18 @@ # /kyos:verify

- the feature spec
- the technical plan
- the changed code
- local test or check results, when available
- `docs/execution/<spec-slug>/spec.md` — read automatically if it exists
- `docs/execution/<spec-slug>/tech.md` — read automatically if it exists
- `docs/execution/<spec-slug>/tasks.md` — read automatically if it exists
Derive the slug from the argument if provided; otherwise glob `docs/execution/*/` and use the most recently modified folder.
## Verification pass
1. Check whether the delivered behavior matches the promised behavior.
2. Check whether the implementation drifted from the technical approach in a meaningful way.
3. Run or inspect tests and validation steps where possible.
4. Call out missing cases, regressions, or unclear behavior directly.
5. End with a clear status: verified, partially verified, or needs rework.
1. Locate the execution folder (from argument or most recently modified `docs/execution/*/`). Read `spec.md`, `tech.md`, and `tasks.md` from that folder — all that exist. Use them as the baseline to compare against the implementation.
2. Check whether the delivered behavior matches the promised behavior.
3. Check whether the implementation drifted from the technical approach in a meaningful way.
4. Run or inspect tests and validation steps where possible.
5. Call out missing cases, regressions, or unclear behavior directly.
6. End with a clear verdict: verified, partially verified, or needs rework.

@@ -32,0 +36,0 @@ ## Things to avoid

+0
-1
catalog/registry.json

@@ -14,3 +14,2 @@ {

"agents": [
"silent-executor",
"product-manager"

@@ -17,0 +16,0 @@ ]

+1
-1
package.json
{
"name": "kyos-cli",
"version": "0.3.4",
"version": "0.3.5",
"description": "Bootstrap and safely evolve a shared Claude Code repo structure.",

@@ -5,0 +5,0 @@ "author": "Eugene",

+43
-140
README.md

@@ -7,15 +7,6 @@ # 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.
Claude is powerful — but without structure, conversations drift, context gets lost, and results are inconsistent. `kyos-cli` gives you a proven workflow so you don't have to figure that out yourself. One command sets it up in your project; from there, Claude knows how to guide you from idea to working code.
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](https://claude.ai/code) installed
## Quickstart
**bash / zsh:**
```bash

@@ -25,66 +16,57 @@ npx kyos-cli --init

**PowerShell:**
```powershell
npx kyos-cli --init
```
- Sets up everything Claude Code needs in your project — commands, workflow steps, and a base config.
- Safe to run on an existing project: it shows you what it would change before doing anything.
- Run `--apply` to add only what's missing, or `--init --force` to start fresh.
Behavior:
## The workflow
- 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).
Getting great results from Claude on complex tasks takes more than a single prompt — you need structure, clear steps, and a way to keep context across the session. `kyos-cli` gives you all of that out of the box.
## CLI reference
`kyos-cli` installs a structured workflow that breaks the process into clear steps:
| Command | Description |
| Command | What it does |
|---|---|
| `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 |
| `/kyos:spec` | Nail down what you're building before touching any code |
| `/kyos:tech` | Turn the idea into a concrete plan Claude can follow |
| `/kyos:tasks` | Break the plan into small, checkable steps |
| `/kyos:implement` | Execute the steps one by one, with verification at each |
| `/kyos:verify` | Confirm the result actually matches what was planned |
## Workflow commands
Run them in order for any feature or fix:
`kyos-cli` ships workflow prompts under `.claude/commands/` for Claude-side usage as slash-style commands:
```text
/kyos:prevalidate
/kyos:architecture
/kyos:hire
/kyos:spec
/kyos:tech
/kyos:tasks
/kyos:implement
/kyos:verify
/kyos:spec → /kyos:tech → /kyos:tasks → /kyos:implement → /kyos:verify
```
Foundation commands:
Each step saves its output to a file, so you can pause, resume in a new session, or hand off to someone else without losing context.
- `/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`)_
There are also two planning commands for bigger decisions:
Daily delivery commands:
| Command | What it does |
|---|---|
| `/kyos:prevalidate` | Quick safety check before making changes |
| `/kyos:architecture` | Set or revise your project's technical direction |
| `/kyos:hire` | Add support for tools or patterns missing from your stack |
- `/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.
## Tips
Recommended flow:
- **Compact after spec or tech** — if the context meter hits 50%+ after `/kyos:spec` or `/kyos:tech`, run `/compact` before continuing. Everything is saved to disk, so nothing is lost and the next command starts with a clean budget.
- **Clear before implement** — run `/clear` just before `/kyos:implement` to give the implementation run the full context window. Then reference the saved tasks file directly: `/kyos:implement @docs/execution/your-feature/tasks.md`.
- **Pick up where you left off** — if `spec.md`, `tech.md`, or `tasks.md` already exist when you open a new session, pass them in directly: `/kyos:tech @docs/execution/your-feature/spec.md`. Claude will read the file and continue from there.
- **Keep earlier files in sync** — if something changes during `/kyos:tech` or `/kyos:tasks` (scope shifts, new constraints, a better approach), reflect those changes back in the earlier files too. Keeping spec, tech, and tasks aligned means they can later be assembled into accurate feature documentation with minimal effort.
```text
/kyos:spec -> /kyos:tech -> /kyos:tasks -> /kyos:implement -> /kyos:verify
```
## CLI commands
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.
| Command | Description |
|---|---|
| `kyos-cli --init` | Set up or inspect an existing setup (default) |
| `kyos-cli --init --force` | Reset everything to a clean baseline |
| `kyos-cli --apply` | Add only missing files, never overwrites anything |
| `kyos-cli --update` | Pull in the latest managed files without touching your customizations |
| `kyos-cli --add <type> <name>` | Add a skill, agent, or MCP from the catalog |
| `kyos-cli --doctor` | Check that everything is in order |
## Catalog
Add capabilities from the built-in registry with `--add`:
Extend your setup with optional capabilities:

@@ -104,77 +86,8 @@ ```bash

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`.
Each addition creates a file you can fill with project-specific guidance. MCP entries are wired up automatically.
## 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
```text
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:
```text
+ 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):
```bash
npx kyos-cli --apply
```
To reset everything to baseline (destructive):
```bash
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:
The CLI runs in whatever directory you're in, so you can roll it out across projects with a simple loop:
**bash / zsh:**
```bash

@@ -186,20 +99,10 @@ for repo in ./repo-a ./repo-b ./repo-c; do

**PowerShell:**
```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](https://docs.npmjs.com/generating-provenance-statements) 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.
- **No install scripts** — nothing executes automatically at install time.
- **Publish provenance** — every release is cryptographically verifiable via [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
- **Lockfile committed** — dependency versions are pinned and regenerated on every release.
- **Path safety** — all file operations are strictly sandboxed to your project directory.
To report a vulnerability, see [SECURITY.md](./SECURITY.md).
+1
-1
src/core/managed-files.js

@@ -43,3 +43,3 @@ const fs = require("fs");

];
const managedAgents = ["README.md", "security-engineer.md", "silent-executor.md"];
const managedAgents = ["README.md", "security-engineer.md"];
const managedSkills = ["silent-execution/SKILL.md"];

@@ -46,0 +46,0 @@ 

+1
-1
src/core/workflows.js

@@ -320,3 +320,3 @@ const fs = require("fs");

[`${CLAUDE_ROOT}/agents/README.md`]:
"# Local Agents\n\nPut repo-specific agents here. This folder is intentionally yours; kyos will not overwrite local agents.\n\n## Available agents\n\n- `silent-executor.md` — execution-focused Haiku agent with concise outputs.\n- `security-engineer.md` — deep-dive AppSec mindset for threat modeling, code review, and actionable remediations.\n",
"# Local Agents\n\nPut repo-specific agents here. This folder is intentionally yours; kyos will not overwrite local agents.\n\n## Available agents\n\n- `security-engineer.md` — deep-dive AppSec mindset for threat modeling, code review, and actionable remediations.\n",
[`${CLAUDE_ROOT}/agents/security-engineer.md`]:

@@ -323,0 +323,0 @@ "# Security Engineer (Deep Dive)\n\nYou are a pragmatic security engineer. You apply modern best practices, dig deeply into code and system behavior, and communicate clearly about risk and fixes.\n\n## Prevalidation gate (before doing work in a repo)\n\nWhen asked to work in an unfamiliar repo (or before running scripts/tests/tools), **prevalidate first**:\n\n1. Identify risky operations you might be asked to run (install scripts, formatters, “download then execute”, DB migrations).\n2. Scan for obvious red flags (committed secrets, unsafe shelling out, dangerous defaults).\n3. Confirm the safest “next command” to run (smallest, read-only, or dry-run).\n4. Only proceed to implementation after reporting the prevalidation results and any required guardrails.\n\nIf available, use `/kyos:prevalidate` and summarize its output before starting changes.\n\n## How you work\n\n- Prefer evidence over guesses: cite concrete code paths, configs, and behaviors.\n- Think in trust boundaries and data flows: sources → transforms → sinks.\n- Prioritize by impact × likelihood × ease-of-exploitation.\n- Recommend the smallest safe fix first; avoid breaking changes unless required.\n- Be explicit about assumptions and unknowns; ask targeted questions when needed.\n\n## Default workflow\n\n1. Scope & assets: what’s in scope, who are the actors, what data matters.\n2. Threat model: entry points, trust boundaries, high-priv capabilities.\n3. Attack surface review: inputs, authn/authz, session/token handling, data validation.\n4. Findings: impact, exploit scenario, evidence, severity.\n5. Remediation: preferred fix + safe alternatives; note migrations/gotchas.\n6. Verification: tests and manual steps to confirm the fix.\n\n## Common high-signal checks\n\n- Authz: IDOR/BOLA, missing role checks, privilege escalation.\n- Injection: SQL/NoSQL/command/template; unsafe deserialization.\n- Web: XSS, CSRF, open redirect, CORS misconfig.\n- SSRF: URL fetchers, webhooks, “download this URL”.\n- Secrets: hardcoded creds, secrets in logs/URLs, overly broad scopes.\n- DoS: unbounded payloads, expensive regex/queries, missing timeouts/rate limits.\n- Supply chain: “download then execute”, unpinned deps, unsafe CI.\n\n## Output format (use by default)\n\n- Summary: 3–6 bullets with the most important risks and next actions.\n- Findings (repeat per finding):\n - Title\n - Severity (Critical/High/Medium/Low/Info)\n - Impact\n - Exploit scenario / Preconditions\n - Evidence (files/functions/configs; repro steps if safe)\n - Fix (preferred + alternatives)\n - Verification\n\n## Safety\n\nDo not provide instructions intended to facilitate real-world wrongdoing. Use minimal, controlled PoCs and harmless payloads when demonstrating issues.\n",

-12
catalog/claude-base/claude/agents/silent-executor.md
---
model: haiku
skills:
- silent-execution
---
You are an execution-focused agent.
- Prefer direct execution over explanation
- Keep outputs concise
- Delegate complex work to tools/skills when needed