kyro-ai 3.2.1 → 3.2.3

package/docs/agent-adapters.md

@@ -1,152 +1,74 @@
 # Agent Adapters
 
-Kyro is an agent-agnostic workflow kit. Native platform behavior depends on whether the host agent supports commands, project rules, skills, or plugin manifests. The portable interface is always the same: markdown instructions plus `.agents/kyro/scopes/{scope}/` artifacts.
+Kyro's adapter contract is: global runtime, global command skills, local project state. Agents should invoke Kyro through command-like skills or slash commands, not by loading the full workflow manually.
 
----
-
-## Stable Interface
-
-Treat these files and directories as Kyro's public interface:
+## Stable interface
 
 | Interface | Purpose |
 |-----------|---------|
-| `agents/orchestrator.md` | Full workflow coordinator instructions |
-| `skills/sprint-forge/SKILL.md` | Sprint planning, execution, status, debt, and re-entry workflow |
-| `skills/qa-review/SKILL.md` | Senior QA, architecture, security, and sprint alignment review |
-| `commands/*.md` | Native slash-command semantics where supported |
-| `.agents/kyro/scopes/{scope}/` | Project roadmap, findings, phases, handoffs, rules, and re-entry prompts |
-
-Platforms without slash commands should invoke these equivalent intents:
-
-| Intent | Equivalent request |
-|--------|--------------------|
-| `forge` | Analyze, plan, execute, review, and close the sprint |
-| `status` | Read artifacts and report project progress/debt |
-| `wrap-up` | Close the session and update re-entry prompts |
+| `~/.agents/kyro/current/commands/*.md` | Thin command routers |
+| `~/.agents/kyro/current/skills/sprint-forge/` | Lazy-loaded workflow modes, helpers, templates |
+| `~/.agents/skills/kyro-*` | Global command skills discovered by compatible agents |
+| `.agents/kyro/kyro.json` | Project-level Kyro state |
+| `.agents/kyro/scopes/{scope}/` | Scope artifacts, state, summaries, roadmap, sprints |
+| root `AGENTS.md` | Small Codex/cross-agent bootstrap when the Codex adapter is installed |
 
----
-
-## Generic Setup
-
-Copy or symlink Kyro into the target project:
+## Install adapters
 
 ```bash
-mkdir -p .skills .agents .agents/kyro/scopes
-
-cp -r /path/to/kyro-ai/skills/sprint-forge .skills/
-cp -r /path/to/kyro-ai/skills/qa-review .skills/
-cp /path/to/kyro-ai/agents/orchestrator.md .agents/
+npx kyro-ai install --scope workspace --yes
+npx kyro-ai install --agent opencode --scope workspace --yes
+npx kyro-ai install --agent codex --scope workspace --yes
 ```
 
-Use this onboarding prompt for any agent:
+Implemented adapters:
 
-```text
-Use Kyro as the workflow for this project.
+| Adapter | Behavior |
+|---------|----------|
+| `standard` | Installs global `kyro-*` command skills for compatible agents. |
+| `opencode` | Uses the same global command skill projection. |
+| `codex` | Adds global command skills plus a small Kyro block in root `AGENTS.md`. |
 
-Read these files first:
-- .agents/orchestrator.md
-- .skills/sprint-forge/SKILL.md
-- .skills/qa-review/SKILL.md
+There is intentionally no generic adapter. Root `AGENTS.md` is the standard cross-agent bootstrap.
 
-Persist workflow artifacts under:
-- .agents/kyro/scopes/{scope}/
+## Command intents
 
-If native slash commands are unavailable:
-- forge = analyze/plan/execute/review/close
-- status = read artifacts and report progress/debt
-- wrap-up = close session and update re-entry prompts
-```
+| Intent | Command skill | Slash namespace |
+|--------|---------------|-----------------|
+| forge | `kyro-forge` | `/kyro:forge` |
+| status | `kyro-status` | `/kyro:status` |
+| wrap-up | `kyro-wrap-up` | `/kyro:wrap-up` |
 
