kyro-ai 3.2.0

package/docs/context-management.md

@@ -0,0 +1,92 @@
+# Context Management Guide
+
+How to manage token limits, prevent context overflow, and use compaction strategies effectively with Kyro.
+
+---
+
+## Token Limits
+
+AI models have finite context windows. When your conversation approaches the limit, older messages are compacted (summarized). This can cause loss of nuance.
+
+| Factor | Guideline |
+|--------|-----------|
+| Root agent instructions | < 60 lines — loaded on every message |
+| Total agent instructions | < 150 lines — larger files waste context on every turn |
+| MCP servers | < 10 active MCPs — each adds tool definitions to context |
+| MCP tools total | < 80 tools — tool descriptions consume tokens |
+| Sprint file size | Keep under 500 lines — use separate files for large sprints |
+
+---
+
+## Compaction Strategies
+
+### What is compaction?
+
+When the conversation approaches the context limit, the system compresses older messages into a summary. This preserves the most recent context but may lose details from earlier turns.
+
+### Good compact points
+
+Kyro is designed with natural compact points:
+
+| Point | Why it's safe |
+|-------|---------------|
+| **Between phases** | Phase checkpoint saves all progress to the sprint file |
+| **After INIT analysis** | Findings are written to files — context can be rebuilt from them |
+| **After sprint generation** | Sprint document captures everything needed for execution |
+| **Between sprints** | Re-entry prompts capture full project state |
+
+### Bad compact points
+
+| Point | Why it's risky |
+|-------|----------------|
+| **Mid-task** | Partial work may be lost — the task state is in the agent's memory |
+| **During retro** | Retro insights come from the full execution context |
+| **During debt table update** | Requires knowledge of what was resolved in this sprint |
+
+### Proactive compaction
+
+Set the environment variable to trigger compaction earlier (before the system forces it):
+
+```bash
+export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
+```
+
+This triggers compaction at 50% context usage instead of the default. Useful for long sprints with many phases.
+
+---
+
+## Re-entry Prompts
+
+Re-entry prompts are Kyro's primary defense against context loss. After each sprint execution, re-entry prompts are updated with:
+
+- Current sprint number and status
+- File paths for all project artifacts
+- Pre-written prompts for common actions (generate next sprint, execute, check status)
+
+If compaction happens mid-session, a new agent can use the re-entry prompt to recover full context.
+
+---
+
+## Tips for Large Projects
+
+1. **One sprint per session** — For projects with 5+ sprints, start a new session for each sprint. Re-entry prompts ensure continuity.
+
+2. **Minimize CLAUDE.md** — Move detailed instructions to separate files that are loaded on-demand, not on every message.
+
+3. **Use lighter models for read-only exploration** — The analysis phase reads many files. A lighter model can reduce cost when the task is status, inventory, or summarization. Use the strongest available model for implementation, debugging, and architecture decisions.
+
+4. **Checkpoint aggressively** — Kyro checkpoints after each phase. This means progress survives compaction.
+
+5. **Avoid loading unnecessary skills** — Each loaded skill adds to the context. Only invoke skills when needed.
+
+---
+
+## Pre-Compaction Checkpoint
+
+Before context compaction, save the current sprint state and update re-entry prompts:
+
+- Logs a warning that compaction is about to happen
+- Checks for active sprint and reminds about re-entry prompts
+- Points to the re-entry prompts file path
+
+This gives the agent (and user) a chance to save state before context is compressed.

package/docs/getting-started.md

