kyro-ai 3.2.0

package/docs/agent-adapters.md

@@ -0,0 +1,152 @@
+# 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.
+
+---
+
+## Stable Interface
+
+Treat these files and directories as Kyro's public 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 |
+
+---
+
+## Generic Setup
+
+Copy or symlink Kyro into the target project:
+
+```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/
+```
+
+Use this onboarding prompt for any agent:
+
+```text
+Use Kyro as the workflow for this project.
+
+Read these files first:
+- .agents/orchestrator.md
+- .skills/sprint-forge/SKILL.md
+- .skills/qa-review/SKILL.md
+
+Persist workflow artifacts under:
+- .agents/kyro/scopes/{scope}/
+
+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
+```
+
+---
+
+## Claude Code Adapter
+
+Claude Code has a native adapter through `.claude-plugin/`.
+
+```bash
+/plugin marketplace add SynapSync/kyro-ai
+/plugin install kyro-ai@kyro-ai
+```
+
+The Claude adapter registers commands, the orchestrator agent, and skills. It is the only native adapter included in this repository today.
+
+---
+
+## Codex Adapter
+
+Codex-style agents should use Kyro as project context:
+
+```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.
+```
+
+---
+
+## Model Guidance
+
+Kyro does not route or enforce model selection.
+
+- 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.
+
+---
+
+## 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.

package/docs/agents-reference.md

@@ -0,0 +1,153 @@
+# Agents Reference
+
+Kyro uses one agent: the **orchestrator**. It coordinates the sprint lifecycle and owns analysis, planning, implementation, review, debugging, and checkpoint behavior.
+
+---
+
+## Overview
+
+| Agent | Role | Model | Tools | Memory |
+|-------|------|-------|-------|--------|
+| **orchestrator** | Full cycle coordination, validation gates, and checkpoints | opus | Read, Glob, Grep, Bash, Edit, Write | project |
+
+---
+
+## Orchestrator
+
+**File:** `agents/orchestrator.md`
+
+The orchestrator coordinates the complete sprint lifecycle. It is the brain of `/kyro:forge`, manages gates, executes protocols, runs checkpoints, and handles sprint close.
+
+### When Triggered
+
+- `/kyro:forge` command.
+- Any workflow task requiring coordinated analysis, planning, implementation, or review.
+
+### Tools
+
+| Tool | Usage |
+|------|-------|
+| Read | Read sprint files, roadmaps, rules, and code paths |
+| Glob | Find project files by pattern |
+| Grep | Search codebase for patterns, debug artifacts, secrets |
+| Bash | Run commands, tests, quality gates, and read-only analysis |
+| Edit | Modify code files during implementation |
+| Write | Create sprint documents, findings, roadmaps, and re-entry prompts |
+
+---
+
+## Protocols
+
+### Analysis Protocol
+
+Used during INIT and codebase exploration. The orchestrator performs read-only analysis:
+
+1. Detect work type: audit/refactor, new feature, bugfix, new project, or tech debt.
+2. Explore architecture, code quality, dependencies, risks, and visible debt.
+3. Generate findings and recommendations for the roadmap.
+
+During analysis, the orchestrator must not edit files.
+
+### Review Checklist
+
+Used after each task completion during sprint execution.
+
+**BLOCKER**
+
+- Related tests pass when the project defines tests.
+- Typecheck/build passes.
+- No debug artifacts are left in production code.
+- No hardcoded secrets or credentials.
+- No syntax errors or broken imports.
+
+**WARNING**
+
+- New code has appropriate coverage when practical.
+- Non-obvious logic is documented.
+- New debt is tracked.
+- No visible performance regressions.
+
+**SUGGESTION**
+
+- Code follows project conventions.
+- Refactoring opportunities are noted for retro.
+- Related documentation updates are identified.
+
+### Debug Protocol
+
+Used when a task fails validation or runtime behavior breaks:
+
+1. Reproduce the failure.
+2. Generate ranked hypotheses.
+3. Investigate evidence.
+4. Identify root cause.
+5. Propose a fix.
+6. Escalate if unresolved after three investigation rounds.
+
+The orchestrator waits for approval before applying non-trivial fixes.
+
+---
+
+## Checkpoint Protocol
+
+The orchestrator owns checkpoints directly. They are not delegated to a separate agent.
+
+| Checkpoint | When | Purpose |
+|------------|------|---------|
+| startup | Start of orchestration | Load rules, detect active sprint, summarize state |
+| pre-phase | Before each phase | Validate rules, sprint file, and worktree state |
+| rule check | Before task execution | Detect likely violations of learned rules |
+| post-edit scan | After edits | Search changed files for debug artifacts and secrets |
+| task complete | After task validation | Verify task status, checkpoint, remaining work, and new debt |
+| pre-commit | Before commit | Run quality gates and final post-edit scan |
+| learn capture | Sprint close | Propose new rules from corrections and discoveries |
+
+---
+
+## Gate Protocol
+
+At each gate, the orchestrator presents:
+
+```text
+===================================
+GATE [N]: [Phase Name] Complete
+===================================
+
+Summary:
+- [key outcomes from this phase]
+
+Next phase: [what happens next]
+
+Options:
+  -> "proceed" -- continue to next phase
+  -> "adjust" -- modify before continuing
+  -> "cancel" -- stop the workflow
+```
+
+The orchestrator never proceeds past a gate without explicit user approval.
+
+---
+
+## Sprint Close Protocol
+
+After all tasks are complete:
+
+1. Run the pre-commit checkpoint.
+2. Consolidate findings.
+3. Fill the retrospective.
+4. Update accumulated technical debt in markdown.
+5. Update frontmatter.
+6. Generate or update re-entry prompts.
+7. Update roadmap if execution changed the plan.
+8. Run the learn-capture checkpoint.
+9. Propose new rules for `.agents/kyro/scopes/rules.md`.
+
+---
+
+## Constraints
+
+- Never skip phases or gates.
+- Never proceed without user approval at gates.
+- If implementation reveals the plan was wrong, return to planning.
+- Capture learnings and propose rules at the end of every cycle.
+- Keep the user informed at each step.

