kyro-ai 3.2.0

package/skills/sprint-forge/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: sprint-forge
+description: >
+  Adaptive sprint workflow: deep analysis, evolving roadmap, one-at-a-time sprints,
+  formal debt tracking, and re-entry prompts for context persistence.
+  Trigger: When the user wants to analyze a project, create a roadmap, generate/execute
+  sprints iteratively, or check project status and technical debt.
+license: Apache-2.0
+metadata:
+  author: synapsync
+  version: "2.0"
+  scope: [root]
+  auto_invoke:
+    # English triggers
+    - "Analyze project or codebase"
+    - "Audit code quality or architecture"
+    - "Create a roadmap for a project"
+    - "Generate the next sprint"
+    - "Execute a sprint"
+    - "Check project status or progress"
+    - "Review technical debt"
+    - "Start a new iterative project workflow"
+    # Spanish triggers
+    - "Analiza el proyecto o codebase"
+    - "Audita la calidad o arquitectura del código"
+    - "Crea un roadmap para el proyecto"
+    - "Genera el siguiente sprint"
+    - "Ejecuta el sprint"
+    - "Estado del proyecto o progreso"
+    - "Revisa la deuda técnica"
+    - "Inicia un workflow de proyecto iterativo"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
+---
+
+# Kyro
+
+## Assets
+
+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/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
+
+See [assets/README.md](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:
+
+1. **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.
+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.
+
+### Frontmatter Properties
+
+All generated markdown documents include YAML frontmatter. See the templates at `assets/templates/` for the expected frontmatter structure. 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](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](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](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 operates as a workflow with one orchestrator agent, built-in checkpoints, and commands. The SKILL.md remains the sprint-forge 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:forge command — coordinates all phases with gates |
+
+### Commands
+
+| Command | Maps To |
+|---------|---------|
+| `/kyro:forge` | Full cycle: INIT → SPRINT → Review → Close with validation gates |
+| `/kyro:status` | STATUS mode with sprint progress and debt summary |
+| `/kyro: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/kyro/scopes/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/kyro/scopes/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
+
+1. **Mode boundary**: Each mode has specific capabilities — INIT cannot execute code, SPRINT cannot create roadmaps, STATUS cannot modify files
+2. **One sprint at a time**: By design, you cannot generate multiple sprints in advance
+3. **Requires analysis first**: SPRINT mode expects INIT to have been run — it needs a roadmap and findings
+4. **Manual execution**: Sprint tasks are executed by the agent, not automated CI/CD
+5. **Context window**: For projects with many sprints (>5), use separate sessions per sprint. Re-entry prompts ensure continuity.
+6. **No automated validation**: Cannot verify that the roadmap matches codebase reality — relies on thorough analysis during INIT
+7. **External blockers**: Cannot resolve dependencies on external teams — logs them as blocked tasks and moves on
+8. **Debt resolution**: Debt items require explicit action to close — they don't auto-resolve

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

@@ -0,0 +1,31 @@
+# Kyro — Assets
+
+This directory contains the modular components of the `kyro-ai` skill.
+
+## Directory Structure
+
+### modes/ (3 files)
+
+| 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 |
+
+### helpers/ (4 files)
+
+| 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 |
+
+### templates/ (4 files)
+
+| 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 |

package/skills/sprint-forge/assets/helpers/analysis-guide.md

@@ -0,0 +1,207 @@
+# Analysis Guide
+
+This helper guides the agent through deep analysis for different types of work. The analysis phase is the foundation of the entire sprint workflow — thoroughness here determines the quality of everything that follows.
+
+---
+
+## Core Principle
+
+> **The analysis dictates the structure, not the reverse.**
+>
+> Do NOT start with a fixed list of categories. Explore the project first, then let the findings define the categories. If the project has 3 problem areas, there are 3 finding files. If it has 15, there are 15.
+
+---
+
+## Step 1 — Detect Work Type
+
+Before analyzing, identify what kind of work this is:
+
+| Work Type | Signals | Focus |
+|-----------|---------|-------|
+| **Audit / Refactor** | "analyze", "audit", "refactor", "review" | Comprehensive codebase exploration |
+| **New Feature** | "add", "implement", "create feature" | Current state + gap analysis |
+| **Bugfix** | "fix", "broken", "error", "regression" | Root cause analysis |
+| **New Project** | "start from scratch", "new project", "build" | Scope definition + planning |
+| **Tech Debt** | "clean up", "deprecated", "missing tests" | Debt inventory + prioritization |
+
+---
+
+## Step 2 — Analysis by Work Type
+
+### Audit / Refactor
+
+This is the most comprehensive analysis type. Explore the **entire** codebase systematically.
+
+**Exploration Strategy**:
+1. Start with the project root: directory structure, configuration files, entry points
+2. Read key architectural files: main entry, routing, state management, data layer
+3. Explore each major directory/module
+4. Check test coverage and quality
+5. Review dependencies and their versions
+6. Look for patterns and anti-patterns
+
+**What to look for** (examples — the actual areas emerge from the project):
+- Architecture: layer separation, dependency direction, coupling
+- API surface: public interfaces, consistency, documentation
+- Component quality: reuse, composition, prop drilling, state management
+- Type safety: any usage, missing types, type assertions
+- Error handling: consistency, coverage, user-facing messages
+- Testing: coverage, quality, missing tests, test patterns
+- Documentation: inline docs, README, API docs
+- Dependencies: outdated, unused, security vulnerabilities
+- Performance: obvious bottlenecks, unnecessary re-renders, heavy computations
+- Accessibility: semantic HTML, ARIA, keyboard navigation
+
+**DO NOT** use this list as a checklist. Let the project tell you what matters.
+
+### New Feature
+
+Focus on understanding what exists and what needs to change.
+
+**Exploration Strategy**:
+1. Understand the current architecture relevant to the feature
+2. Identify where the feature will integrate
+3. Map existing patterns the feature should follow
+4. Identify gaps between current state and requirements
+
+**What to document**:
+- Current state of related functionality
+- Integration points (APIs, components, data flows)
+- Patterns to follow (existing conventions)
+- Requirements and acceptance criteria
+- Technical risks and unknowns
+
+### Bugfix
+
+Focus on reproducing, understanding, and scoping the fix.
+
+**Exploration Strategy**:
+1. Reproduce the bug (or understand the reproduction steps)
+2. Trace the code path involved
+3. Identify the root cause
+4. Assess blast radius (what else could be affected)
+
+**What to document**:
+- Bug description and reproduction steps
+- Root cause analysis
+- Affected code paths and files
+- Related code that may have the same pattern (similar bugs)
+- Proposed fix approach
+- Testing strategy
+
+### New Project
+
+Focus on defining what will be built and how.
+
+**Exploration Strategy**:
+1. Understand the requirements / product idea
+2. Research comparable projects or solutions
+3. Define the technical stack
+4. Plan the project structure
+
+**What to document**:
+- Project scope and boundaries
+- Technical stack decisions (with justification)
+- Proposed architecture
+- Key design decisions
+- Risks and unknowns
+- Initial structure / scaffolding plan
+
+### Tech Debt
+
+Focus on inventorying and prioritizing existing debt.
+
+**Exploration Strategy**:
+1. Scan the codebase for debt indicators
+2. Categorize debt by type and location
+3. Assess impact of each debt item
+4. Prioritize by impact vs effort
+
+**What to document**:
+- Debt inventory (categorized)
+- Impact assessment per item
+- Dependency relationships (which debt blocks other work)
+- Prioritized resolution order
+- Quick wins vs long-term refactors
+
+---
+
+## Step 3 — Document Findings
+
+Each finding becomes a separate file. This is important for:
+- **Granularity**: Each area can be addressed independently
+- **Sprint mapping**: Each finding maps to one or more sprints
+- **Progress tracking**: As sprints complete, findings are resolved
+
+### Finding File Format
+
+**Filename**: `NN-descriptive-slug.md` (e.g., `01-architecture-layers.md`, `02-api-inconsistencies.md`)
+
+**Content**:
+
+```
+---
+title: "Finding: {Title}"
+date: "{date}"
+updated: "{date}"
+scope: "{scope}"
+type: "analysis"
+status: "active"
+version: "1.0"
+severity: "{critical | high | medium | low}"
+agents:
+  - "{agent_model}"
+tags:
+  - "{scope}"
+  - "analysis"
+  - "finding"
+changelog:
+  - version: "1.0"
+    date: "{date}"
+    changes: ["Finding documented"]
+related:
+  - "[[ROADMAP]]"
+---
+
+# Finding: {Title}
+
+## Summary
+
+{2-3 sentence summary of the finding}
+
+## Severity / Impact
+
+{critical | high | medium | low} — {Why this level}
+
+## Details
+
+{Detailed description of the finding. Include specific examples from the code.}
+
+## Affected Files
+
+- `path/to/file1.dart`
+- `path/to/file2.dart`
+
+## Recommendations
+
+1. {Specific, actionable recommendation}
+2. {Another recommendation}
+```
+
+### Numbering
+
+- Use sequential numbering: `01-`, `02-`, `03-`, ...
+- The number determines the default sprint order (finding 01 → Sprint 1)
+- This is a suggestion, not a rule — the roadmap may reorder based on dependencies
+
+---
+
+## Step 4 — Determine Sprint Count
+
+The number of sprints emerges from the number of distinct finding areas:
+
+- **Small project / bugfix**: 1-3 findings → 1-3 sprints
+- **Medium refactor**: 5-8 findings → 5-8 sprints
+- **Major audit**: 10-20 findings → 10-20 sprints
+
+Some findings may be grouped into a single sprint if they are small and related. Some large findings may be split across multiple sprints. The roadmap makes these decisions.

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

@@ -0,0 +1,83 @@
+# Kyro Analyzer — Codebase Analysis Strategies
+
+## Purpose
+
+Provides the orchestrator with structured analysis strategies based on work type classification during the analysis phase. This is the knowledge base that powers INIT mode's deep analysis.
+
+## Work Type Detection
+
+| Type | Signals | Analysis Focus |
+|------|---------|----------------|
+| **Audit/Refactor** | "audit", "refactor", "improve", "clean up" | Architecture, patterns, anti-patterns, debt |
+| **New Feature** | "add", "implement", "build", "create" | Integration points, existing patterns, dependencies |
+| **Bugfix** | "fix", "bug", "broken", "error", "not working" | Error reproduction, related code paths, recent changes |
+| **New Project** | "start", "bootstrap", "scaffold", "new project" | Requirements, tech stack, project structure |
+| **Tech Debt** | "debt", "TODO", "deprecated", "legacy" | Debt inventory, priority, effort estimation |
+
+## Analysis Strategy per Type
+
+### Audit/Refactor
+1. Map project structure (directories, entry points, config files)
+2. Identify architecture pattern (MVC, Clean, Hexagonal, etc.)
+3. Check test coverage and quality
+4. Scan for anti-patterns (god files, circular dependencies, deep nesting)
+5. Review dependency health (outdated, vulnerable, unused)
+6. Identify code duplication hotspots
+
+### New Feature
+1. Understand existing architecture and conventions
+2. Find similar features already implemented (patterns to follow)
+3. Map integration points (where the new feature touches existing code)
+4. Check test patterns for similar features
+5. Identify potential conflicts with in-progress work
+
+### Bugfix
+1. Reproduce or understand the error
+2. Trace the error through the call stack
+3. Check git blame for recent changes to affected files
+4. Search for similar bugs or related issues
+5. Identify the minimal set of files involved
+
+### New Project
+1. Clarify requirements and constraints
+2. Evaluate tech stack choices
+3. Define project structure and conventions
+4. Identify initial dependency set
+5. Plan CI/CD and deployment approach
+
+### Tech Debt
+1. Inventory all TODOs, FIXMEs, HACKs in codebase
+2. Check for deprecated API usage
+3. Identify untested code paths
+4. Map technical debt to business risk
+5. Prioritize by effort vs. impact
+
+## Finding Output Format
+
+Each finding becomes a numbered file in `{output_kyro_dir}/findings/`:
+
+```markdown
+---
+title: "[Finding Title]"
+date: YYYY-MM-DD
+scope: "{scope}"
+type: finding
+status: open
+severity: critical|high|medium|low
+tags: [architecture, security, performance, quality, debt]
+---
+
+# [Finding Title]
+
+## Summary
+[1-2 sentence description]
+
+## Evidence
+[Code snippets, file paths, metrics that support this finding]
+
+## Impact
+[What happens if this is not addressed]
+
+## Recommendation
+[Specific action to take, with estimated effort]
+```