kyro-ai 3.2.1 → 3.2.3

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

@@ -1,253 +1,27 @@
-# SPRINT Mode — Generate & Execute Sprints
+# SPRINT Mode — Router
 
-This mode generates the next sprint from roadmap + previous sprint + debt, and optionally executes it task by task.
+This file is the lightweight index for sprint work. Do not load the full sprint protocol upfront.
 
----
+## Route
 
-## When This Mode Activates
+| Need | Load |
+|------|------|
+| Generate the next sprint | `plan-sprint.md` |
+| Execute pending sprint tasks | `execute-task.md` |
+| Validate task or phase quality | `review-task.md` |
+| Close sprint, retro, debt, roadmap, re-entry | `close-sprint.md` |
+| Resume interrupted or inconsistent state | `recover.md` |
 
-| EN Signals | ES Signals |
-|-----------|-----------|
-| "generate sprint", "next sprint", "execute sprint", "run sprint", "continue sprint" | "genera sprint", "siguiente sprint", "ejecuta sprint", "corre sprint", "continúa sprint" |
+## Required read order
 
----
+1. `.agents/kyro/scopes/{scope}/state.json`
+2. `.agents/kyro/scopes/{scope}/index.json`
+3. The routed mode file above
+4. Only the helpers/templates named by that routed mode
 