package/docs/architecture.md

@@ -0,0 +1,159 @@
+# Architecture
+
+This document describes Kyro's Command > Agent > Skill workflow architecture and the markdown artifacts used to preserve project context.
+
+---
+
+## Command > Agent > Skill Pattern
+
+Kyro is organized in three layers:
+
+```
+User Command (/kyro:forge, /kyro:status, /kyro:wrap-up)
+  |
+  v
+Agent (orchestrator)
+  |
+  +---> Skill (core)
+  |
+  +---> Skill (qa-review)
+```
+
+### Commands
+
+Commands are the user-facing interface. Each command is defined as a markdown file in `commands/` with frontmatter that specifies its description and argument hints.
+
+| Command | Primary Agent | Purpose |
+|---------|--------------|---------|
+| `/kyro:forge` | orchestrator | Full cycle: Analyze, Plan, Implement, Review, Close |
+| `/kyro:status` | orchestrator | Read-only project progress and debt summary |
+| `/kyro:wrap-up` | orchestrator | End-of-session closure ritual with quality check and context handoff |
+
+### Agent
+
+The orchestrator coordinates the full sprint lifecycle. It performs read-only analysis during discovery, generates plans, executes approved tasks, runs validation, handles debugging, updates sprint artifacts, and owns lifecycle checkpoints.
+
+| Agent | Toolset | Can Write? | Role |
+|-------|---------|-----------|------|
+| orchestrator | Read, Glob, Grep, Bash, Edit, Write | Yes | Full lifecycle coordination |
+
+### Skills
+
+Skills provide domain knowledge that the orchestrator consumes.
+
+| Skill | Knowledge Domain |
+|-------|-----------------|
+| `core` | Core orchestration: modes, helpers, templates, gates, re-entry prompts |
+| `qa-review` | Senior QA audit, architecture validation, security review, sprint alignment |
+
+---
+
+## Data Flow
+
+```
+USER
+  |
+  v
+/kyro:forge
+  |
+  v
+ORCHESTRATOR
+  |-- loads .agents/kyro/scopes/rules.md
+  |-- reads sprint-forge skill assets
+  |-- runs built-in checkpoints
+  |
+  v
+.agents/kyro/scopes/{scope}/
+  |-- findings/
+  |-- phases/
+  |-- ROADMAP.md
+  |-- README.md
+  |-- RE-ENTRY-PROMPTS.md
+```
+
+### Flow for `/kyro:forge`
+
+1. **Rules Loading** - Orchestrator reads `.agents/kyro/scopes/rules.md` if present.
+2. **Analysis** - Orchestrator explores the codebase and creates finding files.
+3. **Gate 1** - User approves analysis.
+4. **Planning** - Orchestrator generates a sprint document with phases and tasks.
+5. **Gate 2** - User approves the plan.
+6. **Implementation** - Orchestrator executes tasks, runs review checks, and checkpoints after each phase.
+7. **Gate 3** - User approves implementation.
+8. **Review and Close** - Orchestrator runs retro, updates debt tables in markdown, proposes rules, and updates re-entry prompts.
+
+---
+
+## 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.
+
+```
+.agents/kyro/scopes/
+├── rules.md
+└── {scope}/
+    ├── README.md
+    ├── ROADMAP.md
+    ├── RE-ENTRY-PROMPTS.md
+    ├── findings/
+    ├── phases/
+    └── handoffs/
+```
+
+`{scope}` is the work topic in kebab-case, for example `oauth-implementation` or `ui-redesign`.
+
+The output directory path (`{output_kyro_dir}`) is resolved once at the start of any mode and embedded in `README.md` and `RE-ENTRY-PROMPTS.md`. These two files are the source of truth for the path.
+
+---
+
+## Built-In Checkpoints
+
+The orchestrator runs checkpoints at lifecycle moments:
+
+| Checkpoint | Purpose |
+|------------|---------|
+| startup | Load rules and detect active sprint state |
+| pre-phase | Validate state before a phase starts |
+| rule check | Verify relevant learned rules |
+| post-edit scan | Detect debug artifacts and likely secrets |
+| task complete | Verify task status and checkpoint state |
+| pre-commit | Run configured quality gates |
+| learn capture | Propose new rules from corrections |
+
+---
+
+## How the Workflow Differs from v1.x
+
+Kyro v2.0 is a full workflow that replaces the v1.x single-skill approach.
+
+```
+v1.x: User message -> sprint-forge skill -> markdown artifacts
+
+v2.0: User command -> orchestrator
+                    -> core / qa-review skills
+                    -> built-in checkpoints
+                    -> markdown artifacts
+```
+
+| Dimension | v1.x | v2.0 |
+|-----------|------|------|
+| Type | Single skill | Full workflow with commands, one agent, skills, and checkpoints |
+| Entry point | Text triggers | Slash commands |
+| Learning | Per-project retro only | Persistent rules in `.agents/kyro/scopes/rules.md` |
+| 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 |
+
+---
+
+## Component Map
+
+| Component | Location |
+|-----------|----------|
+| Commands | `commands/` |
+| Orchestrator | `agents/orchestrator.md` |
+| Sprint workflow skill | `skills/sprint-forge/` |
+| QA review skill | `skills/qa-review/` |
+| Templates | `skills/sprint-forge/assets/templates/` |
+| Rules | `.agents/kyro/scopes/rules.md` in the target project |

