# 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 every install/sync from the project root** (the repository Kyro should manage). The global runtime and skills always land under your home directory; **project state** (layered files under `.agents/kyro/` and registration of `scopes/`) is written relative to the **current working directory**. If you install from `~` or another folder, you still get the runtime—but Kyro state appears in the wrong place.

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.

Default standard install:

```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`, installed adapters
- `.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`).

Agent-specific installs (still from the project root):

```bash
kyro install --agent opencode --scope workspace --init-workspace --yes
kyro install --agent codex --scope workspace --init-workspace --yes
```

Claude Code can use the first-class plugin independently, without installing the npm CLI (see [README](../README.md#install-claude-code-plugin)). Install the CLI only when you want its projected runtime or shared project state.

## 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
```

OpenCode installs equivalent native entrypoints under `~/.config/opencode/` when you use `--agent opencode`.

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.

Installed as a **Claude Code plugin** instead? Its plugin commands work without the npm CLI or projected runtime; CLI-only operations still require the full npm package.

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.
With Kyro 5, install or sync also removes the old shared `project.json.scopes[]` cache after verifying every old entry against its scope's `sprint.json`. If the cache contains an unresolved entry, migration stops and explains what must be reconciled.

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-style slash command environments:

```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)