-## Sub-Modes
-
-| Sub-Mode | Trigger | What Happens |
-|----------|---------|--------------|
-| **GENERATE** | "generate", "create", default when sprint file doesn't exist | Creates the sprint document only |
-| **EXECUTE** | "execute", "run", "implement", sprint file already exists | Implements tasks from an existing sprint |
-| **GENERATE+EXECUTE** | "generate and execute", "do the next sprint" | Generates then immediately executes |
-
-If ambiguous, ask:
-
-> "Should I **generate** the sprint document, **execute** an existing sprint, or **both**?"
-
----
-
-## GENERATE Workflow
-
-### Step 0 — Locate Output Directory
-
-Determine `{output_kyro_dir}` before reading any sprint files:
-
-1. **Re-entry prompt paths** — If the user's message contains absolute file paths (e.g. `/Users/.../ROADMAP.md`), extract `{output_kyro_dir}` from those paths. This is the most reliable source.
-2. **Explicit path** — If the user mentions a path directly, use it.
-3. **Auto-discover** — Scan `{cwd}/.agents/kyro/scopes/`:
-   - Single directory found → use it
-   - Multiple directories → ask: "Which project? Found: {list}"
-4. **Ask** — If none of the above: "Where are your kyro-ai documents? (e.g. `.agents/kyro/scopes/my-project/`)"
-
-Once resolved, all subsequent steps use `{output_kyro_dir}` as the base for all file paths.
-
-### Step 1 — Determine Sprint Number
-
-1. Read `ROADMAP.md` to understand the planned sprints
-2. Scan `phases/` directory for existing sprint files
-3. The next sprint number = highest existing sprint + 1
-4. If no sprints exist, start with Sprint 1
-
-### Step 2 — Gather Inputs
-
-Read the required inputs as defined in [sprint-generator.md](../helpers/sprint-generator.md):
-
-1. **Roadmap section**: Open `ROADMAP.md`, locate Sprint {N} definition
-   - Extract: title, focus, type, version target, suggested phases
-2. **Previous sprint** (Sprint 2+): Open `phases/SPRINT-{N-1}-*.md`
-   - Extract: Retro, Recommendations, Accumulated Debt Table
-3. **Finding file(s)**: Open the finding file(s) mapped to this sprint in the roadmap
-   - Extract: summary, details, affected files, recommendations
-
-### Step 3 — Build Disposition Table (Sprint 2+)
-
-For every recommendation from Sprint N-1, determine what happens to it:
-
-| # | Recommendation | Action | Where | Justification |
-|---|---------------|--------|-------|---------------|
-| 1 | {text from sprint N-1} | Incorporated | Phase 2, T2.3 | Directly addresses API consistency |
-| 2 | {text from sprint N-1} | Deferred | Sprint 5 | Requires schema migration first |
-| 3 | {text from sprint N-1} | N/A | — | Fixed by Sprint 2 emergent phase |
-| 4 | {text from sprint N-1} | Converted to Phase | Phase 4 | Significant enough to warrant its own phase |
-
-**Every recommendation MUST appear in this table.** No exceptions.
-
-**Action options**: Incorporated, Deferred, Resolved, N/A, **Converted to Phase** (when a recommendation becomes an entire phase, not just a task).
-
-**Reference**: See [sprint-generator.md](../helpers/sprint-generator.md) → Step 4 for action options.
-
-### Step 4 — Build Phases
-
-Assemble phases from three sources:
-
-1. **Roadmap-suggested phases**: Starting point from the roadmap
-2. **Recommendation phases**: Incorporated recommendations that need their own phase
-3. **Debt phases**: Debt items targeting this sprint
-
-For each phase:
-- **Objective**: Clear statement of what the phase accomplishes
-- **Tasks**: List with checkboxes, task IDs (T{phase}.{task}), descriptions, file paths, verification criteria
-
-**Reference**: See [sprint-generator.md](../helpers/sprint-generator.md) → Step 5 for phase assembly rules.
-
-### Step 5 — Assemble Sprint Document
-
-Use the [SPRINT.md template](../templates/SPRINT.md):
-
-1. Fill frontmatter properties with actual values (title, date, project, sprint number, previous/next doc links, related findings)
-2. Fill metadata: source finding, previous sprint, version target, type, carry-over count
-3. Write sprint objective
-4. Write Disposition table (Sprint 2+)
-5. Write phases with tasks
-6. Copy debt table from previous sprint + add new items
-7. Write Definition of Done
-8. Leave Retro and Recommendations sections EMPTY
-
-**Reference**: See [debt-tracker.md](../helpers/debt-tracker.md) for debt table rules.
-
-### Step 6 — Write Sprint File
-
-Save to: `{sprints_dir}/SPRINT-{N}-{slug}.md`
-
-The slug is derived from the sprint's focus area (e.g., `architecture-cleanup`, `api-consistency`).
-
----
-
-## EXECUTE Workflow
-
-### Step 7 — Read Sprint
-
-Load the sprint file to execute. Verify it has:
-- Phases with tasks
-- Debt table
-- Definition of Done
-
-**Fill execution metadata**: Set `Execution Date` to today's date and `Executed By` to the executor's name in the sprint header. Also update the frontmatter `updated` field to today's date. These fields track who executed the sprint and when.
-
-### Step 8 — Execute Task by Task
-
-For each task in each phase:
-
-1. **Mark in-progress**: Change `[ ]` to `[~]`
-2. **Do the work**:
-   - Read relevant files
-   - Write/modify code as needed
-   - Run verification commands
-   - Test changes
-3. **Mark done**: Change `[~]` to `[x]`
-4. **Or mark blocked**: Change `[~]` to `[!]` with explanation
-5. **Or mark carry-over**: Change `[~]` to `[>]` — when a task cannot be completed in this sprint but is not blocked. It will be carried over to the next sprint.
-
-**Document evidence inline**: For each task, fill the `Evidence` field with concrete proof of work — trace logs, before/after snapshots, tables of affected items, verification marks. Evidence is not optional; it makes the sprint auditable.
-
-**Execution order**: Process phases in order (Phase 1 → Phase 2 → ...). Within a phase, process tasks in order unless dependencies require different ordering.
-
-**Persistence rule — checkpoint per phase**: After completing all tasks in a phase, write the sprint file to disk with all status updates (`[x]`, `[!]`, `[>]`) and evidence for that phase. This ensures progress survives unexpected interruptions (agent crash, session timeout, context overflow) without disrupting task-to-task flow within a phase. Do NOT write the file after every individual task — that fragments the agent's focus and wastes I/O. Do NOT defer all writes to sprint close — that risks losing all progress tracking on failure.
-
-**Code quality**: Write production-quality code. Follow existing project patterns. Do not introduce new patterns without justification.
-
-### Step 9 — Handle Emergent Work
-
-During execution, you may discover work not covered by the plan. This is expected.
-
-**When to add an Emergent Phase**:
-- Found a bug that must be fixed before continuing
-- Discovered a dependency that was not in the analysis
-- A task reveals additional scope that cannot be deferred
-
-**How to add**:
-1. Add an "Emergent Phase" section in the sprint document (after planned phases)
-2. Include: phase name, reason for emergence, tasks with IDs (TE.1, TE.2, ...)
-3. Update Definition of Done to include emergent tasks
-
-**Rule**: Do not add emergent phases for nice-to-haves. Only for work that is necessary to meet the sprint objective or that would create debt if deferred.
-
-### Step 10 — Close Sprint
-
-When all tasks are done (or explicitly skipped/blocked/carried-over):
-
-**10a. Consolidate Findings**: Before filling the retro, complete the **Findings Consolidation** table. Review all phases (planned and emergent) and list every significant discovery with its origin, impact, and action taken. This creates an auditable trail of what was learned.
-
-1. **Fill Retro section**:
-   - What Went Well: Things that worked as expected or better
-   - What Didn't Go Well: Challenges, blockers, things that took longer
-   - Surprises: Unexpected findings or outcomes
-   - **New Technical Debt Detected**: List new debt items discovered during execution, referencing their D{n} numbers from the Accumulated Debt table
-
-2. **Fill Recommendations for Sprint N+1**:
-   - Numbered list of specific, actionable recommendations
-   - These become formal input for the next sprint's Disposition table
-   - Include both technical and process recommendations
-
-3. **Update Debt Table**:
-   - Mark resolved items: Status → `resolved`, fill "Resolved In"
-   - Add new items discovered during execution
-   - Update deferred items if timelines changed
-   - Follow all rules from [debt-tracker.md](../helpers/debt-tracker.md)
-
-4. **Update Frontmatter**:
-   - Set `updated` to today's date
-   - Set `status` to `"completed"` (or `"active"` if carry-overs exist)
-   - Set `progress` to final completion percentage (0-100)
-   - Append changelog entry: `{"version": "1.1", "date": "{today}", "changes": ["Sprint completed"]}`
-
-5. **Verify Definition of Done**:
-   - Check every DoD item
-   - Mark as complete or document why it's not
-
-### Step 11 — Update Re-entry Prompts
-
-After sprint execution:
-
-1. Open `{output_kyro_dir}/RE-ENTRY-PROMPTS.md`
-2. Update current sprint number
-3. Update file references (last sprint, next finding)
-4. Update Quick Reference table with new sprint status
-5. Update "Last updated" date
-
-**Reference**: See [reentry-generator.md](../helpers/reentry-generator.md) for update rules.
-
-### Step 12 — Update Roadmap (If Needed)
-
-If execution revealed that the roadmap needs adjustment:
-
-- A planned sprint no longer makes sense → remove or modify it
-- A new sprint is needed → add it to the roadmap
-- Sprint dependencies changed → update the dependency map
-- Phase suggestions for future sprints should change → update them
-
-**This is the ADAPTIVE principle**: The roadmap serves execution, not the reverse.
-
----
-
-## Critical Rules for Sprint Mode
-
-1. **One sprint at a time** — NEVER generate Sprint N+1 before Sprint N is complete
-2. **Disposition is mandatory** — Every recommendation from Sprint N-1 must be in the Disposition table
-3. **Emergent phases are welcome** — But only for necessary work, not nice-to-haves
-4. **Debt table is inherited completely** — Never drop items, never reset the table
-5. **Re-entry prompts must be updated** — Every sprint execution ends with a prompt update
-6. **Retro is honest** — Don't sugarcoat. Document real challenges and surprises.
-7. **Recommendations are specific** — "Improve tests" is not a recommendation. "Add unit tests for the auth middleware error paths in auth.ts:45-80" is.
-
----
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| No roadmap found | INIT mode must be run first. Inform user. |
-| Previous sprint not found | Check if sprint numbering is correct. If Sprint 1, this is expected. |
-| Finding file not found | Check roadmap mapping. The file may have been renamed or the mapping may be wrong. |
-| All tasks blocked | Document blockers in retro, close sprint as incomplete, recommend resolution in Sprint N+1. |
-| Sprint file already exists | Ask user: overwrite, resume execution, or skip to next sprint. |
-
----
-
-## References
-
-- [sprint-generator.md](../helpers/sprint-generator.md) — Sprint generation algorithm
-- [debt-tracker.md](../helpers/debt-tracker.md) — Debt table rules
-- [reentry-generator.md](../helpers/reentry-generator.md) — Re-entry prompt updates
-- [SPRINT.md template](../templates/SPRINT.md) — Sprint document structure
+## Invariants
 
