Kyro AI

Kyro gives AI coding agents a durable, CLI-governed way to plan, execute, and review software work. Plans and evidence live in the project instead of disappearing with a chat session. Choose the workflow explicitly: Forge for scope-and-sprint delivery, or Work for a task-based plan with its own lifecycle. Neither path is selected by the size or difficulty of the job.

Kyro works through a CLI and host adapters for Claude Code, Codex, OpenCode, and other skill-capable agents. The agent proposes and implements; the CLI validates and writes managed state. A passing task review is an attestation by a checker, not proof that tests ran or a substitute for independent QA.

Version 6.4.0 adds focused validation suggestions and proportional Forge sprint closure. Projects can map changed files to checks, reserve the aggregate suite for an integration boundary, and require it at close for high-impact changes. Work retains its aggregate check before closure. See Validation tiers.

Version 6.4.1 fixes native Windows brief ingestion for work create and work amend-brief, and isolates the integrity-repair tests from developer machine configuration. See the Work guide for the portable source checks and their limits.

Choose a workflow

| | Forge | Work | | --- | --- | --- | | Start with | A scope and sprint plan | A Markdown brief and explicit task plan | | State | .agents/kyro/scopes/<scope>/sprint.json | .agents/kyro/work/<id>/brief.md and work.json | | Flow | Scope → sprint → tasks → reviews → QA-or-close → checkpoint | Brief → tasks → evidence → reviews → close or promote | | Use when | You want sprint checkpoints, scope-level planning, debt, and independent certification | You want a separate, task-driven path with dependencies, amendments, and explicit closure | | Entry point | /kyro:forge or kyro-forge | /kyro:work or kyro-work, selected explicitly |

Work is not restricted to small or quick jobs. A Work can later be promoted into a new Forge scope through an explicit, recoverable CLI transaction. Promotion transfers selected unfinished tasks, not approvals: Forge tasks start pending and follow Forge's own review and QA process. It does not change the active Forge scope. See the Work guide.

Before either path, /kyro:idea can mature an idea into a plan. Idea does not automatically choose or create a Forge scope or Work.

Install and verify

Requires Node.js 18 or newer and Git. From the root of the project where you will use Kyro:

npm install -g kyro-ai
kyro install --init-workspace --yes
kyro --version
kyro doctor --artifacts

Installation projects the runtime and command skills under ~/.agents/, and initializes project-local .agents/kyro/ state. Check kyro capabilities --json before relying on a command such as work: a locally installed older runtime does not gain new verbs merely because this repository was built. kyro update refreshes an installed runtime from a published package; it is not part of developing or testing a release candidate.

One install publishes canonical ~/.agents/skills/kyro-* skills and projects to every detected, enabled harness. Claude and OpenCode use native skill links with a copy fallback; Codex and Pi discover the canonical skills directly. Detection uses the harness binary on PATH or an existing config directory. Use kyro install --no-init-workspace for machine assets alone. --agent is an explicit selection that can re-enable a detected harness, not a required per-harness install step.

kyro adapters list
kyro adapters disable claude       # Persistent machine opt-out; keeps canonical skills
kyro adapters enable claude
kyro adapters enable codex --integrations
kyro doctor --adapters

Config integrations are opt-in: the Codex MCP/root AGENTS.md blocks and OpenCode agent overlay are unchanged on fresh installs without --integrations. Machine choices live in ~/.agents/kyro/adapters.json; install/sync migrates legacy workspace installedAdapters with existing integrations preserved. Sync/update discovers newly added harnesses and respects disabled choices across workspaces. Doctor shows one row per implemented adapter.

Invoke Work as Claude /kyro-work, Codex kyro-work, OpenCode /kyro/work, or Pi /skill:kyro-work. Pi has no files of its own. If you previously installed the Claude Kyro plugin, verify the new skills and then disable or uninstall the plugin in Claude Code; Kyro never changes plugin settings automatically. See agent adapters for discovery, link/copy behavior, invocation names, and migration.

Workspace kyro uninstall preserves machine projections and integrations. kyro uninstall --machine removes Kyro-owned canonical skills, projections, integration blocks, and the registry. Each team member initializes their own clone; local.json remains personal and harness choices are per machine.

First steps

For a Forge scope, ask your agent to run /kyro:forge (or its installed kyro-forge skill) with the outcome you want. Forge asks for approval at planning gates, writes sprint state through the CLI, and routes the next task from a fresh context pack. The typical progression is:

scope initialization → sprint plan → task execution → evidence → review
                     → independent QA or close decision → sprint checkpoint

For Work, write a Markdown brief that states a verifiable outcome, then create the Work explicitly:

kyro work create --id search-refresh --from brief.md --dry-run --json
kyro work create --id search-refresh --from brief.md --json
kyro work status --work search-refresh --json
kyro work context-pack --work search-refresh --json