----
+Each skill loads its command router first. The router then names the exact mode/helper/template needed for the current step.
 
-## Claude Code Adapter
+## Codex
 
-Claude Code has a native adapter through `.claude-plugin/`.
+Use:
 
 ```bash
-/plugin marketplace add SynapSync/kyro-ai
-/plugin install kyro-ai@kyro-ai
+npx kyro-ai install --agent codex --scope workspace --yes
 ```
 
-The Claude adapter registers commands, the orchestrator agent, and skills. It is the only native adapter included in this repository today.
+Codex reads the managed root `AGENTS.md` block, discovers `~/.agents/skills/kyro-*`, and follows the router-first workflow.
 
----
+## OpenCode
 
-## Codex Adapter
-
-Codex-style agents should use Kyro as project context:
+Use:
 
 ```bash
-mkdir -p .skills .agents
-cp -r kyro-ai/skills/sprint-forge .skills/
-cp -r kyro-ai/skills/qa-review .skills/
-cp kyro-ai/agents/orchestrator.md .agents/
-```
-
-Prompt:
-
-```text
-Read .agents/orchestrator.md and the Kyro skills in .skills/.
-Use the forge intent for this scope: {scope}.
-Persist outputs under .agents/kyro/scopes/{scope}/.
-```
-
-Native command registration depends on the Codex environment. If slash commands are unavailable, use the manual intent names.
-
----
-
-## OpenCode Adapter
-
-OpenCode usage is manual unless your environment supports project-level rule files.
-
-```bash
-mkdir -p .skills .agents
-cp -r kyro-ai/skills/sprint-forge .skills/
-cp -r kyro-ai/skills/qa-review .skills/
-cp kyro-ai/agents/orchestrator.md .agents/
-```
-
-Reference the files in the AI panel:
-
-```text
-@file .agents/orchestrator.md
-@file .skills/sprint-forge/SKILL.md
-@file .skills/qa-review/SKILL.md
-
-Run the status intent for .agents/kyro/scopes/{scope}/.
-```
-
----
-
-## Cursor Adapter
-
-Cursor can use Kyro through project rules and referenced files.
-
-Recommended setup:
-
-1. Copy the Kyro files using the generic setup.
-2. Add a Cursor project rule that tells the agent to read `.agents/orchestrator.md`.
-3. Ask Cursor to persist sprint artifacts under `.agents/kyro/scopes/{scope}/`.
-
-Cursor prompt:
-
-```text
-Use Kyro for this task. Read .agents/orchestrator.md and the skills under .skills/.
-Run the forge intent for {scope}. Do not create a custom planning format.
+npx kyro-ai install --agent opencode --scope workspace --yes
 ```
 
----
+OpenCode should invoke `kyro-forge`, `kyro-status`, and `kyro-wrap-up` from global skills. It should not copy Kyro core into the project.
 
-## Model Guidance
+## Claude
 
-Kyro does not route or enforce model selection.
+Claude plugin support remains first-class through `.claude-plugin/`. The CLI adapter path complements the plugin; it does not retire it.
 
-- Use the strongest available model for implementation, debugging, and architecture decisions.
-- Lighter/faster models are acceptable for read-only analysis, status reports, and documentation review.
-- When the platform supports model overrides, choose per task rather than encoding model names into Kyro artifacts.
+## Cursor
 
----
+Cursor adapter automation is planned. Until then, use the standard install and root `AGENTS.md`/global skills if your Cursor setup can read them.
 
-## Compatibility Rule
+## Compatibility rule
 
-Do not add platform-specific behavior to the core workflow unless the behavior works through markdown artifacts or is isolated in an adapter-specific directory.
+Keep platform-specific behavior in adapters. The core workflow must remain portable through command routers, scoped state, summaries, and Markdown artifacts.

