kyro-ai 3.2.2 → 3.3.0

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

@@ -0,0 +1,19 @@
+# Bugfix Analysis
+
+Use for broken behavior, regressions, or incorrect outputs.
+
+## Inspect
+
+1. Reproduce or restate the failure precisely.
+2. Trace the failing path from input to output.
+3. Identify root cause and blast radius.
+4. Search for the same pattern in nearby code.
+5. Find the narrowest verification that proves the fix.
+
+## Findings
+
+Document root cause, affected files, reproduction, expected behavior, proposed fix, and tests.
+
+## Sizing signals
+
+Use one sprint for localized fixes. Split only when reproduction, infrastructure, migration, or broad duplicated patterns require independent proof.

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

@@ -0,0 +1,28 @@
+# Feature Analysis
+
+Use for new user-visible behavior or capability changes.
+
+## Inspect
+
+1. Identify the public interface affected: command, API, UI, config, or artifact.
+2. Trace the smallest existing path that owns similar behavior.
+3. Read only the files needed to understand integration points, tests, and docs.
+4. Capture risks from compatibility, persistence, validation, or missing tests.
+
+## Findings
+
+Write findings only for distinct implementation concerns. Do not split by task labels alone.
+
+Each finding must include:
+
+- summary
+- affected files or modules
+- user-visible behavior
+- implementation recommendation
+- validation approach
+
+## Sizing signals
+
+Multiple sprints are justified when the feature has a dependency chain, public interface change, reusable foundation, separate review units, or risk that should be proven independently.
+
+One sprint is acceptable when the change is cohesive, low risk, and can be reviewed end-to-end safely.

package/skills/sprint-forge/assets/helpers/analysis/new-project.md

@@ -0,0 +1,18 @@
+# New Project Analysis
+
+Use when creating a new package, app, CLI, or workflow from scratch.
+
+## Inspect
+
+1. Clarify the user goal, target audience, and first usable slice.
+2. Identify comparable local patterns or repo conventions.
+3. Choose the minimum architecture needed for the first release.
+4. List unknowns that block implementation.
+
+## Findings
+
+Document scope, non-goals, interfaces, stack decisions, risks, and first milestone.
+
+## Sizing signals
+
+Multiple sprints are justified for scaffolding, core behavior, publishing, or integration phases that prove independently valuable milestones. Avoid planning speculative future features.

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

@@ -0,0 +1,18 @@
+# Refactor Analysis
+
+Use for structural changes that preserve intended behavior.
+
+## Inspect
+
+1. Identify the behavior that must remain stable.
+2. Map coupling, ownership boundaries, and current tests.
+3. Find the smallest safe sequence of changes.
+4. Note compatibility or migration constraints.
+
+## Findings
+
+Document current structure, target structure, affected modules, risks, and verification gates.
+
+## Sizing signals
+
+Split when a foundation must land before consumers, when compatibility must be preserved, or when review units would otherwise mix unrelated concerns. Keep as one sprint for local cleanups with strong tests.

package/skills/sprint-forge/assets/helpers/analysis/tech-debt.md

@@ -0,0 +1,18 @@
+# Tech Debt Analysis
+
+Use for cleanup, modernization, dependency, or maintainability work.
+
+## Inspect
+
+1. Identify debt symptoms and the behavior they affect.
+2. Separate blocking debt from cosmetic cleanup.
+3. Check tests, build health, and known constraints.
+4. Prioritize by risk reduction and unblock value.
+
+## Findings
+
+Document debt item, impact, affected files, remediation, and validation.
+
+## Sizing signals
+
+Split debt work when items have different risk profiles, owners, or dependency order. Group small related cleanups when they share the same verification path.

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

@@ -1,103 +1,72 @@
-# INIT Mode — Analysis, Roadmap & Scoped State
+# INIT Mode — Lean Analysis, Roadmap & Scoped State
 
-Use INIT when a scope has no Kyro roadmap yet. INIT creates human-readable evidence plus structured routing files so future commands do not reread everything.
+Use INIT when a scope has no Kyro roadmap. Optimize for justified sprint boundaries, not fewer sprints.
 
 ## Inputs
 
 - User request and current repository path.
 - `.agents/kyro/kyro.json` if present.
-- `../helpers/analysis-guide.md` for analysis strategy.
+- One work-type helper under `../helpers/analysis/` after routing.
 - Templates only when writing their artifact.
 
 ## Step 1 — Resolve scope
 
-Determine:
-
-| Field | Rule |
-|-------|------|
-| scope | Short kebab-case work topic, not the repo name. |
-| codebasePath | Usually current working directory. |
-| outputDir | Default `.agents/kyro/scopes/{scope}/`. |
-
-If scope or output directory is ambiguous, ask once. Then create the scoped directory structure.
+Determine `scope`, `codebasePath`, and `outputDir` (`.agents/kyro/scopes/{scope}/`). If scope or output directory is ambiguous, ask once. If the output directory exists, ask whether to resume or choose a different scope.
 
 ## Step 2 — Detect work type
 
