Assets
This skill uses a modular assets architecture. Detailed workflows, helpers, and templates are in the assets/ directory:
- assets/modes/ — INIT, SPRINT, and STATUS mode workflows
- assets/helpers/ — Analysis guide, debt tracker, sprint generator, re-entry generator
- assets/templates/ — Roadmap, sprint, project README, and re-entry prompt templates
See assets/README.md for full directory documentation.
Purpose
Kyro is an adaptive sprint workflow skill designed for iterative project execution. Unlike rigid planners that pre-generate all sprints upfront, Kyro:
- Analyzes first — deep exploration of the project/issue before committing to a plan
- 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
This skill works for any project type, language, or framework.
Critical Rules
RULE 1 — SPRINT-BY-SPRINT
Sprints are generated ONE AT A TIME. Never pre-generate all sprints. Each sprint is informed by the previous sprint's retro, recommendations, and accumulated debt. This ensures the plan adapts to reality.
RULE 2 — SUGGESTED PHASES, NOT RIGID
The roadmap defines suggested phases per sprint. During execution, emergent phases MUST be added when new findings surface. Phases are guidelines, not constraints.
RULE 3 — RETRO IS FORMAL INPUT
The retrospective and recommendations from Sprint N-1 are formal input for Sprint N. Every recommendation must either become a task in the next sprint or have its deferral justified in the Disposition table.
RULE 4 — DEBT NEVER DISAPPEARS
The Accumulated Technical Debt table is inherited sprint to sprint. An item is only closed when explicitly resolved. Items are never deleted — only their status changes.
RULE 5 — ADAPTIVE
The roadmap is a living document. If execution reveals that a planned sprint no longer makes sense, the roadmap is updated. The plan serves execution, not the reverse.
RULE 6 — LANGUAGE-AGNOSTIC
This skill works for any language, framework, or project type. It does not assume Flutter, React, Dart, or any specific technology. The analysis determines the structure.
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.
Capabilities Matrix
| Capability | INIT | SPRINT | STATUS |
|---|---|---|---|
| Analyze codebase/project | Yes | No | No |
| Create vault structure | Yes | No | No |
| Generate roadmap | Yes | No | No |
| Generate/update re-entry prompts | Yes | Yes | No |
| Generate sprint | No | Yes | No |
| Execute sprint tasks | No | Yes | No |
| Write/modify code | No | Yes | No |
| Read vault/sprints | Yes | Yes | Yes |
| Update accumulated debt | No | Yes | No |
| Report progress | No | No | Yes |
| Run review and debug protocols | No | Yes (review checklist, debug protocol) | No |
| Propose learned rules | No | Yes (via retro) | No |
| Validate tasks with checklist | No | Yes (BLOCKER/WARNING/SUGGESTION) | No |
Configuration Resolution
{output_kyro_dir} is the directory where kyro stores all project documents. Resolve it once at the start of any mode:
- Re-entry prompt — If the user's message contains file paths (e.g.
/Users/.../ROADMAP.md), extract{output_kyro_dir}from those paths. It's already there. - INIT (first time) — Ask the user where to save documents. Store the chosen path in
README.mdandRE-ENTRY-PROMPTS.md. These are the only sources of truth. - SPRINT/STATUS without re-entry prompt — Auto-discover by scanning
.agents/sprint-forge/in{cwd}, or ask the user directly.
No AGENTS.md. No branded blocks. The re-entry prompts and README carry the path across sessions.
Frontmatter Properties
All generated markdown documents include YAML frontmatter following the Obsidian markdown standard. The agents field tracks the AI model or agent that generated or modified the document. Resolve {agent_model} from the model or agent ID powering the current session (e.g., "gpt-5", "codex", "cursor", "opencode"). When modifying an existing document, append the current model or agent to the agents array if not already present.
Mode Detection
| Mode | EN Signals | ES Signals | What It Does |
|---|---|---|---|
| INIT | "analyze", "audit", "start project", "create roadmap" | "analiza", "audita", "inicia proyecto", "crea roadmap" | Analyzes the project, generates findings, creates roadmap, scaffolds vault, generates re-entry prompts |
| SPRINT | "generate sprint", "next sprint", "execute sprint" | "genera sprint", "siguiente sprint", "ejecuta sprint" | Generates the next sprint from roadmap + previous sprint + debt, optionally executes it |
| STATUS | "project status", "progress", "technical debt" | "estado del proyecto", "progreso", "deuda técnica" | Reports completed sprints, accumulated debt, metrics, next sprint preview |
Disambiguation: If the user's intent is unclear, ask:
"Do you want me to analyze the project (INIT), generate/execute the next sprint (SPRINT), or check project status (STATUS)?"
Asset Loading (Mode-Gated)
After detecting the mode, read ONLY the assets listed for that mode. Do NOT read assets for other modes — they waste context tokens.
| 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 |
| 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.
Quick Start
INIT Mode
Use when starting a new project workflow:
Analyze this project and create a roadmap for the refactoring work.
This will: explore the codebase, generate findings, create an adaptive roadmap, scaffold the output directory, and generate re-entry prompts.
Full workflow: See assets/modes/INIT.md
SPRINT Mode
Use when ready to work on the next sprint:
Generate the next sprint.
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.
Full workflow: See assets/modes/SPRINT.md
STATUS Mode
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.
Full workflow: See assets/modes/STATUS.md
Integration with Other Skills
| Skill | Integration |
|---|---|
code-analyzer |
INIT: Can be used as a preliminary step. The code-analyzer reports feed into Kyro findings, providing structured technical input for the roadmap. |
Workflow Components
Kyro v2.0 operates as a workflow with one orchestrator agent, built-in checkpoints, and commands. The SKILL.md remains the core orchestration logic:
Agent
The orchestrator is the single agent, handling all phases through specialized protocols:
| Protocol | Role | When Used |
|---|---|---|
| Analysis protocol | Read-only codebase analysis | INIT mode — deep codebase exploration |
| Review checklist | Task quality validation | SPRINT mode — validates each task before closure |
| Debug protocol | Root cause investigation | SPRINT mode — invoked on task failure |
| Full cycle coordination | Gate management and sprint lifecycle | /kyro-workflow:forge command — coordinates all phases with gates |
Commands
| Command | Maps To |
|---|---|
/kyro-workflow:forge |
Full cycle: INIT → SPRINT → Review → Close with validation gates |
/kyro-workflow:status |
STATUS mode with sprint progress and debt summary |
/kyro-workflow:wrap-up |
End-of-session closure ritual with quality check and context handoff |
Built-In Checkpoints
The orchestrator runs checkpoints at lifecycle moments. Key checkpoints:
- session_start — loads learned rules from
.agents/sprint-forge/rules.md - post_edit_scan — checks for debug artifacts after code edits
- task_complete — runs review checklist
- drift_check — detects possible scope drift when enabled
- rule_check — checks relevant learned rules before task execution
Per-Project Learning
Corrections during sprint execution are captured as persistent rules in .agents/sprint-forge/rules.md. These rules are loaded at session start and applied automatically in future sprints. See the learner helper (assets/helpers/learner.md) for details.
Limitations
- Mode boundary: Each mode has specific capabilities — INIT cannot execute code, SPRINT cannot create roadmaps, STATUS cannot modify files
- One sprint at a time: By design, you cannot generate multiple sprints in advance
- Requires analysis first: SPRINT mode expects INIT to have been run — it needs a roadmap and findings
- Manual execution: Sprint tasks are executed by the agent, not automated CI/CD
- Context window: For projects with many sprints (>5), use separate sessions per sprint. Re-entry prompts ensure continuity.
- No automated validation: Cannot verify that the roadmap matches codebase reality — relies on thorough analysis during INIT
- External blockers: Cannot resolve dependencies on external teams — logs them as blocked tasks and moves on
- Debt resolution: Debt items require explicit action to close — they don't auto-resolve