kyro-ai 3.2.0

package/skills/sprint-forge/assets/modes/STATUS.md

@@ -0,0 +1,145 @@
+# STATUS Mode — Project Progress Report
+
+This mode reads all project artifacts and generates a comprehensive progress report.
+
+---
+
+## When This Mode Activates
+
+| EN Signals | ES Signals |
+|-----------|-----------|
+| "project status", "progress", "progress report", "technical debt", "how's the project going" | "estado del proyecto", "progreso", "reporte de progreso", "deuda técnica", "cómo va el proyecto" |
+
+---
+
+## Prerequisites
+
+- INIT mode must have been run (README.md, ROADMAP.md, and at least one finding file exist)
+- At least one sprint should exist for meaningful metrics (but STATUS works even with zero sprints)
+
+---
+
+## Workflow
+
+### Step 0 — Locate Output Directory
+
+Before reading any files, determine `{output_kyro_dir}`:
+
+1. If the user's request includes an explicit path, use it
+2. Otherwise, check `{cwd}/.agents/kyro/scopes/` — if a single project directory exists, use it
+3. If multiple directories exist, ask: "Which project? Found: {list}"
+4. If none found, ask: "Where are your kyro-ai documents? (e.g. `.agents/kyro/scopes/my-project/`)"
+
+### Step 1 — Read Project State
+
+Read the following files:
+
+1. `{output_kyro_dir}/README.md` — Project overview and paths
+2. `{output_kyro_dir}/ROADMAP.md` — Planned sprints, dependencies, execution rules
+3. All sprint files in `{output_kyro_dir}/phases/` — Progress, debt, retros
+
+### Step 2 — Calculate Metrics
+
+From the roadmap and sprint files, compute:
+
+| Metric | How to Calculate |
+|--------|-----------------|
+| **Total Planned Sprints** | Count sprints defined in ROADMAP.md |
+| **Completed Sprints** | Count sprint files with all DoD items checked |
+| **In-Progress Sprints** | Sprint files with some tasks done but DoD incomplete |
+| **Remaining Sprints** | Total - Completed - In-Progress |
+| **Total Tasks** | Sum of all tasks across all generated sprint files |
+| **Completed Tasks** | Sum of `[x]` tasks |
+| **Blocked Tasks** | Sum of `[!]` tasks |
+| **Skipped Tasks** | Sum of `[-]` tasks |
+| **Open Debt Items** | Count debt items with status `open` or `in-progress` in latest sprint |
+| **Resolved Debt Items** | Count debt items with status `resolved` in latest sprint |
+| **Deferred Debt Items** | Count debt items with status `deferred` in latest sprint |
+| **Emergent Phases** | Count of emergent phases added across all sprints |
+
+### Step 3 — Generate Report
+
+Output the report directly to the console (do NOT write to a file):
+
+```
+# {scope} — Status Report
+
+> Generated: {date}
+> Codebase: `{codebase_path}`
+> Working Dir: `{output_kyro_dir}`
+
+---
+
+## Progress Overview
+
+| Metric | Value |
+|--------|-------|
+| Sprints | {completed}/{total} completed ({percentage}%) |
+| Tasks | {done}/{total} completed, {blocked} blocked, {skipped} skipped |
+| Debt | {open} open, {resolved} resolved, {deferred} deferred |
+| Emergent Phases | {count} added during execution |
+
+---
+
+## Sprint Progress
+
+| Sprint | Status | Tasks | Key Deliverables |
+|--------|--------|-------|-----------------|
+| Sprint 1 | completed | 12/12 | Architecture cleanup |
+| Sprint 2 | completed | 10/14 | API surface audit |
+| Sprint 3 | in-progress | 3/8 | Component quality |
+| Sprint 4 | pending | — | Testing infrastructure |
+
+---
+
+## Accumulated Technical Debt
+
+{Copy the debt table from the latest sprint file}
+
+**Debt Trend**: {Is open count growing or shrinking?}
+**Oldest Open Item**: {Item that has been open the longest}
+
+---
+
+## Roadmap Health
+
+- **Adaptations Made**: {Number of times the roadmap was modified}
+- **Original Sprint Count**: {From initial INIT}
+- **Current Sprint Count**: {After adaptations}
+- **Sprints Added**: {count}
+- **Sprints Removed**: {count}
+- **Assessment**: {Is the roadmap still serving the project well?}
+
+---
+
+## Next Sprint Preview
+
+**Sprint {N}**: {title}
+- Focus: {focus}
+- Source: `findings/{finding_file}`
+- Dependencies: {which sprints must complete first}
+- Carry-over: {count} recommendations from Sprint {N-1}
+
+---
+
+## Re-entry Prompt
+
+{The appropriate re-entry prompt for the next action — usually Scenario 2 or 3 from RE-ENTRY-PROMPTS.md}
+```
+
+---
+
+## Edge Cases
+
+| Situation | Handling |
+|-----------|---------|
+| No sprints generated yet | Show INIT results only (findings count, roadmap overview). Suggest generating Sprint 1. |
+| All sprints complete | Show final metrics. Highlight any remaining open debt. Suggest project closure or maintenance phase. |
+| Sprint in progress | Show current sprint progress. Highlight blocked tasks. Suggest resuming execution. |
+| No debt items | Note that no technical debt has been logged. This could mean the project is clean or debt isn't being tracked. |
+
+---
+
+## References
+
+- [debt-tracker.md](../helpers/debt-tracker.md) — Debt table format and reporting rules

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

