kyro-ai 3.2.1 → 3.2.3

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

@@ -27,45 +27,16 @@ related:
 > 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
+This directory stores Kyro artifacts for `{scope}`. Use structured summaries first; open Markdown only when a router needs durable evidence.
 
-```
-{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
-    └── ...
-```
+## Quick Resume
 
----
+1. Read `state.json`.
+2. Read `index.json`.
+3. Read `ROADMAP.summary.json`.
+4. Run `kyro-forge`, `kyro-status`, or `kyro-wrap-up`.
 
-## Absolute Paths
+## Paths
 
 | Resource | Path |
 |----------|------|
@@ -74,34 +45,19 @@ If you are an AI agent resuming work on this project, read these files in order:
 | 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` |
-
----
+| Re-entry | `{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 -->
+## Current State
 
 | Metric | Value |
 |--------|-------|
-| {metric_name} | {metric_value} |
-
----
+| Work type | {work_type} |
+| Planned sprints | {planned_sprint_count} |
+| Active sprint | {active_sprint} |
+| Next action | {next_action} |
 
 ## Sprint Map
 
-<!-- Updated as sprints are completed -->
-
-| Sprint | Status | Focus | Key Deliverables |
-|--------|--------|-------|-----------------|
-| 1 | {status} | {focus} | {deliverables} |
+| Sprint | Status | Focus | Proof |
+|--------|--------|-------|-------|
+| 1 | {status} | {focus} | {sprint_proof} |

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

@@ -27,106 +27,37 @@ related:
 > Last updated: {date}
 > Current sprint: {current_sprint_number}
 
-These prompts help you (or a new agent) recover full project context in a new session.
+Use these prompts to resume through summary-first routing. Open long Markdown only when a router asks for it.
 
----
-
-## 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
+## Fast Context
 
 | 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}` |
-
----
+| State | `{output_kyro_dir}/state.json` |
+| Index | `{output_kyro_dir}/index.json` |
+| Roadmap Summary | `{output_kyro_dir}/ROADMAP.summary.json` |
+| Sprints | `{output_kyro_dir}/phases/` |
 
-## Scenario 1 — First Sprint (after INIT)
-
-Use this prompt when INIT has been completed and you need to generate Sprint 1.
+## Resume Planning
 
+```text
+Continue Kyro scope `{scope}`. Read `{output_kyro_dir}/state.json`, `{output_kyro_dir}/index.json`, and `{output_kyro_dir}/ROADMAP.summary.json` first. Then use kyro-forge to plan the next sprint. Open ROADMAP.md or finding Markdown only if the router requests missing details.
 ```
-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/
+## Resume Execution
 
-Then use /kyro:forge to generate Sprint 1. Follow the roadmap's Sprint 1 definition
-and the corresponding finding file(s) as input.
+```text
+Continue active Kyro sprint for `{scope}`. Read state.json and index.json first, then the active SPRINT summary JSON if present. Use kyro-forge to route to execution, review, close, or recover. Open sprint Markdown only when required for the active task.
 ```
 
----
-
-## 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.
+## Status
 
+```text
+Report Kyro status for `{scope}`. Read state.json, index.json, ROADMAP.summary.json, SPRINT summaries, and DEBT.summary.json first. Use kyro-status brief unless full evidence is requested.
 ```
-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/
+## Closeout
 
-Then use /kyro:forge to generate a status report showing: completed sprints,
-accumulated debt, metrics, and what's planned next.
+```text
+Close the Kyro session for `{scope}`. Read state.json and index.json first, then use kyro-wrap-up. Update summaries and re-entry prompts after any Markdown changes.
 ```

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

@@ -26,8 +26,6 @@ related:
 
 > Generated by `kyro-ai` on {date}
 
----
-
 ## Project Paths
 
 | Path | Value |
@@ -37,80 +35,32 @@ related:
 | 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 Sizing Decision
 
-## Sprint Template
-
-Each sprint in this roadmap follows this structure:
+```json
+{sizing_decision_json}
+```
 
-| 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 |
+Acceptance:
 
----
+- `recommendedSprintCount` equals the sprint rows below.
+- Each sprint has exactly one `sprintProofs` entry.
+- Multi-sprint plans include at least one `splitTriggers` entry.
+- `whyNotFewer` and `whyNotMore` are non-empty.
 
 ## Dependency Map
 
-<!-- Fill during INIT: show which sprints depend on others -->
-<!-- Example:
-Sprint 1 → Sprint 2 → Sprint 3
-                    ↘ Sprint 4 → Sprint 5
--->
-
-```
+```text
 {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
+| Sprint | Finding Source | Version | Type | Focus | Dependencies | Proof | Status |
+|--------|----------------|---------|------|-------|--------------|-------|--------|
+| 1 | `{finding_file}` | {version} | {type} | {focus} | — | {sprint_proof} | pending |
 
-<!-- Fill during INIT: expand each sprint with suggested phases -->
+## Sprint Definitions
 
 ### Sprint 1 — {title}
 
@@ -119,8 +69,9 @@ Sprint 1 → Sprint 2 → Sprint 3
 - **Type**: {type}
 - **Focus**: {focus}
 - **Dependencies**: None
+- **Proof**: {sprint_proof}
 - **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. -->
+<!-- Add only justified sprints. Optimize for justified boundaries, not fewer sprints. -->

package/skills/sprint-forge/assets/templates/ROADMAP.summary.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "scope": "{scope}",
+  "status": "planned",
+  "summary": "{roadmap_summary}",
+  "plannedSprintCount": 0,
+  "completedSprintCount": 0,
+  "adaptationCount": 0,
+  "sizingDecision": {
+    "recommendedSprintCount": 0,
+    "riskLevel": "low",
+    "rationale": "{sizing_rationale}",
+    "splitTriggers": [],
+    "whyNotFewer": "{why_not_fewer}",
+    "whyNotMore": "{why_not_more}",
+    "sprintProofs": []
+  },
+  "nextRecommendedAction": "plan_sprint",
+  "openDecisions": [],
+  "relevantArtifactPaths": [
+    ".agents/kyro/scopes/{scope}/ROADMAP.md"
+  ],
+  "lastUpdated": "{date}"
+}

package/skills/sprint-forge/assets/templates/SPRINT.summary.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "scope": "{scope}",
+  "sprint": "SPRINT-{N}",
+  "status": "planned",
+  "completedTasks": 0,
+  "blockedTasks": 0,
+  "carryOverTasks": 0,
+  "nextRecommendedAction": "execute_task",
+  "nextTask": "{task_id}",
+  "openDecisions": [],
+  "filesTouched": [],
+  "debtDeltas": [],
+  "sourceMarkdown": ".agents/kyro/scopes/{scope}/phases/SPRINT-{N}-{slug}.md",
+  "lastUpdated": "{date}"
+}

package/skills/sprint-forge/assets/templates/index.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "scope": "{scope}",
+  "roadmapSummary": "{roadmap_summary}",
+  "activeSprintSummary": null,
+  "openDebtCount": 0,
+  "nextTask": null,
+  "sizingDecision": {
+    "recommendedSprintCount": 0,
+    "riskLevel": "low",
+    "rationale": "{sizing_rationale}",
+    "splitTriggers": [],
+    "whyNotFewer": "{why_not_fewer}",
+    "whyNotMore": "{why_not_more}",
+    "sprintProofs": []
+  },
+  "relevantArtifactPaths": {
+    "roadmap": ".agents/kyro/scopes/{scope}/ROADMAP.md",
+    "roadmapSummary": ".agents/kyro/scopes/{scope}/ROADMAP.summary.json",
+    "sprints": ".agents/kyro/scopes/{scope}/phases",
+    "reentry": ".agents/kyro/scopes/{scope}/RE-ENTRY-PROMPTS.md"
+  },
+  "lastUpdated": "{date}"
+}

package/skills/sprint-forge/assets/templates/state.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "scope": "{scope}",
+  "status": "planning",
+  "activeSprint": null,
+  "currentPhase": "init",
+  "nextAction": "plan_sprint",
+  "roadmapPath": ".agents/kyro/scopes/{scope}/ROADMAP.md",
+  "sprintsPath": ".agents/kyro/scopes/{scope}/phases",
+  "lastUpdated": "{date}"
+}

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

@@ -1,207 +0,0 @@
-# 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.