package/docs/architecture.mmd

@@ -0,0 +1,21 @@
+flowchart TD
+    USER["User command"]
+    FORGE["/kyro:forge"]
+    STATUS["/kyro:status"]
+    WRAP["/kyro:wrap-up"]
+    ORCH["orchestrator agent"]
+    SPRINT["sprint-forge skill"]
+    QA["qa-review skill"]
+    RULES[".agents/kyro/scopes/rules.md"]
+    SCOPE[".agents/kyro/scopes/{scope}/ markdown artifacts"]
+
+    USER --> FORGE
+    USER --> STATUS
+    USER --> WRAP
+    FORGE --> ORCH
+    WRAP --> ORCH
+    STATUS --> SCOPE
+    ORCH --> SPRINT
+    ORCH --> QA
+    ORCH --> RULES
+    ORCH --> SCOPE

package/docs/cli.md

@@ -0,0 +1,87 @@
+# Kyro CLI
+
+Kyro includes a small CLI for installing workspace harness assets and checking health.
+
+## Commands
+
+```bash
+kyro                    # Open the interactive TUI
+kyro install            # Install adapter assets, OpenCode workspace by default
+kyro doctor             # Read-only package/workspace health check
+kyro sync               # Refresh managed workspace assets
+kyro uninstall          # Remove managed workspace assets, preserving Kyro project state
+```
+
+`npx kyro-ai` also resolves to the same CLI entrypoint.
+
+## Install Scope
+
+The default install scope is `workspace`.
+
+Workspace install writes project-local files so the repository carries its Kyro harness configuration:
+
+```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
+```
+
+## OpenCode Adapter
+
+OpenCode and Codex are the workspace adapters implemented by the CLI:
+
+```bash
+kyro install --agent opencode --scope workspace --dry-run
+kyro install --agent opencode --scope workspace --yes
+kyro install --agent 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.
+
+Projected skills:
+
+- `kyro-forge`
+- `kyro-status`
+- `kyro-wrap-up`
+
+Each projected skill references the managed Kyro core in `.agents/kyro/internal/` instead of duplicating long workflow instructions.
+
+## State Model
+
+`kyro install` creates only global project state:
+
+```text
+.agents/kyro/scopes/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.
+
+Initial state shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "artifactRoot": ".agents/kyro/scopes",
+  "scopes": [],
+  "activeScope": null,
+  "installedAdapters": []
+}
+```
+
+## 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.
+
+## 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.

package/docs/commands-reference.md

@@ -0,0 +1,138 @@
+# Commands Reference
+
+Kyro provides 3 slash commands. Each command maps to one or more agents and skills that handle the actual work.
+
+---
+
+## /kyro:forge
+
+**Full sprint cycle: Analyze, Plan, Implement, Review, Close.**
+
+### Syntax
+
+```
+/kyro:forge <project path or description>
+```
+
+### Arguments
+
+The argument describes what to analyze or work on. It can be a path, a module name, or a description of the work.
+
+### Examples
+
+```
+/kyro:forge analyze the authentication module
+/kyro:forge audit code quality in src/api/
+/kyro:forge refactor the persistence layer
+/kyro:forge add user profile feature
+/kyro:forge fix the login timeout bug
+```
+
+### Phases and Gates
+
+The `/kyro:forge` command runs the complete lifecycle:
+
+```
+[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
+```
+
+### Gate Options
+
+At each gate, the orchestrator presents a summary and waits for your decision:
+
+| Option | Effect |
+|--------|--------|
+| `proceed` | Continue to the next phase |
+| `adjust` | Modify the output before continuing (describe what to change) |
+| `cancel` | Stop the workflow |
+
+### 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
+
+---
+
+## /kyro:status
+
+**Project progress, sprint state, and technical debt summary.**
+
+### Syntax
+
+```
+/kyro:status [brief|full|debt]
+```
+
+### Variants
+
+| Variant | What It Shows |
+|---------|---------------|
+| `brief` | Sprint progress bars and next sprint preview only |
+| `full` | Complete report with all sections (default) |
+| `debt` | Technical debt table and aged debt items |
+
+### Examples
+
+```
+/kyro:status                # Full report
+/kyro:status brief          # Quick progress check
+/kyro:status debt           # Focus on technical debt
+```
+
+### Report Sections
+
+The full report includes:
+
+```
+KYRO -- Project Status
+
+## Sprint Progress
+Sprint 1: xxxxxxxxxx 10/10 (100%)  Complete
+Sprint 2: xxxxxxxx--  8/10 ( 80%)  Complete
+Sprint 3: xxxxxxx--- 7/10 ( 70%)  In Progress
+
+## Technical Debt
+- Open: 4
+- In progress: 1
+- Aged: 2
+- Critical: 1
+
+## Roadmap Health
+- Sprints completed: 2/5
+- Roadmap adaptations: 1
+- Carry-over tasks: 3
+
+## Next Sprint Preview
+Sprint 4: [title]
+- Suggested phases: [count]
+- Carry-over tasks: [count]
+- Critical debt items due: [count]
+```
+
+### 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