@@ -0,0 +1,107 @@
+---
+title: "{scope} — Working Project"
+date: "{date}"
+updated: "{date}"
+scope: "{scope}"
+type: "progress"
+status: "active"
+version: "1.0"
+agents:
+  - "{agent_model}"
+tags:
+  - "{scope}"
+  - "progress"
+  - "kyro-ai"
+changelog:
+  - version: "1.0"
+    date: "{date}"
+    changes: ["Project initialized"]
+related:
+  - "[[ROADMAP]]"
+  - "[[RE-ENTRY-PROMPTS]]"
+---
+
+# {scope} — Working Project
+
+> Type: {work_type}
+> Created: {date}
+> Codebase: `{codebase_path}`
+
+---
+
+## What Is This
+
+This directory contains the working artifacts for {description_of_work}. It is managed by the `kyro-ai` skill and follows an adaptive sprint workflow.
+
+---
+
+## For AI Agents — Mandatory Reading Order
+
+If you are an AI agent resuming work on this project, read these files in order:
+
+1. **This README** — You are here. Understand the project structure.
+2. **ROADMAP.md** — The adaptive roadmap with all planned sprints and execution rules.
+3. **Last completed sprint** — The most recent sprint file in `phases/`. Read its retro, recommendations, and debt table.
+4. **RE-ENTRY-PROMPTS.md** — Pre-written prompts for common actions. Copy the appropriate one.
+
+---
+
+## Directory Structure
+
+```
+{output_kyro_dir}/
+├── README.md              ← This file
+├── ROADMAP.md             ← Adaptive roadmap (living document)
+├── RE-ENTRY-PROMPTS.md    ← Context recovery prompts
+├── findings/              ← Analysis findings (one file per area)
+│   ├── 01-{slug}.md
+│   ├── 02-{slug}.md
+│   └── ...
+└── phases/               ← Sprint documents (generated one at a time)
+    ├── SPRINT-1-{slug}.md
+    ├── SPRINT-2-{slug}.md
+    └── ...
+```
+
+---
+
+## Absolute Paths
+
+| Resource | Path |
+|----------|------|
+| Codebase | `{codebase_path}` |
+| Working Directory | `{output_kyro_dir}` |
+| Findings | `{output_kyro_dir}/findings/` |
+| Sprints | `{output_kyro_dir}/phases/` |
+| Roadmap | `{output_kyro_dir}/ROADMAP.md` |
+| Re-entry Prompts | `{output_kyro_dir}/RE-ENTRY-PROMPTS.md` |
+
+---
+
+## Sprint System Rules
+
+1. Sprints are generated **one at a time** — never pre-generated
+2. Each sprint feeds from the previous sprint's retro and recommendations
+3. The accumulated debt table passes from sprint to sprint, never losing items
+4. The roadmap adapts based on what execution reveals
+5. Re-entry prompts are updated after each sprint for context persistence
+
+---
+
+## Current State — Baseline
+
+<!-- Filled during INIT with baseline metrics -->
+
+| Metric | Value |
+|--------|-------|
+| {metric_name} | {metric_value} |
+
+---
+
+## Sprint Map
+
+<!-- Updated as sprints are completed -->
+
+| Sprint | Status | Focus | Key Deliverables |
+|--------|--------|-------|-----------------|
+| 1 | {status} | {focus} | {deliverables} |