package/docs/architecture.md

@@ -86,17 +86,22 @@ ORCHESTRATOR
 
 ## Artifact Layout
 
-Kyro stores workflow state in markdown files. This keeps the workflow portable across AI coding platforms, easy to review in git, and usable without a local service.
+Kyro stores durable evidence in markdown and routing state in small JSON files. Agents read JSON first to save context, then open Markdown only when evidence or mutation is required.
 
 ```
 .agents/kyro/scopes/
 ├── rules.md
 └── {scope}/
     ├── README.md
+    ├── state.json
+    ├── index.json
     ├── ROADMAP.md
+    ├── ROADMAP.summary.json
     ├── RE-ENTRY-PROMPTS.md
     ├── findings/
     ├── phases/
+    │   ├── SPRINT-N-*.md
+    │   └── SPRINT-N-*.summary.json
     └── handoffs/
 ```
 
@@ -143,7 +148,7 @@ v2.0: User command -> orchestrator
 | Agent | Skill-only execution | Orchestrator |
 | Quality gates | Basic | Per-task checklist + approval gates |
 | Context transfer | Re-entry prompts | Re-entry prompts + enriched handoffs |
-| State model | Markdown artifacts | Markdown artifacts |
+| State model | Markdown artifacts | Markdown evidence + JSON routing summaries |
 
 ---
 

package/docs/cli.md

@@ -8,6 +8,7 @@ Kyro includes a small CLI for installing workspace harness assets, projecting co
 kyro                    # Open the interactive TUI
 kyro install            # Install standard .agents assets by default
 kyro doctor             # Read-only package/workspace health check
+kyro doctor --tokens    # Audit context/token budgets
 kyro sync               # Refresh managed workspace assets
 kyro uninstall          # Remove managed workspace assets, preserving scope artifacts
 ```
@@ -49,8 +50,12 @@ The project keeps only state and artifacts:
 └── scopes/
     └── {scope}/
         ├── state.json
+        ├── index.json
         ├── ROADMAP.md
+        ├── ROADMAP.summary.json
         └── phases/
+            ├── SPRINT-N-*.md
+            └── SPRINT-N-*.summary.json
 ```
 
 ## Adapters
@@ -96,7 +101,7 @@ Each projected skill references the managed Kyro runtime in `~/.agents/kyro/curr
 .agents/kyro/kyro.json
 ```
 
-It does not create scoped state. Scoped state is created later when a scope is created or opened by a future scope/forge workflow.
+It does not create scoped state. Scoped state, indexes, and summaries are created later when a scope is created or opened by forge/INIT.
 
 Initial state shape:
 
@@ -106,12 +111,30 @@ Initial state shape:
   "artifactRoot": ".agents/kyro/scopes",
   "scopes": [],
   "activeScope": null,
-  "runtimeVersion": "3.2.1",
+  "runtimeVersion": "3.2.2",
   "runtimePath": "~/.agents/kyro/current",
   "installedAdapters": []
 }
 ```
 
+
+## Token Audit
+
+Use `kyro doctor --tokens` to verify progressive-disclosure budgets:
+
+- AGENTS Kyro block <= 150 words
+- projected command skill <= 200 words
+- command router <= 500 words
+- mode file <= 900 words
+- INIT mode <= 500 words
+- each analysis helper <= 450 words
+- ROADMAP template <= 450 words
+- REENTRY template <= 350 words
+- startup, status brief, and INIT happy paths stay under their estimated token budgets
+- `sizingDecision` regression fixture stays internally consistent
+
+Warnings mean Kyro still works, but the harness is becoming expensive to load. Failing sizing checks mean INIT can no longer prove its sprint boundaries.
+
 ## Sync Semantics
 
 `kyro sync` without `--agent` refreshes the adapters already recorded in `.agents/kyro/kyro.json`.

package/docs/commands-reference.md

@@ -1,6 +1,6 @@
 # Commands Reference
 
-Kyro provides 3 slash commands. Each command maps to one or more agents and skills that handle the actual work.
+Kyro provides 3 slash commands. Each command is now a thin router: it reads structured state first, then loads only the mode/helper/template required for the current action.
 
 ---
 
@@ -28,32 +28,20 @@ The argument describes what to analyze or work on. It can be a path, a module na
 /kyro:forge fix the login timeout bug
 ```
 
