kyro-ai 3.2.0 → 3.2.2

package/docs/HOW-TO-USE-OPENCODE.md

@@ -1,93 +1,47 @@
 # OpenCode Adapter Guide
 
-This guide describes manual Kyro usage with OpenCode-style agents. Native command or skill registration depends on the host environment; Kyro compatibility comes from referencing portable markdown files.
-
----
+OpenCode should discover Kyro through global command skills. Do not copy Kyro core into each project.
 
 ## Setup
 
 ```bash
-mkdir -p .skills .agents .agents/kyro/scopes
-
-cp -r kyro-ai/skills/sprint-forge .skills/
-cp -r kyro-ai/skills/qa-review .skills/
-cp kyro-ai/agents/orchestrator.md .agents/
+npx kyro-ai install --agent opencode --scope workspace --yes
 ```
 
-Recommended project structure:
+This installs:
 
-```text
-your-project/
-├── .agents/
-│   ├── orchestrator.md
-│   └── core/
-│       └── {scope}/
-├── .skills/
-│   ├── sprint-forge/
-│   └── qa-review/
-└── src/
-```
+- global runtime: `~/.agents/kyro/current/`
+- global command skills: `~/.agents/skills/kyro-*`
+- project state: `.agents/kyro/kyro.json`
 
----
+## Usage
 
-## Onboarding Prompt
+Use the installed command-like skills:
 
-```text
-Use Kyro for this project.
+- `kyro-forge` — route analyze/plan/execute/review/close
+- `kyro-status` — summary-first progress and debt report
+- `kyro-wrap-up` — close session and refresh handoff context
 
-Read:
-@file .agents/orchestrator.md
-@file .skills/sprint-forge/SKILL.md
-@file .skills/qa-review/SKILL.md
+Each skill is intentionally tiny. It loads the command router first, then only the mode/helper/template needed for the current step.
 
-Persist workflow artifacts under .agents/kyro/scopes/{scope}/.
-If slash commands are unavailable, use:
-- forge = analyze/plan/execute/review/close
-- status = read artifacts and report progress/debt
-- wrap-up = close session and update re-entry prompts
-```
+## Artifacts
 
----
-
-## Example Flows
-
-### Sprint Planning
+Save workflow artifacts under:
 
 ```text
-@file .agents/orchestrator.md
-@file .skills/sprint-forge/SKILL.md
-
-Run the forge intent for {scope}.
-Create or update ROADMAP.md, findings, and the next sprint under
-.agents/kyro/scopes/{scope}/.
+.agents/kyro/scopes/{scope}/
+├── state.json
+├── index.json
+├── ROADMAP.md
+├── ROADMAP.summary.json
+└── phases/
+    ├── SPRINT-N-*.md
+    └── SPRINT-N-*.summary.json
 ```
 
-### QA Review
-
-```text
-@file .skills/qa-review/SKILL.md
-@file .agents/kyro/scopes/{scope}/RE-ENTRY-PROMPTS.md
+## Verify
 
-Review the current implementation against the sprint plan.
-Return blockers first, then warnings, then approval status.
-```
-
-### Session Wrap-Up
-
-```text
-@file .agents/orchestrator.md
-@file .skills/sprint-forge/SKILL.md
-
-Run the wrap-up intent for {scope}.
-Update retro notes, debt status, re-entry prompts, and proposed learned rules.
+```bash
+kyro doctor
+kyro doctor --tokens
 ```
-
----
-
-## Limitations
-
-- OpenCode may not register Kyro commands or skills natively.
-- You must ensure generated artifacts are saved under `.agents/kyro/scopes/{scope}/`.
-- Learned rules are markdown-based and must be maintained in `rules.md`.
-
-For the generic adapter contract and Cursor notes, see [Agent Adapters](agent-adapters.md).

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

@@ -1,52 +1,89 @@
 # Kyro CLI
 
-Kyro includes a small CLI for installing workspace harness assets and checking health.
+Kyro includes a small CLI for installing workspace harness assets, projecting command skills, and checking package/workspace health.
 
 ## Commands
 
 ```bash
 kyro                    # Open the interactive TUI
-kyro install            # Install adapter assets, OpenCode workspace by default
+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 Kyro project state
+kyro uninstall          # Remove managed workspace assets, preserving scope artifacts
 ```
 
-`npx kyro-ai` also resolves to the same CLI entrypoint.
+`npx kyro-ai` resolves to the same CLI entrypoint.
 
 ## Install Scope
 
-The default install scope is `workspace`.
+The default install scope is `workspace`, but Kyro now separates global runtime from project state.
 
-Workspace install writes project-local files so the repository carries its Kyro harness configuration:
+Global runtime files are installed once per Kyro version:
 
 ```text
