# Getting Started with Kyro

Kyro is a portable sprint workflow kit for AI coding agents (**kyro-ai**, `sprint.json` schema v4). It installs a global runtime and tiny command skills; each project keeps state under `.agents/kyro/`.

> New here? The [README](../README.md) is the client-facing tour. This page is the slightly deeper first-run guide.

## Prerequisites

- Node.js ≥ 18
- Git
- An AI coding agent that can read `~/.agents/skills`, root `AGENTS.md`, slash commands, or markdown instructions

## Install

Run workspace initialization and sync from the project root: project state is relative to the current directory. Machine-only `kyro install --no-init-workspace` can run outside a project and does not create workspace state. Runtime and skills always land under your home directory.

Install the complete npm package globally once. Open a new terminal so its `kyro` command is on PATH; then initialize each project from its root. The projected runtime under `~/.agents/kyro/current/` is for workflow commands and cannot install or sync package assets.

One install for all detected, enabled harnesses:

```bash
npm install -g kyro-ai
cd /path/to/your-app
kyro install --scope workspace --init-workspace --yes
```

`--init-workspace` creates or refreshes **layered** project state in this directory (non-interactive):

- `.agents/kyro/project.json` — shared (safe to commit): principles, global conventions, team policy
- `.agents/kyro/local.json` — personal/machine (gitignored): `activeScope`, optional local execution settings
- `.agents/kyro/.gitignore` — ignores local-only files; never ignores `project.json` or `scopes/`

It reads scopes from valid matching `scopes/<id>/sprint.json` files (common after cloning a team repo that commits scopes + `project.json` while each developer keeps a personal `local.json`).

Install publishes canonical skills and projects detected Claude/OpenCode harnesses automatically; Codex and Pi read the canonical root. No per-harness `--agent` flag is required. Machine choices persist in `~/.agents/kyro/adapters.json` across projects. Existing workspace `installedAdapters` records migrate with integrations preserved and stop being written to `local.json`.

```bash
kyro adapters list
kyro adapters disable claude --dry-run
kyro adapters enable codex --integrations
kyro doctor --adapters
```

Disable is a persistent machine opt-out and preserves canonical skills. Config edits (Codex MCP and workspace `AGENTS.md`, OpenCode agent overlay) require integrations opt-in on new installs. `--agent` explicitly selects/re-enables a detected adapter. Workspace uninstall keeps machine projections and integrations; `kyro uninstall --machine` removes Kyro-owned skills, projections, integration blocks, and the registry. Preview mutations with `--dry-run`.