+- One sprint at a time.
+- Previous retro, recommendations, and debt feed the next sprint.
+- Checkpoint after each phase, not every task.
+- Markdown remains evidence; JSON summaries are the routing index.

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

@@ -1,145 +1,63 @@
-# STATUS Mode — Project Progress Report
+# STATUS Mode — Summary-First Project Report
 
-This mode reads all project artifacts and generates a comprehensive progress report.
+This mode reports progress from structured summaries first. Markdown is the fallback evidence, not the default startup context.
 
----
+## Inputs
 
-## When This Mode Activates
+1. Read `.agents/kyro/kyro.json`.
+2. Resolve scope and read `.agents/kyro/scopes/{scope}/state.json`.
+3. Read `.agents/kyro/scopes/{scope}/index.json`.
+4. Read summary files listed in `index.json`:
+   - `ROADMAP.summary.json`
+   - active or latest `SPRINT-*.summary.json`
+   - `DEBT.summary.json` when present
+5. Open Markdown only for missing summary fields, `full` reports, or debt mutations.
 
-| 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" |
+## Report variants
 
----
+| Variant | Context policy |
+|---------|----------------|
+| `brief` or empty | Summaries only unless a required field is missing. |
+| `full` | Summaries first, then selected Markdown evidence. |
+| `debt` | Debt summary first, then latest debt table if needed. |
+| `debt-*` | Load `../helpers/debt-tracker.md`, mutate source Markdown, refresh summaries. |
 