@@ -0,0 +1,165 @@
+# 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.
+
+---
+
+## 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
+
+### Claude Code Adapter
+
+Use this path when you want Claude Code to register Kyro slash commands, agents, and skills automatically:
+
+```bash
+/plugin install SynapSync/kyro-ai
+```
+
+For local development:
+
+```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
+```
+
+### Generic Agent Setup
+
+Use this path for agents without a verified Kyro-native plugin mechanism:
+
+```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
+```
+
+Then expose these files as project context or rules in your agent:
+
+- `.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
+
+See [agent-adapters.md](agent-adapters.md) for Codex, OpenCode, Cursor, and generic AGENTS guidance.
+
+---
+
+## First Run
+
+If your platform supports Kyro slash commands, start with:
+
+```text
+/kyro:forge analyze the authentication module
+```
+
+If your platform does not support slash commands, invoke the same intent manually:
+
+```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.
+```
+
+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.
+
+To check progress, use `/kyro:status` or ask the agent to run Kyro status mode by reading `.agents/kyro/scopes/{scope}/`.
+
+---
+
+## Output Structure
+
+After running forge in INIT mode, Kyro creates a scope workspace:
+
+```text
+.agents/kyro/scopes/{scope}/
+├── README.md
+├── ROADMAP.md
+├── RE-ENTRY-PROMPTS.md
+├── findings/
+├── phases/
+└── handoffs/
+```
+
+Project rules are stored in:
+
+```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
+
+### 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
+```
+
+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.
+
+---
+
+## 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

package/docs/harness-migration.md

@@ -0,0 +1,95 @@
+# Harness Migration — Multi-Agent Runtime Direction
+
+Kyro is evolving from a markdown-heavy workflow into an installable harness for AI-assisted software delivery. The goal is not to abandon existing adapters. The goal is to make Kyro practical across Claude, Codex, OpenCode, Cursor, and other AGENTS.md-compatible environments with one consistent operating model.
+
+## Current Problem
+
+Kyro currently works best where a host can load its plugin, commands, agents, and skills directly. Outside that environment, teams must manually copy or install pieces of the workflow and ask each agent to interpret large markdown instructions.
+
+That creates predictable issues:
+
+- agents consume too many tokens before doing useful work
+- validation depends too much on prose discipline
+- state is reconstructed from markdown instead of queried from a structured source
+- install/setup differs per agent
+- health checks are not available as a first-class runtime command
+
+Plan A stabilizes the current package first: version checks, link checks, package health checks, and command/orchestrator deduplication. Track B builds the harness runtime on top of that stable base.
+
+## Target Direction
+
+Kyro should become a **multi-agent harness** with:
+
+- a small CLI/runtime that owns deterministic checks and state operations
+- thin adapter prompts for each supported agent
+- markdown artifacts that remain human-readable and git-friendly
+- structured sidecar state for things agents should not parse from prose
+- first-class support for both Claude plugin workflows and non-Claude agents
+
+Claude plugin support remains a supported adapter. It should not be treated as legacy or removed just because Kyro adds a CLI and additional adapters.
+
+## Adapter Model
+
+Kyro should support multiple agent surfaces through adapter-specific packaging:
+
+| Adapter | Expected Role |
+| --- | --- |
+| Claude plugin | First-class native plugin experience with commands, agents, and skills |
+| Codex | Project instructions and CLI-backed workflow commands |
+| OpenCode | Project-local context plus CLI-backed status, checks, and artifacts |
+| Cursor | Project rules plus CLI-backed workflow state |
+
+The stable contract across all adapters is:
+
+1. use Kyro artifact paths consistently
+2. let deterministic code validate package and project health
+3. keep large workflow detail out of always-loaded prompts
+4. preserve markdown as the collaborative human interface
+
+## Runtime Responsibilities
+
+The future runtime should own behavior that is currently too fragile as prose:
+
+- package diagnostics: versions, links, missing assets, invalid manifests
+- project diagnostics: artifact layout, sprint state, debt consistency
+- state queries: current scope, current sprint, next recommended action
+- rendering: structured state to markdown views
+- install scaffolding: agent-specific bootstrap files
+
+The agent should still do the creative and engineering work: analysis, implementation, review, and decision-making. The harness should make that work observable, repeatable, and easier to validate.
+
+## Non-Goals for Plan A
+
+Plan A does not implement the CLI runtime.
+
+Plan A does not replace the Claude plugin.
+
+Plan A does not redesign sprint-forge behavior.
+
+Plan A only prepares the repository so Track B can build the harness from a stable, tested baseline.
+
+## Track B Starting Point
+
+Track B begins with the smallest useful multi-agent installer:
+
+```bash
+kyro
+kyro install --agent opencode --scope workspace
+kyro doctor
+kyro sync
+kyro uninstall
+```
+
+Recommended first implementation order:
+
+1. `kyro install --agent opencode --scope workspace` and `kyro install --agent codex --scope workspace` for native command/skill projection
+2. `kyro doctor` for package/project health checks
+3. `kyro sync` for managed asset refresh
+4. adapter-specific install templates for Claude, Cursor, and additional concrete agent surfaces
+5. structured scoped `state.json` only when a scope is created or opened
+
+This keeps Kyro portable without forcing every agent to load the whole workflow into context.
+
+## Generic Adapter Decision
+
+Kyro intentionally does not ship a `generic` install adapter. The root `AGENTS.md` file is the cross-agent instruction standard; concrete adapters should install concrete command/skill projections for agents that support them.

package/docs/programmatic-usage.md

@@ -0,0 +1,109 @@
+# Programmatic Usage
+
+Kyro can be used with any LLM API by loading its markdown instructions into your application's prompts. This is a programmatic adapter pattern, not a built-in runtime.
+
+---
+
+## Core Pattern
+
+1. Load the relevant Kyro files.
+2. Provide project context and artifact paths.
+3. Ask the model to run a Kyro intent.
+4. Save the generated markdown artifacts back to disk or your storage layer.
+
+```pseudo
+orchestrator = read("agents/orchestrator.md")
+kyro_core = read("skills/sprint-forge/SKILL.md")
+qa_review = read("skills/qa-review/SKILL.md")
+
+system_prompt = join([
+  orchestrator,
+  kyro_core,
+  qa_review
+])
+
+response = llm.generate({
+  model: SELECTED_MODEL,
+  system: system_prompt,
+  input: """
+  Run the forge intent for scope: oauth-implementation.
+  Use artifact root: .agents/kyro/scopes/oauth-implementation/.
+  Current project context:
+  {PROJECT_CONTEXT}
+  """
+})
+
+write_artifacts(response)
+```
+
+---
+
+## Provider-Neutral Review Example
+
+```pseudo
+qa_review = read("skills/qa-review/SKILL.md")
+
+response = llm.generate({
+  model: STRONG_REVIEW_MODEL,
+  system: qa_review,
+  input: """
+  Review this change using the qa-review skill.
+
+  Files:
+  {CHANGED_FILES}
+
+  Diff:
+  {DIFF}
+
+  Return APPROVED, APPROVED WITH NOTES, CHANGES REQUIRED, or REJECTED.
+  """
+})
+```
+
+---
+
+## Provider-Neutral Sprint Example
+
+```pseudo
+orchestrator = read("agents/orchestrator.md")
+kyro_core = read("skills/sprint-forge/SKILL.md")
+
+response = llm.generate({
+  model: STRONG_PLANNING_MODEL,
+  system: join([orchestrator, kyro_core]),
+  input: """
+  Run the status intent for .agents/kyro/scopes/{scope}/.
+  Then generate the next sprint if the roadmap and previous sprint support it.
+  """
+})
+```
+
+---
+
+## Artifact Contract
+
+Your host application is responsible for persistence:
+
+- Write findings to `.agents/kyro/scopes/{scope}/findings/`.
+- Write sprint documents to `.agents/kyro/scopes/{scope}/phases/`.
+- Keep `ROADMAP.md`, `RE-ENTRY-PROMPTS.md`, and `rules.md` in sync.
+- Run verification commands outside the model when possible.
+
+---
+
+## Model Guidance
+
+Kyro does not require a specific provider or model family.
+
+- Use a high-capability model for implementation, debugging, and architecture decisions.
+- Use a faster/lower-cost model for read-only status reports or simple documentation review.
+- Keep model names out of Kyro's sprint-forge artifacts unless you are recording which model modified a document.
+
+---
+
+## Safety Notes
+
+- Treat model output as a patch proposal unless your host application validates and writes files explicitly.
+- Keep secrets out of prompts.
+- Run tests, typechecks, and builds outside the model.
+- Preserve the markdown artifact layout so future agents can resume work.

package/docs/rules-guide.md

@@ -0,0 +1,216 @@
+# Rules Guide -- Per-Project Learning System
+
+Kyro accumulates knowledge across sprints through a persistent rules file at `.agents/kyro/scopes/rules.md`. Rules capture corrections, patterns, and estimation insights so that mistakes made once are never repeated.
+
+---
+
+## How Rules Are Captured
+
+The learning flow moves from correction to persistent rule in four steps:
+
+```
+1. User corrects the agent during a sprint
+       |
+       v
+2. Agent proposes a rule based on the correction
+       |
+       v
+3. User approves (or edits) the proposed rule
+       |
+       v
+4. Rule is appended to .agents/kyro/scopes/rules.md
+```
+
+### Detection
+
+Rules are captured from two sources:
+
+- **Explicit corrections** -- the user tells the agent it did something wrong. These have the highest confidence.
+- **Pattern detection** -- the agent identifies a recurring pattern worth codifying (e.g., "DB migration tasks consistently take 40% longer than estimated"). These are proactive suggestions with lower confidence.
+
+### Proposal Format
+
+When a correction or pattern is detected, the agent proposes a rule:
+
+```
+Detected a pattern worth remembering:
+
+[RULE-XXX] Category: One-line rule
+  Context: Why this rule exists
+  Source: Sprint N, Project: project-name
+
+Save this rule? (yes/no/edit)
+```
+
+The user can:
+- **yes** -- save the rule as proposed
+- **no** -- discard the proposal
+- **edit** -- modify the rule text before saving
+
+### Storage
+
+Approved rules are appended to `.agents/kyro/scopes/rules.md` and logged in the sprint's `LEARNED` section.
+
+---
+
+## Rule Format and Categories
+
+Rules follow a standard format with categories that determine when they are applied.
+
+### Format
+
+Each rule is a single line with structured metadata:
+
+```
+- [RULE-NNN] One-line actionable rule (YYYY-MM-DD, project: project-name)
+```
+
+Components:
+- `RULE-NNN` -- unique sequential identifier
+- Rule text -- specific, actionable instruction
+- Date -- when the rule was learned
+- Project -- where the rule was learned (for traceability)
+
+### Categories
+
+Rules are organized into categories that correspond to different phases of sprint execution:
+
+```markdown
+# Kyro -- Learned Rules
+
+## Estimation
+- [RULE-001] DB migration tasks: add 20% buffer to estimates (2026-02-20, project: nebux-api)
+- [RULE-002] Auth tasks frequently reveal hidden dependencies (2026-02-22, project: nebux-api)
+
+## Quality
+- [RULE-003] Always validate version compatibility before adding dependencies (2026-02-25, project: synap-sync)
+
+## Architecture
+- [RULE-004] Extract shared validation logic before 3rd duplication (2026-03-01, project: skills-registry)
+
+## Testing
+- [RULE-005] E2E tests for auth flows catch integration issues that unit tests miss (2026-03-03, project: nebux-api)
+
+## Process
+- [RULE-006] Run full quality gates before closing sprint, not just per-task (2026-03-05, project: synap-sync)
+```
+
+| Category | Applied During | Examples |
+|----------|---------------|----------|
+| **Estimation** | Sprint generation (Phase 2) | Buffer adjustments, complexity flags |
+| **Quality** | Task execution and review (Phase 3) | Validation steps, dependency checks |
+| **Architecture** | Analysis and planning (Phase 1-2) | Pattern preferences, boundary rules |
+| **Testing** | Task validation (Phase 3) | Test strategy, coverage requirements |
+| **Process** | All phases | Workflow preferences, gate behavior |
+
+---
+
+## How Rules Are Loaded and Applied
+
+### Loading
+
+At the start of every session, the orchestrator startup checkpoint:
+
+1. Reads `.agents/kyro/scopes/rules.md` (path configurable in `config.json`)
+2. Parses all active rules
+3. Makes them available to the orchestrator for the session
+
+Loading is automatic when `config.json` has `rules.auto_load: true` (the default).
+
+### Application
+
+Rules are applied contextually based on their category:
+
+- **Before generating sprint estimates** -- check Estimation rules. If a rule applies (e.g., "DB migration tasks: add 20% buffer"), adjust the estimate and note the adjustment.
+- **Before architecture decisions** -- check Architecture rules. If a rule applies, follow it or explicitly justify deviation.
+- **During task execution** -- check Quality and Testing rules. If a rule is about to be violated, pause and show the rule to the user.
+- **During sprint planning** -- check Process rules.
+
+### Rule Violation Warning
+
+When the agent is about to violate a learned rule, the orchestrator rule checkpoint triggers a warning:
+
+```
+[Kyro] Rule violation detected:
+  [RULE-003] Always validate version compatibility before adding dependencies
+  Source: 2026-02-25, project: synap-sync
+
+The current action appears to skip version validation.
+Proceed anyway? (yes/no)
+```
+
+## Managing Rules
+
+### Deprecating a Rule
+
+When a rule is no longer relevant (technology changed, project context shifted), mark it as deprecated:
+
+```markdown
+## Estimation
+- [RULE-001] DB migration tasks: add 20% buffer to estimates (2026-02-20, project: nebux-api)
+- ~~[RULE-002] Auth tasks frequently reveal hidden dependencies (2026-02-22, project: nebux-api)~~ [DEPRECATED: auth module rewritten in Sprint 5]
+```
+
+Deprecated rules are kept for history but are no longer applied.
+
+### Evolving a Rule
+
+When a rule needs updating based on new experience, create a new rule that references the original:
+
+```markdown
+## Estimation
+- ~~[RULE-001] DB migration tasks: add 20% buffer to estimates~~ [EVOLVED -> RULE-015]
+- [RULE-015] DB migration tasks: add 30% buffer when involving foreign key changes, 20% otherwise (2026-03-08, project: nebux-api, evolved from RULE-001)
+```
+
+### Consolidating Rules
+
+After accumulating many rules, related rules can be consolidated:
+
+```markdown
+## Estimation
+- ~~[RULE-001] DB migration tasks: add 20% buffer~~ [CONSOLIDATED -> RULE-020]
+- ~~[RULE-002] Auth tasks: reveal hidden dependencies~~ [CONSOLIDATED -> RULE-020]
+- [RULE-020] Complex backend tasks (DB migrations, auth, payments): add 20-30% buffer and check for hidden dependencies before estimating (2026-03-08, consolidated from RULE-001, RULE-002)
+```
+
+### Rule Limits
+
+The learner helper enforces a maximum of **50 active rules**. When approaching this limit:
+- Review rules during sprint retros -- rarely-used rules may be candidates for deprecation
+- Consolidate related rules into broader, more useful ones
+- Deprecate rules tied to completed or abandoned projects
+
+---
+
+## Example rules.md File
+
+```markdown
+# Kyro -- Learned Rules
+
+> Accumulated rules from sprint execution for this project.
+> Loaded automatically at session start. Applied contextually by category.
+> Maximum 50 active rules. Deprecate or consolidate when approaching limit.
+
+## Estimation
+- [RULE-001] DB migration tasks: add 20% buffer to estimates (2026-02-20, project: nebux-api)
+- [RULE-002] Auth tasks frequently reveal hidden dependencies -- add 20% buffer (2026-02-22, project: nebux-api)
+- [RULE-008] UI animation tasks take 2x longer when involving cross-platform support (2026-03-05, project: mobile-app)
+
+## Quality
+- [RULE-003] Always validate version compatibility before adding dependencies (2026-02-25, project: synap-sync)
+- [RULE-009] Never use string concatenation for SQL queries -- always parameterized (2026-03-06, project: nebux-api)
+
+## Architecture
+- [RULE-004] Extract shared validation logic before 3rd duplication (2026-03-01, project: skills-registry)
+- [RULE-010] Prefer composition over inheritance for middleware chains (2026-03-06, project: nebux-api)
+
+## Testing
+- [RULE-005] E2E tests for auth flows catch integration issues that unit tests miss (2026-03-03, project: nebux-api)
+- [RULE-011] Always test error paths, not just happy paths (2026-03-07, project: synap-sync)
+
+## Process
+- [RULE-006] Run full quality gates before closing sprint, not just per-task (2026-03-05, project: synap-sync)
+- [RULE-007] Always validate version compatibility before adding new dependencies (2026-03-05, project: synap-sync)
+- ~~[RULE-012] Use npm ci instead of npm install in CI pipelines (2026-03-07, project: nebux-api)~~ [DEPRECATED: migrated to pnpm]
+```