Claude Code receives native `kyro-*` skills under `~/.claude/skills/` from its CLI adapter. If you have an older Kyro plugin, verify the new skills before disabling or uninstalling the plugin in Claude Code. Kyro never changes those plugin settings automatically; see [Agent adapters](agent-adapters.md#claude).

## What gets installed

Global runtime:

```text
~/.agents/kyro/current/
├── commands/
├── core/
├── skills/
├── dist/                 # projected CLI (dist/cli.js)
├── package.json
├── config.json
└── manifest.json         # includes kyroInvocation
```

Kyro keeps only this active runtime. Reinstalling or upgrading replaces `current/`; old versioned runtime folders are cleaned instead of retained.

Global command skills:

```text
~/.agents/skills/
├── kyro-forge/SKILL.md
├── kyro-status/SKILL.md
├── kyro-task-context/SKILL.md
├── kyro-idea/SKILL.md
├── kyro-qa/SKILL.md
├── kyro-scope-retire/SKILL.md
└── kyro-work/SKILL.md
```

Detected OpenCode receives native commands and skill links under `~/.config/opencode/`; detected Claude receives skill links under `~/.claude/skills/`. Links fall back to version-pinned copies when symlinks are unavailable, or when `KYRO_LINK_MODE=copy` is set. Pi reads the canonical skills and creates no files of its own. Invoke Work as Claude `/kyro-work`, Codex `kyro-work`, OpenCode `/kyro/work`, or Pi `/skill:kyro-work`; see [Agent adapters](agent-adapters.md#invocation-by-harness).

Project state (layered):

```text
.agents/kyro/
├── project.json          # shared — commit
├── local.json            # personal — gitignored
├── .gitignore            # install/sync assist
└── scopes/
```

`kyro install` does not create a scoped `sprint.json`; forge/INIT creates it when a scope is opened for the first time. If `scopes/` already has valid sprint files (for example after cloning a team repo), Kyro reads them directly. With multiple scopes, set yours with:

```bash
node ~/.agents/kyro/current/dist/cli.js scope set-active <scope> --yes
# or: kyro scope set-active <scope> --yes   # when a durable global bin exists
```

Full multi-dev commit matrix: [Teams](teams.md).

### CLI invocation (important)

`npm install -g kyro-ai` provides the durable CLI. `kyro install` records an agent-safe invocation in the global runtime `manifest.json`; on Windows, that invocation uses Node and the projected CLI because a `.cmd` shim cannot be spawned directly by Node. Project state files do not store the CLI string. A one-time install refreshes it for projected agent modes across workspaces.

The old Claude plugin-only path is not part of the current distribution. Use the global npm CLI for new Claude installations and `kyro update` for published upgrades.

Upgrading (from the project root) is one command — it checks the registry for the latest
release, updates the global package when behind, and refreshes the runtime plus the current
workspace from the fresh package, asking first unless `--yes`:

```bash
cd /path/to/your-app
kyro update
```

Useful variants: `kyro update --check` reports the status without changing anything,
`kyro update --dry-run` previews the planned steps, and `kyro update --yes` skips the
confirmation (for scripts). If only a projected runtime exists, migrate with `npm install -g kyro-ai`, open a new terminal, verify `kyro --version`, then run `kyro install --scope workspace --init-workspace --yes` from the project root. For a manual update of an initialized workspace, run `npm install -g kyro-ai` first and then `kyro sync --scope workspace --yes`. Existing scopes remain in place.
Install or sync removes the old shared `project.json.scopes[]` cache without creating a backup. Missing or invalid `sprint.json` files produce warnings at the end instead of blocking the runtime refresh; affected scopes may not appear in `scope list` until their sprint files are repaired or restored. Existing scope files are not changed.

See [CLI · invocation persistence](cli.md#cli-invocation-persistence-kyroinvocation) and
[CLI · update](cli.md#update-kyro-update).

## First run

Use the installed command skill or slash command:

```text
kyro-forge auth-refactor
```

or, in Claude Code after installing its adapter:

```text
/kyro-forge auth-refactor
```

Kyro routes progressively:

1. read layered project state (`.agents/kyro/project.json` + `local.json`)
2. resolve or create scope
3. read the scope's lean pack / `sprint.json` if present
4. route on `sprint.json.handoff.nextAction` and load only the required mode: INIT, clarify, plan, execute, review, close, done, or recover
5. record task evidence and status through **tool-owned CLI verbs** during execution (`record-evidence`, then `review` for the checker verdict — **no hand-editing** of `sprint.json`), then close via `close-sprint`

## Delegated execution (optional)

By default, `/kyro:forge` runs as a **single agent**: the orchestrator implements, records evidence, and reviews. You can opt in to **delegated execution** so a host subagent implements or reviews **one task** while the orchestrator keeps ownership of `sprint.json` through the Kyro CLI.

There is **no** separate slash command or CLI verb such as `kyro delegate`. Activation is configuration plus natural language inside forge.

### Activation

| Layer | How to enable | Effect |
| ----- | ------------- | ------ |
| **L1 (automatic)** | Set `execution.delegationEnabled: true` in `.agents/kyro/local.json` | `context-pack` surfaces `delegationEnabled: true`; execute/review modes load delegate role helpers |
| **L0 (per task)** | Ask in chat during forge (even when L1 is off) | Orchestrator follows the delegation protocol for that task only |

L1 example (personal, gitignored):

```json
{
  "schemaVersion": 4,
  "activeScope": "my-scope",
  "execution": {
    "delegationEnabled": true
  }
}
```

Verify:

```bash
node ~/.agents/kyro/current/dist/cli.js context-pack \
  --kyro-scope my-scope --task T1.1 --json | jq .delegationEnabled
# → true
```

Full field contract: [Teams — Delegation opt-in](teams.md#delegation-opt-in-l1). Protocol detail: [Architecture — Delegated execution](architecture.md#delegated-execution-protocol-opt-in). **Practical walkthrough with flow diagrams:** [Delegation flow](delegation-flow.md).

### How to tell the agent to run task X with a delegate

Entry point is still **`/kyro:forge`** (or `kyro-forge`). Name the scope and task id.

**With L1 enabled** — delegation is automatic during `execute_task`:

```text
/kyro:forge

Continue scope my-scope. Execute task T1.1.
```

**Without L1** — ask explicitly:

```text
/kyro:forge

Scope: my-scope
Execute task T1.1 with a delegate implementer.
Load delegates/implementer.md. You orchestrate record-evidence and review via CLI.
```

**Checker delegate during review:**

```text
/kyro:forge

Review task T1.1 with a fresh checker delegate (delegates/checker.md).
You apply findings through kyro review — the delegate does not touch sprint.json.
```

### What each role does

| Role | Does | Does not |
| ---- | ---- | -------- |
| **Orchestrator** | `context-pack`, brief, spawn delegate, `record-evidence`, `review`, handoff | Delegate all sprint ownership |
| **Implementer delegate** | Product code, scoped validation, status JSON | `record-evidence`, `review`, edit `sprint.json` |
| **Checker delegate** | Independent review, findings JSON | Self-approve; mutate project state |

One task = one implementer delegate. "Run the phase with delegates" means the orchestrator **loops** tasks — no delegate owns a whole phase.

### Typical CLI checks before delegating

```bash
node ~/.agents/kyro/current/dist/cli.js status --kyro-scope my-scope
node ~/.agents/kyro/current/dist/cli.js context-pack \
  --kyro-scope my-scope --task T1.1 --json
```

The task pack (`taskDescription`, `taskFiles`, acceptance criteria, `delegationEnabled`) is the brief source — not the full `sprint.json`.

### Copy-paste orchestrator prompt

```text
/kyro:forge

Scope: my-scope
Runtime: node ~/.agents/kyro/current/dist/cli.js

Execute T1.1 with delegate implementer.
1. context-pack --task T1.1
2. Spawn delegate per delegates/implementer.md (one task, one delegate)
3. Delegate returns status JSON only
4. You: record-evidence T1.1 (no --yes), then review T1.1 --verdict pass|fail --yes
```

CLI reminder: `record-evidence` never takes `--yes`; `review` does. Mixing them is a common orchestrator slip.

If the host cannot spawn subagents, the orchestrator falls back to single-agent execution — forge does not fail.

## Scope output

After INIT, a scope looks like:

```text
.agents/kyro/scopes/{scope}/
├── sprint.json          # single source of truth
├── archive/             # write-only, at sprint close
└── findings/            # write-only INIT analysis evidence
```

`sprint.json` holds the objective, success criteria, roadmap, active sprint, debt, scope conventions, ADRs, and handoff routing. Register a rule with `kyro rule add`; when the user confirms it should apply project-wide, add `--global` so Kyro also persists it in shared `project.json.conventions[]`. `context-pack` merges those global rules into every scope. When the scope is created via `kyro plan` and at least one of git `user.name` or a valid `user.email` is set, it also stores an optional immutable `author` (scope creator; present fields only; never blocks init). `archive/` receives a verbatim snapshot plus a human narrative each time a sprint closes.

## Verify

```bash
node ~/.agents/kyro/current/dist/cli.js doctor
node ~/.agents/kyro/current/dist/cli.js doctor --artifacts
```

Use the **full npm package** (global `kyro` from `npm install -g kyro-ai`) for `install`, `sync`, and `doctor --tokens`. Day-to-day workflow uses installed skills and the projected runtime CLI (including `doctor --artifacts`).

`doctor --tokens` audits realistic Kyro runtime paths and fails forbidden eager helper loading or over-budget paths — run it from the full package.

## Next steps

- [CLI](cli.md)
- [Teams & multi-dev](teams.md) — includes `delegationEnabled` in `local.json`
- [Delegated execution](getting-started.md#delegated-execution-optional) — activate and prompt the orchestrator
- [Agent adapters](agent-adapters.md)
- [Commands reference](commands-reference.md)
- [Architecture](architecture.md)