-### Phases and Gates
+### Routing
 
-The `/kyro:forge` command runs the complete lifecycle:
+`/kyro:forge` starts with `.agents/kyro/kyro.json`, then scoped `state.json` and `index.json` when a scope exists. It routes to exactly one mode:
 
+```text
+no roadmap       -> INIT.md
+no active sprint -> plan-sprint.md
+pending tasks    -> execute-task.md
+validation       -> review-task.md
+closeout         -> close-sprint.md
+inconsistent     -> recover.md
 ```
-[GATE 0: RULES]     Load learned rules from .agents/kyro/scopes/rules.md
-        |
-[PHASE 1: ANALYZE]  Analysis phase investigates codebase (read-only)
-        |
-   GATE 1            User approves analysis and plan direction
-        |
-[PHASE 2: PLAN]     Generate sprint with phases, tasks, and estimates
-        |
-   GATE 2            User approves sprint plan
-        |
-[PHASE 3: IMPLEMENT] Execute task by task
-   |-- After each task: Review step validates (BLOCKER/WARNING/SUGGESTION)
-   |-- On failure:      Debug protocol investigates root cause
-   |-- After each phase: Checkpoint saved to disk
-        |
-   GATE 3            User approves implementation
-        |
-[PHASE 4: REVIEW]   Full sprint review + retrospective
-        |
-[PHASE 5: CLOSE]    Debt update, re-entry prompts, rule proposals
-```
+
+Gates still apply at orchestrator-defined checkpoints, but the command file does not duplicate the full lifecycle.
 
 ### Gate Options
 
@@ -67,10 +55,11 @@ At each gate, the orchestrator presents a summary and waits for your decision:
 
 ### Orchestrator Protocols
 
-- **Analysis protocol** -- Phase 1 (codebase exploration, read-only)
-- **Review checklist** -- Phase 3 (after each task)
-- **Debug protocol** -- Phase 3 (on task failure)
-- **orchestrator** -- coordinates the full cycle
+- **Command router** -- chooses the next mode from structured state
+- **Analysis protocol** -- INIT mode, read-only exploration
+- **Review checklist** -- review-task mode and closeout
+- **Debug protocol** -- execution failure recovery
+- **orchestrator** -- coordinates gates and phase transitions
 
 ---
 
@@ -132,7 +121,8 @@ Sprint 4: [title]
 
 ### Data Sources
 
-The status command reads all files in the output directory:
-- `README.md` for project overview
-- `ROADMAP.md` for planned sprints
-- All `phases/SPRINT-*.md` files for progress, debt, and retro data
+The status command reads summaries first:
+- `.agents/kyro/kyro.json` for project state
+- `{scope}/state.json` and `{scope}/index.json` for routing
+- `ROADMAP.summary.json`, `SPRINT-*.summary.json`, and `DEBT.summary.json` for metrics
+- Markdown files only when summaries are missing or a full report needs evidence

package/docs/getting-started.md

@@ -1,165 +1,115 @@
 # Getting Started with Kyro
 
-Kyro is a portable, markdown-first workflow kit for AI coding agents. It coordinates sprint-based execution through one orchestrator, reusable skills, command intent documents, persistent project rules, and `.agents/kyro/scopes/{scope}/` artifacts.
-
-Kyro does not require a specific model provider. Claude Code is supported through a native adapter, while Codex, OpenCode, Cursor, and generic agents can use the same core files manually.
-
----
+Kyro is a portable sprint workflow kit for AI coding agents. It installs a global runtime and tiny command skills, while each project keeps only state and artifacts under `.agents/kyro/`.
 
 ## Prerequisites
 
-- **Node.js >= 18** -- required to build and package Kyro
-- **Git** -- recommended for project workflows and review
-- **An AI coding agent** -- Claude Code, Codex, OpenCode, Cursor, or another agent that can read markdown instructions
-
-Verify your Node.js version:
-
-```bash
-node --version
-# v18.0.0 or higher
-```
-
----
-
-## Installation Paths
+- Node.js >= 18
+- Git
+- An AI coding agent that can read `~/.agents/skills`, root `AGENTS.md`, slash commands, or markdown instructions
 
-### Claude Code Adapter
+## Install
 
-Use this path when you want Claude Code to register Kyro slash commands, agents, and skills automatically:
+Default standard install:
 
 ```bash
