kyro-ai 3.2.0 → 3.2.2

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.0",
+  "version": "3.2.2",
   "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",

package/skills/sprint-forge/SKILL.md

@@ -38,7 +38,7 @@ allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
 
 This skill uses a modular assets architecture. Detailed workflows, helpers, and templates are in the [assets/](assets/) directory:
 
-- **[assets/modes/](assets/modes/)** — INIT, SPRINT, and STATUS mode workflows
+- **[assets/modes/](assets/modes/)** — lightweight routers plus focused INIT, planning, execution, review, close, recover, and STATUS workflows
 - **[assets/helpers/](assets/helpers/)** — Analysis guide, debt tracker, sprint generator, re-entry generator
 - **[assets/templates/](assets/templates/)** — Roadmap, sprint, project README, and re-entry prompt templates
 
@@ -54,7 +54,7 @@ Kyro is an **adaptive sprint workflow** skill designed for iterative project exe
 - **Generates sprints one at a time** — each sprint feeds from the previous one's retro, recommendations, and accumulated debt
 - **Tracks debt formally** — an accumulated debt table that persists across sprints and never loses items
 - **Adapts the roadmap** — the plan evolves based on what execution reveals
-- **Persists context** — re-entry prompts allow a new agent (or new session) to recover full context
+- **Persists context cheaply** — `state.json`, `index.json`, summaries, and re-entry prompts let new agents recover without rereading every Markdown file
 
 This skill works for **any** project type, language, or framework.
 
@@ -88,7 +88,7 @@ This skill works for **any** project type, language, or framework.
 
 > **RULE 7 — CONTEXT PERSISTENCE**
 >
-> After INIT and after each executed sprint, re-entry prompts are updated. These prompts allow any agent in any session to recover full project context and continue seamlessly.
+> After INIT and after each executed sprint, update `state.json`, `index.json`, relevant `*.summary.json`, and re-entry prompts. Agents read structured state before opening long Markdown evidence.
 
 ---
 
@@ -100,6 +100,7 @@ This skill works for **any** project type, language, or framework.
 | Create vault structure | Yes | No | No |
 | Generate roadmap | Yes | No | No |
 | Generate/update re-entry prompts | Yes | Yes | No |
+| Update state/index/summaries | Yes | Yes | Yes |
 | Generate sprint | No | Yes | No |
 | Execute sprint tasks | No | Yes | No |
 | Write/modify code | No | Yes | No |
@@ -120,7 +121,7 @@ This skill works for **any** project type, language, or framework.
 2. **INIT (first time)** — Ask the user where to save documents. Store the chosen path in `README.md` and `RE-ENTRY-PROMPTS.md`. These are the only sources of truth.
 3. **SPRINT/STATUS without re-entry prompt** — Auto-discover by scanning `.agents/kyro/scopes/` in `{cwd}`, or ask the user directly.
 
-No AGENTS.md. No branded blocks. The re-entry prompts and README carry the path across sessions.
+The project state lives in `.agents/kyro/kyro.json`; scoped state lives in `.agents/kyro/scopes/{scope}/state.json` and `index.json`. Re-entry prompts and README remain human handoff aids, not startup requirements.
 
 ### Frontmatter Properties
 
@@ -149,7 +150,7 @@ After detecting the mode, read ONLY the assets listed for that mode. Do NOT read
 | Mode | Read These Assets | Do NOT Read |
 |------|-------------------|-------------|
 | **INIT** | `INIT.md`, `analysis-guide.md`, `reentry-generator.md` | SPRINT.md, STATUS.md, sprint-generator.md, debt-tracker.md |
-| **SPRINT** | `SPRINT.md`, `sprint-generator.md`, `debt-tracker.md`, `reentry-generator.md` | INIT.md, STATUS.md, analysis-guide.md |
+| **SPRINT** | `SPRINT.md`, then exactly one routed mode: `plan-sprint.md`, `execute-task.md`, `review-task.md`, `close-sprint.md`, or `recover.md` | INIT.md, STATUS.md, unrelated modes/helpers/templates |
 | **STATUS** | `STATUS.md`, `debt-tracker.md` | INIT.md, SPRINT.md, analysis-guide.md, sprint-generator.md, reentry-generator.md, all templates |
 
 **On-demand assets**: Templates are loaded as each workflow step references them, not upfront.
@@ -184,9 +185,9 @@ Or to generate and immediately execute:
 Generate and execute the next sprint.
 ```
 
-This will: read the roadmap and previous sprint, build the disposition table, generate phases, and optionally execute task by task.
+This will: read structured state first, route to planning or execution, and load only the mode/helper files needed for the current step.
 
-**Full workflow:** See [assets/modes/SPRINT.md](assets/modes/SPRINT.md)
+**Router:** See [assets/modes/SPRINT.md](assets/modes/SPRINT.md)
 
 ### STATUS Mode
 
@@ -196,7 +197,7 @@ Use to check project progress:
 Show me the project status and technical debt.
 ```
 
-This will: read all sprints, calculate metrics, display progress and accumulated debt.
+This will: read summaries first, calculate metrics, and open Markdown only when summaries are missing or a full report requires evidence.
 
 **Full workflow:** See [assets/modes/STATUS.md](assets/modes/STATUS.md)
 

package/skills/sprint-forge/assets/README.md

@@ -1,31 +1,41 @@
 # Kyro — Assets
 
-This directory contains the modular components of the `kyro-ai` skill.
+Kyro assets are designed for progressive disclosure: load the router first, then only the mode/helper/template needed for the current action.
 