-Classify the request as audit/refactor, feature, bugfix, new project, or tech debt. If unclear, ask before analysis.
+Classify as `feature`, `bugfix`, `audit`, `refactor`, `new-project`, or `tech-debt`. Load only the matching helper:
 
-## Step 3 — Analyze
-
-Use project search/read tools to inspect only what the work type requires:
+```text
+../helpers/analysis/{workType}.md
+```
 
-- Audit/refactor: broad architecture and quality scan.
-- Feature: integration points and missing behavior.
-- Bugfix: reproduce, root cause, blast radius.
-- New project: requirements and comparable patterns.
-- Tech debt: debt indicators and cleanup targets.
+## Step 3 — Analyze
 
-Let evidence determine findings. Do not force a fixed category list.
+Use project search/read tools only for the detected work type. Let evidence determine findings. Do not force category counts or split work by labels alone.
 
 ## Step 4 — Write findings
 
-Write each distinct finding to `{outputDir}/findings/NN-descriptive-slug.md`.
+Write each distinct finding to `{outputDir}/findings/NN-descriptive-slug.md` with summary, severity, affected files, details, recommendation, and validation.
 
-Each finding needs summary, severity, affected files, details, and recommendations. Use `analysis-guide.md` for the detailed format.
+## Step 5 — Decide sprint sizing
 
-## Step 5 — Write roadmap
+Before writing the roadmap, produce `sizingDecision`:
 
-Load `../templates/ROADMAP.md` only now. Write `{outputDir}/ROADMAP.md` with:
+```json
+{
+  "recommendedSprintCount": 1,
+  "riskLevel": "low | medium | high",
+  "rationale": "...",
+  "splitTriggers": [],
+  "whyNotFewer": "...",
+  "whyNotMore": "...",
+  "sprintProofs": []
+}
+```
 
-- project paths
-- finding-to-sprint map
-- sprint dependencies
-- sprint title/focus/type/version target
-- suggested phases
-- sprint summary table
+Consistency rules: count must match planned sprints; `sprintProofs.length` must match count; every sprint needs one proof; multi-sprint plans need non-empty `splitTriggers`; `whyNotFewer` and `whyNotMore` cannot be empty.
 
-## Step 6 — Scaffold human artifacts
+## Step 6 — Write artifacts
 
 Load templates only when writing:
 
-- `../templates/PROJECT-README.md` → `{outputDir}/README.md`
-- `../templates/REENTRY-PROMPTS.md` → `{outputDir}/RE-ENTRY-PROMPTS.md`
+- `../templates/ROADMAP.md` with paths, `sizingDecision`, dependency map, sprint summary, and sprint definitions.
+- `../templates/PROJECT-README.md` for scope overview.
+- `../templates/REENTRY-PROMPTS.md` for summary-first recovery.
 
-Create `{outputDir}/phases/` empty. Sprints are generated later.
+Create `{outputDir}/phases/` empty.
 
 ## Step 7 — Write structured routing files
 
-Create:
-
-- `{outputDir}/state.json` from `../templates/state.json`
-- `{outputDir}/index.json` from `../templates/index.json`
-- `{outputDir}/ROADMAP.summary.json` from `../templates/ROADMAP.summary.json`
-
-Initial values:
-
-```json
-{
-  "status": "planning",
-  "activeSprint": null,
-  "currentPhase": "init",
-  "nextAction": "plan_sprint"
-}
-```
-
-Update `.agents/kyro/kyro.json` so `scopes` includes this scope and `activeScope` points to it when appropriate.
+Create `state.json`, `index.json`, and `ROADMAP.summary.json`. Include `sizingDecision` in `index.json` and `ROADMAP.summary.json`. Update `.agents/kyro/kyro.json` with the scope and activeScope when appropriate.
 
 ## Output
 
-Report:
-
-- scope
-- work type
-- number of findings
-- planned sprint count
-- files created
-- next action: run `kyro-forge` to plan Sprint 1
+Report scope, work type, finding count, sprint count, sizing rationale, files created, and next action: run `kyro-forge` to plan Sprint 1.
 
 ## Rules
 
 - `kyro install` never creates scoped `state.json`; INIT does.
 - Markdown is durable evidence; JSON is the fast routing index.
-- Do not load sprint templates, debt tracker, or execution modes during INIT.
-- If the output directory already exists, ask whether to resume or choose a different scope.
+- Do not load sprint templates, debt tracker, execution modes, or unrelated analysis helpers during INIT.

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

@@ -6,6 +6,15 @@
   "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": [

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

@@ -5,6 +5,15 @@
   "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",