package/skills/sprint-forge/assets/templates/REENTRY-PROMPTS.md

@@ -0,0 +1,132 @@
+---
+title: "{scope} — Re-entry Prompts"
+date: "{date}"
+updated: "{date}"
+scope: "{scope}"
+type: "execution-plan"
+status: "active"
+version: "1.0"
+agents:
+  - "{agent_model}"
+tags:
+  - "{scope}"
+  - "execution-plan"
+  - "reentry"
+  - "kyro-ai"
+changelog:
+  - version: "1.0"
+    date: "{date}"
+    changes: ["Re-entry prompts created"]
+related:
+  - "[[README]]"
+  - "[[ROADMAP]]"
+---
+
+# {scope} — Re-entry Prompts
+
+> Last updated: {date}
+> Current sprint: {current_sprint_number}
+
+These prompts help you (or a new agent) recover full project context in a new session.
+
+---
+
+## Output Directory
+
+```
+{output_kyro_dir}
+```
+
+This is where all kyro-ai documents for this project live. All file paths below are relative to this directory.
+
+---
+
+## Quick Reference
+
+| Sprint | File | Status |
+|--------|------|--------|
+| 1 | `phases/SPRINT-1-{slug}.md` | {status} |
+
+---
+
+## Dynamic Paths
+
+| Resource | Path |
+|----------|------|
+| Codebase | `{codebase_path}` |
+| Working Directory | `{output_kyro_dir}` |
+| Roadmap | `{output_kyro_dir}/ROADMAP.md` |
+| Latest Sprint | `{output_kyro_dir}/phases/{latest_sprint_file}` |
+
+---
+
+## Scenario 1 — First Sprint (after INIT)
+
+Use this prompt when INIT has been completed and you need to generate Sprint 1.
+
+```
+I'm working on the {scope} project. The analysis and roadmap have been created.
+
+Read these files in order:
+1. {output_kyro_dir}/README.md
+2. {output_kyro_dir}/ROADMAP.md
+3. The finding files in {output_kyro_dir}/findings/
+
+Then use /kyro:forge to generate Sprint 1. Follow the roadmap's Sprint 1 definition
+and the corresponding finding file(s) as input.
+```
+
+---
+
+## Scenario 2 — Next Sprint (Sprint N)
+
+Use this prompt when Sprint N-1 is complete and you need to generate Sprint N.
+
+```
+I'm continuing work on the {scope} project. Sprint {N-1} has been completed.
+
+Read these files in order:
+1. {output_kyro_dir}/README.md
+2. {output_kyro_dir}/ROADMAP.md
+3. {output_kyro_dir}/phases/{last_sprint_file} (pay attention to Retro, Recommendations, and Debt table)
+4. The finding file(s) for Sprint {N}: {output_kyro_dir}/findings/{next_finding_file}
+
+Then use /kyro:forge to generate Sprint {N}. Ensure all recommendations from Sprint {N-1}
+are addressed in the Disposition table.
+```
+
+---
+
+## Scenario 3 — Execute Current Sprint
+
+Use this prompt when a sprint has been generated but not yet executed.
+
+```
+I'm working on the {scope} project. Sprint {N} has been generated and needs execution.
+
+Read these files in order:
+1. {output_kyro_dir}/README.md
+2. {output_kyro_dir}/ROADMAP.md
+3. {output_kyro_dir}/phases/{current_sprint_file}
+
+Then use /kyro:forge to execute Sprint {N}. Work through each phase and task,
+marking progress as you go. Add emergent phases if new work is discovered.
+```
+
+---
+
+## Scenario 4 — Check Project Status
+
+Use this prompt to get a progress report.
+
+```
+I need a status report on the {scope} project.
+
+Read these files:
+1. {output_kyro_dir}/README.md
+2. {output_kyro_dir}/ROADMAP.md
+3. All sprint files in {output_kyro_dir}/phases/
+
+Then use /kyro:forge to generate a status report showing: completed sprints,
+accumulated debt, metrics, and what's planned next.
+```