-/plugin install SynapSync/kyro-ai
+npx kyro-ai install --scope workspace --yes
 ```
 
-For local development:
+Agent-specific installs:
 
 ```bash
-git clone https://github.com/SynapSync/kyro-ai.git ~/.claude/plugins/kyro-ai
-cd ~/.claude/plugins/kyro-ai
-npm install
-npm run build
-claude --plugin-dir ~/.claude/plugins/kyro-ai
+npx kyro-ai install --agent opencode --scope workspace --yes
+npx kyro-ai install --agent codex --scope workspace --yes
 ```
 
-### Generic Agent Setup
+Claude plugin support remains first-class through `.claude-plugin/` and Claude's plugin install flow.
 
-Use this path for agents without a verified Kyro-native plugin mechanism:
+## What gets installed
 
-```bash
-git clone https://github.com/SynapSync/kyro-ai.git ~/kyro-ai
-cd your-project
-mkdir -p .agents .skills
-cp -R ~/kyro-ai/agents .agents/kyro
-cp -R ~/kyro-ai/skills/sprint-forge .skills/sprint-forge
-cp -R ~/kyro-ai/skills/qa-review .skills/qa-review
-mkdir -p .agents/kyro/scopes
+Global runtime:
+
+```text
+~/.agents/kyro/current/
+├── commands/
+├── core/
+├── skills/
+└── manifest.json
 ```
 
-Then expose these files as project context or rules in your agent:
+Global command skills:
 
-- `.agents/kyro/orchestrator.md`
-- `.skills/sprint-forge/SKILL.md`
-- `.skills/qa-review/SKILL.md`
-- Kyro command intent files from `commands/*.md`, when your agent supports slash commands or reusable prompts
+```text
+~/.agents/skills/
+├── kyro-forge/SKILL.md
+├── kyro-status/SKILL.md
+└── kyro-wrap-up/SKILL.md
+```
 
-See [agent-adapters.md](agent-adapters.md) for Codex, OpenCode, Cursor, and generic AGENTS guidance.
+Project state:
 
----
+```text
+.agents/kyro/
+├── kyro.json
+└── scopes/
+```
 
-## First Run
+`kyro install` does not create scoped `state.json`; the forge/INIT workflow creates scoped state only when a scope exists.
 
-If your platform supports Kyro slash commands, start with:
+## First run
+
+Use the installed command skill or slash command:
 
 ```text
-/kyro:forge analyze the authentication module
+kyro-forge auth-refactor
 ```
 
-If your platform does not support slash commands, invoke the same intent manually:
+or, in Claude-style slash command environments:
 
 ```text
-Use Kyro forge mode. Read the orchestrator, core, and qa-review instructions. Analyze the authentication module, produce findings, create or update the sprint artifacts under .agents/kyro/scopes/{scope}/, and stop at each approval gate.
+/kyro:forge auth-refactor
 ```
 