-.agents/
-├── kyro-ai/
-│   ├── sprint-forge/
-│   ├── commands/
-│   ├── skills/
-│   ├── KYRO.md
-│   └── manifest.json
-├── skills/
-│   ├── kyro-forge/SKILL.md
-│   ├── kyro-status/SKILL.md
-│   └── kyro-wrap-up/SKILL.md
-└── core/
-    └── kyro.json
+~/.agents/kyro/
+├── versions/
+│   └── {version}/
+│       ├── core/
+│       ├── commands/
+│       ├── skills/
+│       ├── KYRO.md
+│       └── manifest.json
+└── current -> versions/{version}
 ```
 
-## OpenCode Adapter
+Global command skills are installed for agent discovery:
 
-OpenCode and Codex are the workspace adapters implemented by the CLI:
+```text
+~/.agents/skills/
+├── kyro-forge/SKILL.md
+├── kyro-status/SKILL.md
+└── kyro-wrap-up/SKILL.md
+```
+
+The project keeps only state and artifacts:
+
+```text
+.agents/kyro/
+├── kyro.json
+└── scopes/
+    └── {scope}/
+        ├── state.json
+        ├── index.json
+        ├── ROADMAP.md
+        ├── ROADMAP.summary.json
+        └── phases/
+            ├── SPRINT-N-*.md
+            └── SPRINT-N-*.summary.json
+```
+
+## Adapters
+
+Implemented workspace adapters:
+
+| Adapter | Purpose |
+| --- | --- |
+| `standard` | Base `~/.agents/skills/kyro-*` command skill projection for compatible agents |
+| `opencode` | OpenCode adapter using the same projected Kyro command skills |
+| `codex` | Codex adapter with projected Kyro command skills plus a managed root `AGENTS.md` block |
+
+Default install uses `standard`:
+
+```bash
+kyro install --scope workspace --dry-run
+kyro install --scope workspace --yes
+```
+
+Agent-specific installs:
 
 ```bash
-kyro install --agent opencode --scope workspace --dry-run
 kyro install --agent opencode --scope workspace --yes
 kyro install --agent codex --scope workspace --yes
+kyro install --agent standard,opencode,codex --scope workspace --yes
 ```
 
-The adapters project Kyro workflows into `.agents/skills/` so compatible agents can discover command-like skills without asking the user to invoke Kyro through prose.
+The adapters project Kyro workflows into `~/.agents/skills/` so compatible agents can discover command-like skills without asking the user to invoke Kyro through prose.
 
 Projected skills:
 
@@ -54,17 +91,17 @@ Projected skills:
 - `kyro-status`
 - `kyro-wrap-up`
 
-Each projected skill references the managed Kyro core in `.agents/kyro/internal/` instead of duplicating long workflow instructions.
+Each projected skill references the managed Kyro runtime in `~/.agents/kyro/current/` instead of duplicating long workflow instructions.
 
 ## State Model
 
-`kyro install` creates only global project state:
+`kyro install` creates only root project state:
 
 ```text
-.agents/kyro/scopes/kyro.json
+.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:
 
@@ -74,14 +111,41 @@ Initial state shape:
   "artifactRoot": ".agents/kyro/scopes",
   "scopes": [],
   "activeScope": null,
+  "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
+- startup/status brief paths stay under their estimated token budgets
+
+Warnings mean Kyro still works, but the harness is becoming expensive to load.
+
+## Sync Semantics
+
+`kyro sync` without `--agent` refreshes the adapters already recorded in `.agents/kyro/kyro.json`.
+
+It must not add the default `standard` adapter to an existing workspace unless the user explicitly passes it:
+
+```bash
+kyro sync
+kyro sync --agent standard --dry-run
+kyro sync --agent codex --dry-run
+```
+
 ## Claude Plugin Support
 
-The Claude plugin adapter remains first-class through `.claude-plugin/`. The CLI does not replace it; it complements Kyro's adapter story for agents that need workspace-installed commands, skills, root AGENTS.md managed blocks, and core assets.
+The Claude plugin adapter remains first-class through `.claude-plugin/`. The CLI does not replace it; it complements Kyro's adapter story for agents that need workspace-installed commands, skills, root `AGENTS.md` managed blocks, and core assets.
 
 ## Unsupported Generic Adapter
 
-Kyro does not provide `--agent generic`. Cross-agent instructions belong in the root `AGENTS.md` standard, and adapter installs should target concrete agent capabilities.
+Kyro does not provide `--agent generic`. Cross-agent instructions belong in root `AGENTS.md`, and adapter installs should target concrete agent capabilities.

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