package/skills/sprint-forge/assets/templates/ROADMAP.md

@@ -0,0 +1,126 @@
+---
+title: "{scope} — Adaptive Roadmap"
+date: "{date}"
+updated: "{date}"
+scope: "{scope}"
+type: "plan"
+status: "active"
+version: "1.0"
+agents:
+  - "{agent_model}"
+tags:
+  - "{scope}"
+  - "plan"
+  - "roadmap"
+  - "kyro-ai"
+changelog:
+  - version: "1.0"
+    date: "{date}"
+    changes: ["Roadmap created"]
+related:
+  - "[[README]]"
+  - "[[RE-ENTRY-PROMPTS]]"
+---
+
+# {scope} — Adaptive Roadmap
+
+> Generated by `kyro-ai` on {date}
+
+---
+
+## Project Paths
+
+| Path | Value |
+|------|-------|
+| Codebase | `{codebase_path}` |
+| Working Directory | `{output_kyro_dir}` |
+| Findings | `{output_kyro_dir}/findings/` |
+| Sprints | `{output_kyro_dir}/phases/` |
+
+---
+
+## Execution Rules
+
+These rules govern the entire sprint lifecycle. They are non-negotiable.
+
+1. **Sprint-by-Sprint** — Sprints are generated ONE AT A TIME. Never pre-generate all sprints. Each sprint is informed by the results of the previous one.
+2. **Retro Feeds Forward** — The retrospective and recommendations of Sprint N-1 are formal inputs for Sprint N. They cannot be ignored.
+3. **Recommendations are Dispositioned** — Every recommendation from the previous sprint must either become a task or have its deferral justified in the Disposition table.
+4. **Debt is Inherited** — The Accumulated Technical Debt table passes from sprint to sprint in full. Items are never deleted, only resolved.
+5. **Phases are Suggested** — The roadmap defines suggested phases per sprint. During execution, emergent phases MUST be added when new work is discovered.
+6. **Emergent Findings Generate Phases** — If execution reveals issues not covered by the plan, new phases are added to the current sprint.
+7. **Re-entry Prompts are Updated** — After INIT and after each executed sprint, re-entry prompts are refreshed to reflect current state.
+8. **Roadmap Adapts** — If execution reveals that planned sprints need modification, this roadmap is updated. The plan serves execution, not the reverse.
+9. **Definition of Done** — Each sprint has explicit completion criteria. A sprint is not done until all DoD items are checked.
+
+---
+
+## Task States
+
+| Symbol | State | Meaning |
+|--------|-------|---------|
+| `[ ]` | Pending | Not started |
+| `[~]` | In Progress | Currently being worked on |
+| `[x]` | Done | Completed and verified |
+| `[!]` | Blocked | Cannot proceed — blocker documented |
+| `[-]` | Skipped | Intentionally skipped with justification |
+| `[>]` | Carry-over | Not completed — carried over to next sprint |
+
+---
+
+## Sprint Template
+
+Each sprint in this roadmap follows this structure:
+
+| Field | Description |
+|-------|-------------|
+| Sprint # | Sequential number |
+| Finding Source | Which finding file(s) this sprint addresses |
+| Version Target | Target version after this sprint (if applicable) |
+| Type | audit / refactor / feature / bugfix / debt |
+| Focus | One-line description of the sprint's primary goal |
+| Suggested Phases | Initial phases suggested by this roadmap (may expand during execution) |
+| Dependencies | Which sprints must complete before this one |
+
+---
+
+## Dependency Map
+
+<!-- Fill during INIT: show which sprints depend on others -->
+<!-- Example:
+Sprint 1 → Sprint 2 → Sprint 3
+                    ↘ Sprint 4 → Sprint 5
+-->
+
+```
+{dependency_diagram}
+```
+
+---
+
+## Sprint Summary
+
+<!-- Fill during INIT: one row per planned sprint -->
+
+| Sprint | Finding Source | Version | Type | Focus | Dependencies | Status |
+|--------|--------------|---------|------|-------|-------------|--------|
+| 1 | `{finding_file}` | {version} | {type} | {focus} | — | pending |
+
+---
+
+## Detailed Sprint Definitions
+
+<!-- Fill during INIT: expand each sprint with suggested phases -->
+
+### Sprint 1 — {title}
+
+- **Source**: `findings/{finding_file}`
+- **Version Target**: {version}
+- **Type**: {type}
+- **Focus**: {focus}
+- **Dependencies**: None
+- **Suggested Phases**:
+  1. {phase_1_name} — {phase_1_description}
+  2. {phase_2_name} — {phase_2_description}
+
+<!-- Add more sprints as needed. The number of sprints is determined by the analysis. -->

