What You Get

Kyro is a sprint harness for AI coding agents. Install once, every agent uses the same source of truth:

• Shared sprint cycle — all agents follow init → plan → execute → review → close (gates enforced in code)
• One scope file — .agents/kyro/scopes/{scope}/sprint.json is the single source of truth
• CLI-owned state — schema and gates run every time; agents can't invent enums or hand-edit
• Team-safe by default — commit project.json + scopes; each dev has personal local.json
• 6 slash commands — /kyro:forge (full cycle), /kyro:status, /kyro:qa, /kyro:idea, /kyro:task-context, /kyro:scope-retire

Why it matters: AI agents forget context, invent process, and edit planning files by hand. Across Claude, Codex, OpenCode, and others you re-explain the same workflow every session. Kyro stops this.

Quick start

Requirements:

• Node.js ≥ 18
• Git
• Claude Code, Codex, OpenCode, or similar agent (must support plugins or skills)

Install for any agent (Codex, OpenCode, CommandCode, etc.)

Use this path to install Kyro for agents other than Claude Code plugin:

cd /path/to/your-project
npx kyro-ai@latest install --init-workspace --yes

This installs:

• Global runtime at ~/.agents/kyro/current/
• Command skills at ~/.agents/skills/kyro-*
• Project state at ./.agents/kyro/

Then invoke Kyro from your agent:

• Codex, Grok, CommandCode: via kyro-* skills (auto-discovered)
• OpenCode: via /kyro/* commands or ~/.config/opencode/skills/kyro-*
• Terminal: kyro forge, kyro status, etc.

Install Claude Code (Plugin)

Step 1: Add the marketplace

/plugin marketplace add SynapSync/kyro-ai

Step 2: Install the plugin

/plugin install kyro-ai

Step 3: Reload plugins

/reload-plugins

Step 4: Start your first sprint

/kyro:forge implement OAuth2 authentication

You'll see the full cycle:

INIT      objective + success criteria
─ gate ─  proceed / adjust / cancel?
PLAN      sprint tasks
─ gate ─  proceed / adjust / cancel?
EXECUTE   evidence via CLI (not hand JSON)
REVIEW    checker verdict via CLI
CLOSE     lossless checkpoint + ledger

state ›  .agents/kyro/scopes/oauth2-auth/sprint.json

That's it! The plugin works standalone. No extra setup needed.

Teams: Initialize shared project state

If your team shares the repo and you want everyone on the same project.json, run once from the project root:

cd /path/to/your-project
npx kyro-ai@latest install --init-workspace --yes

This creates:

• .agents/kyro/project.json — shared, committed (team constitution + scopes registry)
• .agents/kyro/local.json — personal, gitignored (your active scope)

If scopes already exist from teammates, this registers them. Then set your active scope:

kyro scope set-active <scope> --yes

Verify installation

npx kyro-ai@latest doctor

Or if installed globally:

kyro doctor

Installation by host

| Host | How to install | Invocation | | ---- | --------------- | ---------- | | Claude Code ⭐ | Plugin (recommended): /plugin marketplace add SynapSync/kyro-ai → /plugin install kyro-ai → /reload-plugins | /kyro:forge, /kyro:status, /kyro:qa, /kyro:idea, /kyro:task-context, /kyro:scope-retire | | Claude Code (npx) | From project root: npx kyro-ai@latest install --init-workspace --yes | Commands via terminal or ~/.agents/skills/kyro-* | | Codex | From project root: npx kyro-ai@latest install --agent codex --init-workspace --yes | Skills kyro-* (auto-loaded in root AGENTS.md) | | OpenCode | From project root: npx kyro-ai@latest install --agent opencode --init-workspace --yes | Native /kyro/* commands | | Cursor / Others | From project root: npx kyro-ai@latest install --init-workspace --yes | kyro-forge, kyro-status … under ~/.agents/skills/ |

Notes by host: Agent adapters · Codex guide · OpenCode guide

For local development

Clone and build from source:

git clone https://github.com/SynapSync/kyro-ai.git
cd kyro-ai && npm install && npm run build
claude --plugin-dir /path/to/kyro-ai

Typical flows

Use it when you want to...

| Scenario | Command | | -------- | ------- | | Start a new feature sprint | /kyro:forge implement email notifications | | Check progress on current work | /kyro:status | | Get a summary before switching contexts | /kyro:task-context (copy-paste into a fresh session) | | Audit code & architecture independently | /kyro:qa (runs outside the forge cycle) | | Mature a rough idea into a plan | /kyro:idea design a rate-limiting strategy | | Retire an inactive scope | /kyro:scope-retire <scope> (prepare, show plan, require fresh human approval) | | Record evidence on a task | kyro record-evidence <task> --evidence "…" | | Mark a task complete after review | kyro review <task> --verdict pass | | Track technical debt | kyro debt add --title "refactor auth" --tag database | | Wrap up a sprint | kyro close-sprint --outcome success |

Day-to-day workflow

Commands (routers)

Thin routers over scope state — they load only what the current step needs.

| Command / skill | Role | | --------------- | ---- | | /kyro:forge · kyro-forge | Full cycle: analyze → plan → execute → review → close (gates) | | /kyro:status · kyro-status | Progress, roadmap, debt (brief / full / debt) | | /kyro:idea · kyro-idea | Optional pre-scope: mature an idea into an execution-ready brief | | /kyro:qa · kyro-qa | Independent certification audit (not the forge review gate) | | /kyro:task-context · kyro-task-context | Copy-paste prompt to continue in a fresh context | | /kyro:scope-retire · kyro-scope-retire | Two-phase retirement with a state-bound human approval gate |

Tool-owned CLI (required for state changes)

Do not hand-edit .agents/kyro/scopes/*/sprint.json or invent enums. Mutate state with the CLI so schema and gates run every time.