-## Prerequisites
+## Metrics
 
-- 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)
+Compute from summaries when available:
 
----
+| Metric | Source |
+|--------|--------|
+| Planned/completed sprints | roadmap summary + sprint summaries |
+| Task counts | sprint summaries |
+| Blocked/carry-over tasks | sprint summaries |
+| Open/resolved/deferred debt | debt summary or latest sprint summary |
+| Roadmap adaptations | roadmap summary |
+| Next action | `state.json.nextAction` and `index.json.nextTask` |
 
-## Workflow
+## Missing summaries
 
-### Step 0 — Locate Output Directory
+If a summary is missing:
 
-Before reading any files, determine `{output_kyro_dir}`:
+1. Open the corresponding Markdown source.
+2. Complete the report.
+3. Warn that this scope needs summary refresh.
+4. If mutating debt/status, write the missing summary before finishing.
 
-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/`)"
+## Output
 
-### Step 1 — Read Project State
+For `brief`, show only:
 
-Read the following files:
+- scope and status
+- active sprint / next action
+- task progress
+- open debt count
+- next recommended command
 
-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
+For `full`, include roadmap health, sprint table, debt trend, and re-entry pointer.
 
-### Step 2 — Calculate Metrics
+## Rules
 
-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
+- Do not read every sprint Markdown file when summaries exist.
+- Debt items are never deleted.
+- Keep `index.json` aligned with any report mutation.

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

@@ -0,0 +1,29 @@
+# Close Sprint Mode
+
+Close a sprint or session by updating only the artifacts required for handoff and learning.
+
+## Inputs
+
+1. Read `state.json`, `index.json`, and active sprint summary.
+2. Open active sprint Markdown for retro, findings consolidation, debt, and Definition of Done.
+3. Read `../helpers/debt-tracker.md` before changing debt rows.
+4. Read `../helpers/reentry-generator.md` only before updating re-entry prompts.
+5. Load roadmap Markdown only if execution changed future sprint sequencing.
+
+## Workflow
+
+1. Run the pre-close quality checkpoint.
+2. Consolidate findings from planned and emergent phases.
+3. Fill retro: went well, did not go well, surprises, new debt.
+4. Write recommendations for Sprint N+1.
+5. Update accumulated debt statuses and new debt rows.
+6. Verify Definition of Done.
+7. Update re-entry prompts and roadmap only when needed.
+8. Refresh `state.json`, `index.json`, active sprint summary, and debt summary.
+9. Propose learned rules for `.agents/kyro/scopes/rules.md`.
+
+## Rules
+
+- Retro must be honest and specific.
+- Re-entry context must point to the next action.
+- Markdown is the durable evidence; summaries are the routing cache.

package/skills/sprint-forge/assets/modes/execute-task.md

@@ -0,0 +1,26 @@
+# Execute Task Mode
+
+Execute the active sprint task by task while keeping checkpoints cheap and auditable.
+
+## Inputs
+
+1. Read `state.json` and `index.json`.
+2. Read the active `SPRINT-*.summary.json`.
+3. Open the active sprint Markdown only for the current phase/task details.
+4. Read `review-task.md` only when validating completed work.
+
+## Workflow
+
+1. Set execution metadata in the sprint file when execution starts.
+2. Process phases in order, and tasks in order unless dependencies require otherwise.
+3. Mark the current task `[~]`, perform the work, run verification, then mark `[x]`, `[!]`, or `[>]`.
+4. Record concrete evidence inline for every task.
+5. Add an emergent phase only for required work that blocks the sprint objective or would create debt if deferred.
+6. After each phase, write the sprint file, refresh `SPRINT-*.summary.json`, `index.json`, and `state.json`.
+
+## Rules
+
+- Do not checkpoint after every task unless the task itself completes the phase.
+- Do not defer all checkpointing to sprint close.
+- Do not introduce new project patterns without justification.
+- If implementation reveals the plan is wrong, return to `plan-sprint.md`.

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

@@ -0,0 +1,29 @@
+# Plan Sprint Mode
+
+Generate the next sprint from structured state first, then Markdown evidence only as needed.
+
+## Inputs
+
+1. Read `.agents/kyro/scopes/{scope}/state.json`.
+2. Read `.agents/kyro/scopes/{scope}/index.json`.
+3. Read `ROADMAP.summary.json` if present; otherwise open `ROADMAP.md`.
+4. For Sprint 2+, read previous `SPRINT-*.summary.json` first; open Markdown only for missing retro, recommendation, or debt detail.
+5. Read `../helpers/sprint-generator.md` only after the next sprint number is known.
+6. Load `../templates/SPRINT.md` only when writing the sprint file.
+
+## Workflow
+
+1. Resolve next sprint number from state/index and existing `phases/` files.
+2. Extract roadmap focus, type, target version, and suggested phases.
+3. Build the mandatory disposition table for every previous recommendation.
+4. Assemble phases from roadmap suggestions, carried recommendations, and due debt.
+5. Write `phases/SPRINT-{N}-{slug}.md`.
+6. Write `phases/SPRINT-{N}-{slug}.summary.json`.
+7. Update `state.json` with `activeSprint`, `currentPhase: "planning"`, and `nextAction: "execute_task"`.
+8. Update `index.json` with active sprint summary, next task, open debt count, and relevant paths.
+
+## Rules
+
+- Never generate Sprint N+1 before Sprint N is complete.
+- Every previous recommendation must be incorporated, deferred, resolved, marked N/A, or converted to a phase.
+- Debt is inherited completely; never reset or drop debt rows.

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

@@ -0,0 +1,23 @@
+# Recover Mode
+
+Recover Kyro when state, summaries, and Markdown disagree.
+
+## Inputs
+
+1. Read `.agents/kyro/kyro.json`.
+2. Read scope `state.json` and `index.json` if present.
+3. List available roadmap, sprint, and summary files.
+4. Open Markdown only for artifacts needed to rebuild missing structured state.
+
+## Workflow
+
+1. Identify the latest trustworthy artifact by timestamp and content completeness.
+2. Rebuild missing or stale `state.json`, `index.json`, and `*.summary.json` from Markdown evidence.
+3. Preserve user-authored Markdown; do not rewrite it unless fixing broken frontmatter or explicit state markers.
+4. Report what was recovered and the next recommended route.
+
+## Rules
+
+- Prefer preserving user work over making state look clean.
+- Never invent completed tasks without evidence.
+- If multiple scopes are plausible, ask the user to choose before writing.

package/skills/sprint-forge/assets/modes/review-task.md

@@ -0,0 +1,25 @@
+# Review Task Mode
+
+Validate completed Kyro work without loading unrelated lifecycle context.
+
+## Inputs
+
+1. Read `state.json`, `index.json`, and the active sprint summary.
+2. Open the active sprint Markdown only for the completed task or phase.
+3. Read `../helpers/reviewer.md` when classifying findings.
+4. Read project-specific quality commands from config or repository scripts.
+
+## Workflow
+
+1. Verify task evidence matches actual code/docs changes.
+2. Run relevant checks for the touched area.
+3. Classify findings as critical, warning, or suggestion.
+4. Block completion on critical issues.
+5. Record warnings and suggestions in the sprint evidence or retro queue.
+6. Refresh summaries after status changes.
+
+## Rules
+
+- Review happens during execution and at close.
+- Do not mark tasks complete without evidence.
+- Suggestions do not block, but they must be visible in retro inputs.

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

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "scope": "{scope}",
+  "open": 0,
+  "inProgress": 0,
+  "resolved": 0,
+  "deferred": 0,
+  "critical": 0,
+  "oldestOpenItem": null,
+  "sourceMarkdown": null,
+  "lastUpdated": "{date}"
+}