package/skills/sprint-forge/assets/templates/SPRINT.md

@@ -0,0 +1,189 @@
+---
+title: "Sprint {N} — {title}"
+date: "{date}"
+updated: "{date}"
+scope: "{scope}"
+type: "sprint-plan"
+status: "active"
+version: "1.0"
+sprint: {N}
+progress: 0
+previous_doc: "[[SPRINT-{N-1}-{previous_slug}]]"
+next_doc: "[[SPRINT-{N+1}-{next_slug}]]"
+parent_doc: "[[ROADMAP]]"
+agents:
+  - "{agent_model}"
+tags:
+  - "{scope}"
+  - "sprint-plan"
+  - "sprint-{N}"
+changelog:
+  - version: "1.0"
+    date: "{date}"
+    changes: ["Sprint generated"]
+related:
+  - "[[ROADMAP]]"
+  - "[[{finding_file_ref}]]"
+---
+
+# Sprint {N} — {title}
+
+> Source: `findings/{finding_file}`
+> Previous Sprint: `phases/{previous_sprint_file}` | None
+> Version Target: {version}
+> Type: {type}
+> Carry-over: {carry_over_count} items from previous sprint
+> Execution Date: {execution_date}
+> Executed By: {executor}
+
+---
+
+## Sprint Objective
+
+{Clear, one-paragraph description of what this sprint aims to accomplish.}
+
+---
+
+## Disposition of Previous Sprint Recommendations
+
+<!-- Skip this section for Sprint 1 (no previous sprint). -->
+<!-- For Sprint 2+, EVERY recommendation from Sprint N-1 must appear here. -->
+
+| # | Recommendation | Action | Where | Justification |
+|---|---------------|--------|-------|---------------|
+| 1 | {recommendation_text} | Incorporated / Deferred / Resolved / N/A | Phase X, Task Y / Sprint Z | {why} |
+
+**Actions**:
+- **Incorporated**: Added as a task in this sprint. Specify phase and task.
+- **Deferred**: Postponed to a future sprint. Specify target sprint and justify.
+- **Resolved**: Already resolved by previous work. Explain when/how.
+- **N/A**: No longer applicable. Explain why.
+- **Converted to Phase**: Recommendation was significant enough to become an entire phase (not just a task). Specify which phase.
+
+---
+
+## Phases
+
+### Phase 1 — {phase_name}
+
+**Objective**: {What this phase accomplishes}
+
+**Tasks**:
+
+- [ ] **T1.1**: {task_description}
+  - Files: `{file_path}`
+  - Evidence: {inline_evidence — e.g., trace logs, before/after snapshots, table of affected items, verification marks}
+  - Verification: {how_to_verify}
+
+- [ ] **T1.2**: {task_description}
+  - Files: `{file_path}`
+  - Evidence: {inline_evidence}
+  - Verification: {how_to_verify}
+
+### Phase 2 — {phase_name}
+
+**Objective**: {What this phase accomplishes}
+
+**Tasks**:
+
+- [ ] **T2.1**: {task_description}
+  - Files: `{file_path}`
+  - Verification: {how_to_verify}
+
+<!-- Add more phases as needed. Phases come from the roadmap's suggested phases + recommendations + debt items. -->
+
+---
+
+## Emergent Phases
+
+<!-- This section starts EMPTY. It is populated during sprint EXECUTION when new work is discovered.
+     Emergent phases are expected and encouraged. They represent the adaptive nature of this workflow. -->
+
+<!-- Example:
+### Emergent Phase — {name}
+
+**Reason**: {Why this phase was added during execution}
+
+**Tasks**:
+
+- [ ] **TE.1**: {task_description}
+  - Files: `{file_path}`
+  - Verification: {how_to_verify}
+-->
+
+---
+
+## Findings Consolidation
+
+<!-- This section is filled during sprint CLOSE, before the Retro. Consolidate ALL significant discoveries made during execution into a single reference table. -->
+
+| # | Finding | Origin Phase | Impact | Action Taken |
+|---|---------|-------------|--------|-------------|
+| 1 | {finding_description} | Phase {X} / Emergent | {high/medium/low} | {task_ref / debt_ref / deferred} |
+
+<!-- Include every significant discovery, not just those that generated tasks. This table becomes a quick-reference for future sprints. -->
+
+---
+
+## Accumulated Technical Debt
+
+<!-- For Sprint 1: start fresh. For Sprint 2+: copy the FULL table from Sprint N-1 and add new items. -->
+
+| # | Item | Origin | Sprint Target | Status | Resolved In |
+|---|------|--------|--------------|--------|-------------|
+| 1 | {debt_item} | {where_discovered} | Sprint {X} | open | — |
+
+**Status values**: `open` | `in-progress` | `resolved` | `deferred` | `carry-over`
+
+**Rules**:
+- Never delete a row — only change status
+- New items are appended at the bottom
+- Inherited items keep their original numbers
+- When resolved, fill "Resolved In" with the sprint number
+
+---
+
+## Definition of Done
+
+- [ ] All phase tasks completed or explicitly skipped with justification
+- [ ] All emergent phase tasks completed
+- [ ] Accumulated debt table updated (new items added, resolved items marked)
+- [ ] Retro section filled
+- [ ] Recommendations for next sprint documented
+- [ ] Re-entry prompts updated to reflect current state
+- [ ] {project_specific_criteria}
+
+---
+
+## Retro
+
+<!-- Filled when the sprint is CLOSED. Do not fill during generation. -->
+
+### What Went Well
+
+-
+
+### What Didn't Go Well
+
+-
+
+### Surprises / Unexpected Findings
+
+-
+
+### New Technical Debt Detected
+
+<!-- List new debt items discovered during this sprint, referencing their D{n} numbers from the Accumulated Debt table. -->
+
+-
+
+---
+
+## Recommendations for Sprint {N+1}
+
+<!-- Filled when the sprint is CLOSED. Each recommendation becomes a candidate task for the next sprint.
+     The next sprint's Disposition table will address each one. -->
+
+1.
+2.
+3.