| Verb | Purpose | | ---- | ------- | | … plan --from <file> | Bootstrap scope or materialize the next sprint | | … clarify --from <file> | Record accepted design clarifications without hand-editing scope state | | … record-evidence <task> … | Maker evidence on a task | | … review <task> --verdict pass\|fail … | Checker verdict | | … debt add\|start\|resolve\|… | Formal debt lifecycle | | … rule add --rule "…" --tag process [--global] | Register a scope rule; optionally promote it to every scope | | … close-sprint --outcome … | Lossless close + checkpoint (never null activeSprint by hand) | | … scope retire --kyro-scope <scope> --reason "…" | Read-only retirement plan; apply only with its digest and explicit human --yes | | … context-pack --json | Lean read for routing (prefer over opening full sprint.json) | | … doctor / … doctor --artifacts | Health and artifact shape | | … analyze | Semantic gates before close |

Replace … with your persisted invocation (kyro, or node ~/.agents/kyro/current/dist/cli.js). Full flags: CLI.

Repairing a legacy debt record in a closed scope

A closed scope's checkpoints, snapshots, narratives and ledger commitments are immutable and are never rewritten. A wrong live record is corrected by an append-only, explicitly typed remediation that leaves an immutable record of itself.

Kyro 4.43.5 is origin-only. Its single operation, debt.origin.set, repairs origin and nothing else, so it cannot repair a record-level legacy shape: a debt that carries a string origin and legacy-only keys like detail/resolution/addedSprint and missing canonical fields. 4.44.0 and later adds debt.canonicalize (remediation protocol v3), which repairs the whole record at once, emits exactly the seven canonical keys id, title, origin, priority, status, targetSprint, note, and names the legacy keys it retires. The current release, 4.47.2, carries that operation unchanged.

Nothing is migrated for you. Installing a newer Kyro never rewrites an existing scope, and Doctor never repairs one on your behalf. The supported path is doctor → canonicalize-prepare → explicit values → canonicalize-preview → apply --yes → doctor → recertify, where preparation and preview write nothing and Kyro refuses to guess priority or targetSprint for you — a suggestion is never an authorization.

Kyro Lens verifies the result read-only: it recomputes the commitments and the replay itself rather than trusting Kyro's label, and never repairs anything.

Full workflow, expected failure boundaries and the certification evidence table: CLI and Release checklist.

How routing works

read project state (project.json + local.json) + scopes/{scope}/sprint.json (prefer context-pack)
  → route on handoff.nextAction
    (init → clarify → plan_sprint → execute_task → review_task → close_sprint → done | recover)
  → load only that mode/helper
  → one tool-owned write

Unknowns become [NEEDS CLARIFICATION] markers; doctor / analyze fail until they are resolved.

What lives where

Global runtime (machine-local, replaced on install/sync):

~/.agents/kyro/current/     # commands, skills core, dist/cli.js, manifest.json
~/.agents/skills/kyro-*/    # command skill stubs (standard)

Project (layered state — team-safe by default):

.agents/kyro/
├── project.json              # SHARED — commit: principles, global conventions, team policy, scopes cache
├── local.json                # LOCAL — gitignored: activeScope, installedAdapters
├── .gitignore                # written by install/sync (local.json, locks)
└── scopes/{scope}/           # SHARED — commit sprint artifacts
    ├── sprint.json           # single source of truth for the scope
    ├── archive/              # write-only at close
    └── findings/             # write-only INIT evidence