-## Directory Structure
-
-### modes/ (3 files)
+## modes/
 
 | File | Description |
 |------|-------------|
-| [INIT.md](modes/INIT.md) | Analysis, roadmap creation, and vault scaffolding workflow |
-| [SPRINT.md](modes/SPRINT.md) | Sprint generation and execution workflow |
-| [STATUS.md](modes/STATUS.md) | Project progress reporting workflow |
+| [INIT.md](modes/INIT.md) | Analysis, roadmap, scoped state, summaries, and scaffolding |
+| [SPRINT.md](modes/SPRINT.md) | Lightweight sprint router |
+| [plan-sprint.md](modes/plan-sprint.md) | Generate the next sprint |
+| [execute-task.md](modes/execute-task.md) | Execute active sprint tasks |
+| [review-task.md](modes/review-task.md) | Validate task or phase quality |
+| [close-sprint.md](modes/close-sprint.md) | Retro, debt, summaries, and re-entry closeout |
+| [recover.md](modes/recover.md) | Rebuild state/summaries after interruption |
+| [STATUS.md](modes/STATUS.md) | Summary-first progress reporting |
 
-### helpers/ (4 files)
+## helpers/
 
 | File | Description |
 |------|-------------|
-| [analysis-guide.md](helpers/analysis-guide.md) | How to analyze different project types |
-| [debt-tracker.md](helpers/debt-tracker.md) | Rules for the accumulated debt table |
-| [sprint-generator.md](helpers/sprint-generator.md) | Algorithm for generating a sprint from inputs |
-| [reentry-generator.md](helpers/reentry-generator.md) | How to generate and update re-entry prompts |
+| [analysis-guide.md](helpers/analysis-guide.md) | Analysis strategy per work type |
+| [sprint-generator.md](helpers/sprint-generator.md) | Sprint generation algorithm |
+| [debt-tracker.md](helpers/debt-tracker.md) | Accumulated debt rules |
+| [reentry-generator.md](helpers/reentry-generator.md) | Re-entry prompt updates |
+| [reviewer.md](helpers/reviewer.md) | Review classification |
+| [handoff.md](helpers/handoff.md) | Session handoff format |
 
-### templates/ (4 files)
+## templates/
 
 | File | Description |
 |------|-------------|
-| [ROADMAP.md](templates/ROADMAP.md) | Adaptive roadmap template |
-| [SPRINT.md](templates/SPRINT.md) | Sprint document template |
-| [PROJECT-README.md](templates/PROJECT-README.md) | Project working directory README template |
-| [REENTRY-PROMPTS.md](templates/REENTRY-PROMPTS.md) | Re-entry prompts template |
+| [ROADMAP.md](templates/ROADMAP.md) | Human roadmap evidence |
+| [SPRINT.md](templates/SPRINT.md) | Human sprint evidence |
+| [PROJECT-README.md](templates/PROJECT-README.md) | Scope README |
+| [REENTRY-PROMPTS.md](templates/REENTRY-PROMPTS.md) | Human handoff prompts |
+| [state.json](templates/state.json) | Scoped routing state |
+| [index.json](templates/index.json) | Fast agent routing index |
+| [ROADMAP.summary.json](templates/ROADMAP.summary.json) | Roadmap summary cache |
+| [SPRINT.summary.json](templates/SPRINT.summary.json) | Sprint summary cache |
+| [DEBT.summary.json](templates/DEBT.summary.json) | Debt summary cache |

package/skills/sprint-forge/assets/helpers/metrics.md

@@ -66,14 +66,14 @@ Score: 72/100 (Good)
 
 ## Data Sources
 
-- Sprint files: task counts, completion status, retro data
-- Debt tables: accumulated across all sprints
-- Roadmap: planned vs actual sprint scope
+- Sprint summaries first: task counts, completion status, retro highlights
+- Debt summary or latest debt table: accumulated debt state
+- Roadmap summary first, roadmap Markdown when summary is missing
 - Rules file: estimation adjustment rules
 
 ## Calculation
 
-Read all sprint files in `{output_kyro_dir}/phases/` and compute:
+Read `index.json` and available `*.summary.json` files first. Open sprint Markdown only for missing fields, then compute:
 
 1. Count tasks per sprint (total, completed, blocked, skipped, carry-over)
 2. Map debt items to source directories

package/skills/sprint-forge/assets/helpers/reentry-generator.md

@@ -22,10 +22,10 @@ Each re-entry prompt covers a specific scenario:
 
 | # | Scenario | When to Use | Key Context Needed |
 |---|----------|-------------|-------------------|
-| 1 | First Sprint | After INIT, before any sprint | README, ROADMAP, findings |
-| 2 | Sprint N (next) | After completing Sprint N-1 | README, ROADMAP, last sprint (retro + recommendations + debt), next finding |
-| 3 | Execute Sprint | Sprint generated but not executed | README, ROADMAP, current sprint file |
-| 4 | Status | Any time, for progress report | README, ROADMAP, all sprint files |
+| 1 | First Sprint | After INIT, before any sprint | state.json, index.json, roadmap summary, selected findings |
+| 2 | Sprint N (next) | After completing Sprint N-1 | state.json, index.json, last sprint summary, roadmap summary |
+| 3 | Execute Sprint | Sprint generated but not executed | state.json, index.json, current sprint summary |
+| 4 | Status | Any time, for progress report | state.json, index.json, summaries; Markdown only as fallback |
 
 ---