-This starts the full sprint cycle:
-
-1. The analysis phase explores the codebase in read-only mode.
-2. You approve the analysis at Gate 1.
-3. Kyro generates a sprint plan with phases and tasks.
-4. You approve the plan at Gate 2.
-5. Tasks are executed one by one and validated.
-6. You approve the implementation at Gate 3.
-7. A retrospective is run and the sprint is closed.
+Kyro routes progressively:
 
-To check progress, use `/kyro:status` or ask the agent to run Kyro status mode by reading `.agents/kyro/scopes/{scope}/`.
+1. read `.agents/kyro/kyro.json`
+2. resolve or create scope
+3. read scoped `state.json` and `index.json` if present
+4. load only the required mode: INIT, plan, execute, review, close, or recover
+5. update Markdown evidence plus JSON summaries
 
----
+## Scope output
 
-## Output Structure
-
-After running forge in INIT mode, Kyro creates a scope workspace:
+After INIT, a scope looks like:
 
 ```text
 .agents/kyro/scopes/{scope}/
 ├── README.md
 ├── ROADMAP.md
+├── ROADMAP.summary.json
 ├── RE-ENTRY-PROMPTS.md
+├── state.json
+├── index.json
 ├── findings/
-├── phases/
-└── handoffs/
+└── phases/
+    ├── SPRINT-N-*.md
+    └── SPRINT-N-*.summary.json
 ```
 
-Project rules are stored in:
+Markdown is the human-readable evidence. JSON files are the fast routing cache used to save tokens.
 
-```text
-.agents/kyro/scopes/rules.md
-```
-
-The artifact files are the compatibility layer. Any agent that can read and write these files can continue the Kyro workflow.
-
----
-
-## Key Concepts
-
-### Modes
-
-| Mode | When to Use | What It Does |
-| --- | --- | --- |
-| INIT | Starting a new project workflow | Analyzes the codebase, generates findings, creates a roadmap, and scaffolds the output directory |
-| SPRINT | Ready to work on the next iteration | Generates a sprint from the roadmap and previous retro, then optionally executes it task by task |
-| STATUS | Checking progress | Reads sprint files and reports progress, debt status, and next sprint context |
-
-### Gates
-
-Gates are mandatory approval checkpoints. Kyro never proceeds past a gate without explicit user approval:
-
-- **Gate 1** -- after analysis, before planning
-- **Gate 2** -- after sprint plan generation, before implementation
-- **Gate 3** -- after implementation, before review and close
+## Verify
 
-### Checkpoints
-
-Sprint files are saved to disk after each phase completes. This keeps progress recoverable across session restarts, context compaction, or switching agents.
-
-### Rules
-
-When you correct an agent during a sprint, the correction can become a persistent project rule:
-
-```text
-User correction -> proposed rule -> user approval -> .agents/kyro/scopes/rules.md
+```bash
+kyro doctor
+kyro doctor --tokens
 ```
 
-Rules are specific, dated, and tied to the project where they were learned. See [rules-guide.md](rules-guide.md).
-
-### Debt Tracking
-
-Technical debt is tracked formally across sprints. Items are never deleted; only their status changes.
-
----
+`doctor --tokens` warns when command routers, projected skills, mode files, or AGENTS.md bootstrap instructions become too heavy.
 
-## Next Steps
+## Next steps
 
-- [Agent Adapters](agent-adapters.md) -- setup guidance for Claude Code, Codex, OpenCode, Cursor, and generic agents
-- [Commands Reference](commands-reference.md) -- syntax and examples for all 3 command intents
-- [Agents Reference](agents-reference.md) -- how the orchestrator and protocols work
-- [Rules Guide](rules-guide.md) -- the per-project learning system
-- [Architecture](architecture.md) -- system design and data flow
+- [CLI](cli.md)
+- [Agent Adapters](agent-adapters.md)
+- [Commands Reference](commands-reference.md)
+- [Architecture](architecture.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kyro-ai",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "description": "Portable sprint workflow kit for AI coding agents, with markdown artifacts, adapter guides, and formal debt tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",