| Path | Commit? | Holds | | ---- | ------- | ----- | | project.json | Yes | Team constitution (principles), global conventions, optional team.minPackageVersion, scopes registry cache | | local.json | No (gitignored) | Personal activeScope, machine installedAdapters | | scopes/** | Yes | Sprint work shared by the team |

CLI invocation is global (~/.agents/kyro/current/manifest.json), never stored on project files.

Also includes (power users): behavioral evals, MCP (kyro mcp serve), append-only trace, portable guardrails — see docs map below. Full multi-dev contract: Teams.

Upgrade, teams, multi-dev

# From the project root — refresh runtime + projected skills after a Kyro release
cd /path/to/your-app
npx kyro-ai@latest sync --scope workspace --yes

| Pattern | Guidance | | ------- | -------- | | Working directory | Always install/sync from the project root. Global runtime is shared; .agents/kyro/ is per-cwd. | | Upgrade | Always npx kyro-ai@latest sync (or re-install) from that root so you get the newest package and refresh the global runtime / projected modes. kyroInvocation lives in ~/.agents/kyro/current/manifest.json (one refresh serves all projects). | | Team commit matrix | Commit project.json + scopes/**. Do not commit local.json (personal activeScope). Install writes .agents/kyro/.gitignore for local-only files — you no longer need to gitignore the entire .agents/kyro/ tree. | | Clone bootstrap | From the clone root: install --init-workspace --yes writes layers if missing, rehydrates on-disk scopes into the shared registry, and leaves activeScope unset when multiple scopes exist. Then: … scope set-active <scope> --yes. | | Read-only commands | status / doctor / context-pack never create project state files; they surface an install bootstrap remedy when layers are missing. | | Global bin (optional) | npm i -g kyro-ai@latest for a durable kyro on PATH; still prefer @latest on every upgrade. |

Details: Teams multi-dev contract · CLI project state.

FAQ

Do agents need to install separately, or does the plugin work for everyone?

The plugin is global (installed once per machine). If you're solo, you're done after /plugin install kyro-ai. If your team shares a repo, also run npx kyro-ai@latest install --init-workspace --yes from the project root once — it writes .agents/kyro/project.json (committed) and local.json per dev (gitignored).

How do I upgrade to the latest version?

From the project root:

npx kyro-ai@latest sync --scope workspace --yes

Or if installed globally:

npm i -g kyro-ai@latest
kyro sync --scope workspace --yes

Can agents hand-edit sprint.json?

No. Kyro enforces schema and gates through CLI verbs, not prompt discipline. Use kyro plan --from <file>, kyro clarify --from <file>, kyro record-evidence, kyro review, and kyro close-sprint instead of hand-edits.

My team has scopes already. How do I join?

cd /path/to/your-project
npx kyro-ai@latest install --init-workspace --yes

Kyro registers existing scopes into project.json and creates your personal local.json. Then set your active scope:

kyro scope set-active <scope> --yes

What if .kyro ends up in the wrong directory?

Remove it and reinstall from the correct project root:

rm -rf ./.agents/kyro
cd /path/to/actual/project
npx kyro-ai@latest install --init-workspace --yes

What's the difference between /plugin install kyro-ai and npx kyro-ai@latest install?

• /plugin install kyro-ai — installs the Claude Code plugin (global, one-time)
• npx kyro-ai@latest install — initializes shared project state (.agents/kyro/). Only needed if your team shares the repo. Solo devs don't need to run this.

Documentation

Start here

| Guide | When | | ----- | ---- | | Getting started | First install and first scope | | CLI | Install, sync, doctor, tool-owned verbs, invocation | | Teams | Multi-dev commit matrix, clone bootstrap, layered state | | Commands reference | Full /kyro:* semantics | | Agent adapters | Host-specific setup |

Go deeper

| Guide | Topic | | ----- | ----- | | Architecture | Layout and data flow | | Context management | Handoff and continuity | | Maker/checker | Evidence and review contract | | Spec traceability | Requirements → scenarios → tasks | | Sprint-close checkpoints | Lossless close and recovery | | Cost model | Token budgets | | MCP · Trace · Evals · Guardrails | Structured tools, audit, regression, policy | | Programmatic usage | Embedding instructions in custom apps |

Development (contributors)

npm ci
npm run build
npm run check   # typecheck, versions, links, dist freshness, evals, …
npm pack --dry-run

dist/ must stay in sync with src/ (npm run check:dist). Releases: release checklist.

Philosophy

1. Commands over prose — invoke a workflow; don’t re-paste a 2k-line prompt.
2. One source of truth per scope — sprint.json, not chat memory.
3. CLI owns deterministic writes — health can’t depend on prompt discipline.
4. One sprint at a time — adapt from evidence, retro, and debt.