Create is only the beginning: use kyro work plan to submit the task proposal, then follow the CLI's revision-bound start, evidence, review, amendment, disposition, and closure commands. The CLI writes work.json; agents must not edit it directly. Preview mutating operations with --dry-run where supported. The Work guide has the exact JSON inputs, flags, retry behavior, and promotion contract.

For either workflow, refresh status or context before writing. If a revision is stale, a brief changed outside the CLI, or a transaction is pending, resolve the reported blocker rather than editing managed files by hand. Work task review and Forge independent QA are deliberately different gates.

Commands at a glance

| Agent command / skill | Purpose | | --- | --- | | /kyro:forge · kyro-forge | Plan, execute, review, and close a Forge sprint or complete a finished scope | | /kyro:work · kyro-work | Enter the explicitly selected Work lifecycle | | /kyro:idea · kyro-idea | Mature an idea before choosing a workflow | | /kyro:status · kyro-status | Read Forge progress, roadmap, and debt | | /kyro:task-context · kyro-task-context | Prepare a concise handoff to a fresh session | | /kyro:qa · kyro-qa | Independently audit a Forge scope and implementation | | /kyro:scope-retire · kyro-scope-retire | Retire an obsolete scope through a separate human-gated operation |

These entry points guide an agent; the CLI owns deterministic state changes. For flags and machine-readable output, see the CLI reference and commands reference.

Project state and teams

.agents/kyro/
├── project.json             # shared project policy; commit
├── local.json               # personal active scope; ignore
├── scopes/<scope>/           # shared Forge sprint state and close archives; commit
└── work/<id>/               # shared Work brief, state, and durable history; commit

Kyro's generated .agents/kyro/.gitignore excludes local state, locks, and pending transaction scratch; the Work brief and work.json remain trackable. A clone can read existing scopes from their sprint files. With multiple Forge scopes, select your own active scope using kyro scope set-active <scope> --yes. Work IDs are selected explicitly and do not silently change that Forge setting. See the teams guide.

The global runtime lives at ~/.agents/kyro/current/; it is not a project file. Installing a newer version never silently migrates an existing scope, and doctor diagnoses rather than repairs. Scope state and closed checkpoints must be changed only by supported CLI operations.

Safety and review boundaries

• CLI-owned writes: sprint.json and work.json have validated schemas and transitions. Use the relevant CLI verb instead of hand-editing them.
• Honest evidence: recording a command and a passed result is a maker claim. A checker must inspect the actual work and results; Work reviews are task-level attestations.
• Recovery: interrupted Work brief amendments and promotions use local pending records. Exact retries can finish valid interruptions; conflicting or corrupted state fails closed.
• Forge isolation: ordinary Work operations do not alter Forge state. Only an explicitly confirmed promotion creates a new Forge scope, with its own provenance link and fresh pending tasks.
• Independent certification: /kyro:qa is separate from executor review. Closing a sprint or completing a scope is a distinct, approval-gated action.

Legacy debt remediation

Kyro 4.43.5 is origin-only: debt.origin.set changes origin but cannot repair an entire legacy debt record. Kyro 4.44.0 and later, including 6.2.0 and 6.3.0, supports debt.canonicalize (remediation protocol v3) for a record with missing canonical fields or legacy-only keys. Protocol v5 also records post-close debt transitions so an owner can reconcile debt and complete a scope without changing historical checkpoints. The older resolvedSprint compatibility migration no longer runs during install, sync, or update. Nothing is migrated for you: upgrading never rewrites an existing scope, and closed-scope checkpoints remain immutable.

The explicit path is doctor → prepare → supply values → preview → apply with confirmation → doctor → recertify. Kyro does not guess priority or targetSprint; a suggestion is never an authorization. Kyro Lens verifies the resulting commitments read-only and does not repair them. See the CLI remediation guide and release checklist.

Documentation

| Guide | What it covers | | --- | --- | | Getting started | Initial installation and Forge scope | | Work | Complete Work CLI lifecycle and promotion | | CLI | Tool-owned verbs, invocation, upgrades, and remediation | | Agent adapters | Claude, Codex, OpenCode, and other hosts | | Teams | Shared versus personal state and clone bootstrap | | Architecture | Components, storage, and data flow | | Maker/checker | Evidence and review responsibilities | | Validation tiers | Focused task checks, proportional sprint close, aggregate at integration | | Sprint checkpoints | Lossless Forge closure and recovery | | MCP · Trace · Evals | Structured tools and diagnostics |

Develop Kyro

git clone https://github.com/SynapSync/kyro-ai.git
cd kyro-ai
npm ci
npm run build
npm run check
npm run check:adapters
npm pack --dry-run

The build output must match source (npm run check:dist). Use node dist/cli.js to test a checkout without changing the globally installed runtime. Release metadata in package.json, package-lock.json, and WORKFLOW.yaml must agree. See the release checklist.

Licensed under Apache-2.0. Report an issue.