kyro-ai 3.2.1 → 3.2.3

package/skills/sprint-forge/SKILL.md

@@ -38,7 +38,7 @@ allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task
 
 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/modes/](assets/modes/)** — lightweight routers plus focused INIT, planning, execution, review, close, recover, and STATUS 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
 
@@ -54,7 +54,7 @@ Kyro is an **adaptive sprint workflow** skill designed for iterative project exe
 - **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
+- **Persists context cheaply** — `state.json`, `index.json`, summaries, and re-entry prompts let new agents recover without rereading every Markdown file
 
 This skill works for **any** project type, language, or framework.
 
@@ -88,7 +88,7 @@ This skill works for **any** project type, language, or framework.
 
 > **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.
+> After INIT and after each executed sprint, update `state.json`, `index.json`, relevant `*.summary.json`, and re-entry prompts. Agents read structured state before opening long Markdown evidence.
 
 ---
 
@@ -100,6 +100,7 @@ This skill works for **any** project type, language, or framework.
 | Create vault structure | Yes | No | No |
 | Generate roadmap | Yes | No | No |
 | Generate/update re-entry prompts | Yes | Yes | No |
+| Update state/index/summaries | Yes | Yes | Yes |
 | Generate sprint | No | Yes | No |
 | Execute sprint tasks | No | Yes | No |
 | Write/modify code | No | Yes | No |
@@ -120,7 +121,7 @@ This skill works for **any** project type, language, or framework.
 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.
+The project state lives in `.agents/kyro/kyro.json`; scoped state lives in `.agents/kyro/scopes/{scope}/state.json` and `index.json`. Re-entry prompts and README remain human handoff aids, not startup requirements.
 
 ### Frontmatter Properties
 
@@ -148,9 +149,9 @@ After detecting the mode, read ONLY the assets listed for that mode. Do NOT read
 
 | 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 |
+| **INIT** | `INIT.md`, then one routed `helpers/analysis/{workType}.md` helper | SPRINT.md, STATUS.md, sprint-generator.md, debt-tracker.md, unrelated analysis helpers |
+| **SPRINT** | `SPRINT.md`, then exactly one routed mode: `plan-sprint.md`, `execute-task.md`, `review-task.md`, `close-sprint.md`, or `recover.md` | INIT.md, STATUS.md, unrelated modes/helpers/templates |
+| **STATUS** | `STATUS.md`, `debt-tracker.md` | INIT.md, SPRINT.md, analysis helpers, sprint-generator.md, reentry-generator.md, all templates |
 
 **On-demand assets**: Templates are loaded as each workflow step references them, not upfront.
 
@@ -184,9 +185,9 @@ 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.
+This will: read structured state first, route to planning or execution, and load only the mode/helper files needed for the current step.
 
-**Full workflow:** See [assets/modes/SPRINT.md](assets/modes/SPRINT.md)
+**Router:** See [assets/modes/SPRINT.md](assets/modes/SPRINT.md)
 
 ### STATUS Mode
 
@@ -196,7 +197,7 @@ 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.
+This will: read summaries first, calculate metrics, and open Markdown only when summaries are missing or a full report requires evidence.
 
 **Full workflow:** See [assets/modes/STATUS.md](assets/modes/STATUS.md)
 

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

@@ -1,31 +1,52 @@
 # Kyro — Assets
 
-This directory contains the modular components of the `kyro-ai` skill.
+Kyro assets are designed for progressive disclosure: load the router first, then only the mode/helper/template needed for the current action.
 
-## Directory Structure
-
-### modes/ (3 files)
+## modes/
 
 | 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 |
+| [INIT.md](modes/INIT.md) | Lean analysis, justified sprint sizing, roadmap, scoped state, and summaries |
+| [SPRINT.md](modes/SPRINT.md) | Lightweight sprint router |
+| [plan-sprint.md](modes/plan-sprint.md) | Generate the next sprint |
+| [execute-task.md](modes/execute-task.md) | Execute active sprint tasks |
+| [review-task.md](modes/review-task.md) | Validate task or phase quality |
+| [close-sprint.md](modes/close-sprint.md) | Retro, debt, summaries, and re-entry closeout |
+| [recover.md](modes/recover.md) | Rebuild state/summaries after interruption |
+| [STATUS.md](modes/STATUS.md) | Summary-first progress reporting |
 
-### helpers/ (4 files)
+## helpers/
 
 | 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 |
+| [analysis/feature.md](helpers/analysis/feature.md) | Feature analysis and sizing signals |
+| [analysis/bugfix.md](helpers/analysis/bugfix.md) | Bugfix analysis and sizing signals |
+| [analysis/audit.md](helpers/analysis/audit.md) | Audit analysis and sizing signals |
+| [analysis/refactor.md](helpers/analysis/refactor.md) | Refactor analysis and sizing signals |
+| [analysis/new-project.md](helpers/analysis/new-project.md) | New project analysis and sizing signals |
+| [analysis/tech-debt.md](helpers/analysis/tech-debt.md) | Tech debt analysis and sizing signals |
+| [sprint-generator.md](helpers/sprint-generator.md) | Sprint generation algorithm |
+| [debt-tracker.md](helpers/debt-tracker.md) | Accumulated debt rules |
+| [reentry-generator.md](helpers/reentry-generator.md) | Re-entry prompt updates |
+| [reviewer.md](helpers/reviewer.md) | Review classification |
+| [handoff.md](helpers/handoff.md) | Session handoff format |
+
+## templates/
 
-### templates/ (4 files)
+| File | Description |
+|------|-------------|
+| [ROADMAP.md](templates/ROADMAP.md) | Human roadmap evidence with sizingDecision |
+| [SPRINT.md](templates/SPRINT.md) | Human sprint evidence |
+| [PROJECT-README.md](templates/PROJECT-README.md) | Scope README |
+| [REENTRY-PROMPTS.md](templates/REENTRY-PROMPTS.md) | Summary-first recovery prompts |
+| [state.json](templates/state.json) | Scoped routing state |
+| [index.json](templates/index.json) | Fast agent routing index |
+| [ROADMAP.summary.json](templates/ROADMAP.summary.json) | Roadmap summary cache |
+| [SPRINT.summary.json](templates/SPRINT.summary.json) | Sprint summary cache |
+| [DEBT.summary.json](templates/DEBT.summary.json) | Debt summary cache |
+
+## fixtures/
 
 | 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 |
+| [subcommands-and-reports.sizingDecision.json](fixtures/subcommands-and-reports.sizingDecision.json) | Regression fixture proving 3 justified sprints can be valid |

package/skills/sprint-forge/assets/fixtures/subcommands-and-reports.sizingDecision.json

@@ -0,0 +1,17 @@
+{
+  "recommendedSprintCount": 3,
+  "riskLevel": "medium",
+  "rationale": "The work has a dependency chain: CLI subcommands first, metadata reading second, removal reporting third.",
+  "splitTriggers": [
+    "public CLI behavior change",
+    "shared metadata reader dependency",
+    "cleanup reporting depends on metadata reading"
+  ],
+  "whyNotFewer": "Combining all changes would mix CLI refactor, metadata parsing, formatting, and reporting behavior in one review unit.",
+  "whyNotMore": "No additional subsystem boundaries or migrations were found.",
+  "sprintProofs": [
+    "Sprint 1 proves CLI subcommand architecture without changing metadata behavior.",
+    "Sprint 2 proves metadata reading and formatting independently.",
+    "Sprint 3 proves cleanup reporting built on metadata reading."
+  ]
+}

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

@@ -0,0 +1,18 @@
+# Audit Analysis
+
+Use for broad quality, architecture, security, performance, or maintainability reviews.
+
+## Inspect
+
+1. Map entry points, package metadata, tests, and docs.
+2. Sample each major subsystem enough to identify real patterns.
+3. Let findings emerge from evidence; do not force a fixed checklist.
+4. Group findings by independent remediation area.
+
+## Findings
+
+Each finding needs severity, evidence, affected files, impact, and recommended remediation.
+
+## Sizing signals
+
+Audits commonly produce multiple sprints when findings affect independent subsystems or risk classes. Avoid over-splitting cosmetic issues that can be resolved together.

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/helpers/metrics.md

@@ -66,14 +66,14 @@ Score: 72/100 (Good)
 
 ## Data Sources
 
-- Sprint files: task counts, completion status, retro data
-- Debt tables: accumulated across all sprints
-- Roadmap: planned vs actual sprint scope
+- Sprint summaries first: task counts, completion status, retro highlights
+- Debt summary or latest debt table: accumulated debt state
+- Roadmap summary first, roadmap Markdown when summary is missing
 - Rules file: estimation adjustment rules
 
 ## Calculation
 
-Read all sprint files in `{output_kyro_dir}/phases/` and compute:
+Read `index.json` and available `*.summary.json` files first. Open sprint Markdown only for missing fields, then compute:
 
 1. Count tasks per sprint (total, completed, blocked, skipped, carry-over)
 2. Map debt items to source directories

package/skills/sprint-forge/assets/helpers/reentry-generator.md

@@ -22,10 +22,10 @@ Each re-entry prompt covers a specific scenario:
 
 | # | Scenario | When to Use | Key Context Needed |
 |---|----------|-------------|-------------------|
-| 1 | First Sprint | After INIT, before any sprint | README, ROADMAP, findings |
-| 2 | Sprint N (next) | After completing Sprint N-1 | README, ROADMAP, last sprint (retro + recommendations + debt), next finding |
-| 3 | Execute Sprint | Sprint generated but not executed | README, ROADMAP, current sprint file |
-| 4 | Status | Any time, for progress report | README, ROADMAP, all sprint files |
+| 1 | First Sprint | After INIT, before any sprint | state.json, index.json, roadmap summary, selected findings |
+| 2 | Sprint N (next) | After completing Sprint N-1 | state.json, index.json, last sprint summary, roadmap summary |
+| 3 | Execute Sprint | Sprint generated but not executed | state.json, index.json, current sprint summary |
+| 4 | Status | Any time, for progress report | state.json, index.json, summaries; Markdown only as fallback |
 
 ---
 

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

@@ -1,204 +1,72 @@
-# INIT Mode — Analysis, Roadmap & Scaffolding
+# INIT Mode — Lean Analysis, Roadmap & Scoped State
 
-This mode performs deep analysis of a project, generates findings, creates an adaptive roadmap, scaffolds the working directory, and generates re-entry prompts.
+Use INIT when a scope has no Kyro roadmap. Optimize for justified sprint boundaries, not fewer sprints.
 
----
+## Inputs
 
-## When This Mode Activates
+- User request and current repository path.
+- `.agents/kyro/kyro.json` if present.
+- One work-type helper under `../helpers/analysis/` after routing.
+- Templates only when writing their artifact.
 
-| EN Signals | ES Signals |
-|-----------|-----------|
-| "analyze", "audit", "start project", "create roadmap", "analyze codebase" | "analiza", "audita", "inicia proyecto", "crea roadmap", "analiza el codebase" |
+## Step 1 — Resolve scope
 
----
+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.
 
-## Prerequisites
+## Step 2 — Detect work type
 
-- Access to the codebase (local path or repository)
-- No previous kyro-ai work for this project (if resuming, use SPRINT or STATUS mode)
+Classify as `feature`, `bugfix`, `audit`, `refactor`, `new-project`, or `tech-debt`. Load only the matching helper:
 
----
-
-## Workflow
-
-### Step 1 — Detect Work Type
-
-Determine the type of work from the user's request:
-
-| Work Type | Signals |
-|-----------|---------|
-| Audit / Refactor | "analyze", "audit", "refactor", "review the codebase" |
-| New Feature | "add feature", "implement", "build" |
-| Bugfix | "fix", "broken", "error", "regression" |
-| New Project | "start from scratch", "new project", "create project" |
-| Tech Debt | "clean up", "deprecated", "reduce debt", "missing tests" |
-
-**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) for detailed guidance per work type.
-
-If the work type is ambiguous, ask the user:
-
-> "Is this an audit/refactor, a new feature, a bugfix, a new project, or tech debt cleanup?"
-
-### Step 2 — Resolve Configuration
-
-Gather or detect the following configuration:
-
-| Config | How to Resolve |
-|--------|---------------|
-| **Scope** | Ask the user. A short kebab-case name for the work topic (e.g., `oauth-implementation`, `ui-redesign`, `q2-growth`). NOT the repo name — the repo is already `{cwd}`. |
-| **Codebase Path** | The absolute path to the codebase. Usually the current working directory. |
-| **Sprint Output Dir** | `{output_kyro_dir}/phases/` (automatic, resolved below) |
-
-**Resolve `{output_kyro_dir}`** — ask the user:
-
-> "Where should I save kyro-ai documents for **{scope}**?
->
-> 1. **Default** (Recommended) — `.agents/kyro/scopes/{scope}/`
-> 2. **Custom path** — provide your preferred directory"
-
-Set `{output_kyro_dir}` based on the choice. This path will be embedded in `README.md` and `RE-ENTRY-PROMPTS.md` — those are the only sources of truth. No other persistence needed.
-
-Confirm with the user:
-
-> **Scope**: {scope}
-> **Codebase**: `{codebase_path}`
-> **Output**: `{output_kyro_dir}`
->
-> Proceed with this configuration?
-
-### Step 3 — Deep Analysis
-
-Perform thorough analysis based on the work type. This is the most critical step.
-
-**Strategy**:
-1. Use the **Explore agent** (Task tool with subagent_type=Explore) for broad codebase exploration
-2. Use **Glob** to find files by pattern
-3. Use **Grep** to search for specific patterns
-4. Use **Read** to examine specific files in detail
-
-**Analysis depth depends on work type**:
-- **Audit/Refactor**: Explore the entire codebase. Every directory, every major file. Identify all areas of concern.
-- **New Feature**: Focus on the integration points. Understand what exists and what gaps need filling.
-- **Bugfix**: Trace the bug path. Reproduce, identify root cause, assess blast radius.
-- **New Project**: Research requirements, comparable solutions, stack decisions.
-- **Tech Debt**: Scan for debt indicators across the codebase.
-
-**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) for the complete analysis strategy.
-
-**Key Principle**: The analysis determines the structure. Do NOT start with a fixed list of categories. Let the project tell you what matters.
-
-### Step 4 — Generate Findings
-
-Write each distinct finding as a separate file:
-
-**Location**: `{output_kyro_dir}/findings/`
-
-**Naming**: `NN-descriptive-slug.md` (e.g., `01-architecture-issues.md`)
-
-**Content per file**: YAML frontmatter properties (following the template in analysis-guide.md) + Summary, severity, details with code examples, affected files, recommendations.
-
-**Number of findings**: VARIABLE. Determined entirely by what the analysis reveals:
-- Small project: 2-4 findings
-- Medium refactor: 5-8 findings
-- Major audit: 10-20+ findings
-
-**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) → Step 3 for the finding file format.
+```text
+../helpers/analysis/{workType}.md
+```
 
-### Step 5 — Create Roadmap
+## Step 3 — Analyze
 
-Using the [ROADMAP.md template](../templates/ROADMAP.md), create the adaptive roadmap:
+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.
 
-1. Fill in project paths (codebase, output dir, findings, phases)
-2. Map each finding to a suggested sprint:
-   - Finding 01 → Sprint 1 (usually, but not always)
-   - Related findings may be grouped into a single sprint
-   - Large findings may be split across multiple sprints
-3. Define sprint dependencies (which sprints must complete before others)
-4. For each sprint, define:
-   - Title and focus
-   - Source finding file(s)
-   - Version target (if applicable)
-   - Type (audit/refactor/feature/bugfix/debt)
-   - Suggested phases (2-5 phases per sprint)
-5. Fill in the Sprint Summary table
-6. Write the dependency map
+## Step 4 — Write findings
 
-**Location**: `{output_kyro_dir}/ROADMAP.md`
+Write each distinct finding to `{outputDir}/findings/NN-descriptive-slug.md` with summary, severity, affected files, details, recommendation, and validation.
 
-### Step 6 — Scaffold Working Directory
+## Step 5 — Decide sprint sizing
 
-Create the full directory structure:
+Before writing the roadmap, produce `sizingDecision`:
 
-```
-{output_kyro_dir}/
-├── README.md              ← From PROJECT-README.md template
-├── ROADMAP.md             ← Created in Step 5
-├── RE-ENTRY-PROMPTS.md    ← Created in Step 7
-├── findings/              ← Created in Step 4
-│   ├── 01-*.md
-│   ├── 02-*.md
-│   └── ...
-└── phases/               ← Empty directory, sprints created later
+```json
+{
+  "recommendedSprintCount": 1,
+  "riskLevel": "low | medium | high",
+  "rationale": "...",
+  "splitTriggers": [],
+  "whyNotFewer": "...",
+  "whyNotMore": "...",
+  "sprintProofs": []
+}
 ```
 
-**README.md**: Use the [PROJECT-README.md template](../templates/PROJECT-README.md). Fill in the frontmatter properties with actual values, then fill in:
-- Project name, type, date
-- Description of the work
-- All absolute paths
-- Baseline metrics (if applicable)
-- Initial sprint map from the roadmap
+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 7 — Generate Re-entry Prompts
+## Step 6 — Write artifacts
 
-Using the [reentry-generator.md](../helpers/reentry-generator.md) helper:
+Load templates only when writing:
 
-1. Use the [REENTRY-PROMPTS.md template](../templates/REENTRY-PROMPTS.md)
-2. Fill in all template variables with actual values:
-   - `{scope}`, `{codebase_path}`, `{output_kyro_dir}`
-   - `{current_sprint}` = 1 (no sprints yet)
-   - Sprint 1 finding file path
-3. Generate all 4 scenario prompts with real paths
-4. Write to `{output_kyro_dir}/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.
 
-## Output Summary
-
-At the end of INIT, present a summary:
-
-```
-## INIT Complete
-
-**Scope**: {scope}
-**Type**: {work_type}
-**Findings**: {N} files in findings/
-**Sprints Planned**: {M} sprints in roadmap
-**Files Created**:
-  - {output_kyro_dir}/README.md
-  - {output_kyro_dir}/ROADMAP.md
-  - {output_kyro_dir}/RE-ENTRY-PROMPTS.md
-  - {output_kyro_dir}/findings/01-{slug}.md
-  - {output_kyro_dir}/findings/02-{slug}.md
-  - ...
-
-**Next Step**: Generate Sprint 1 using `/kyro:forge` or copy the re-entry prompt from RE-ENTRY-PROMPTS.md → Scenario 1.
-```
+Create `{outputDir}/phases/` empty.
 
----
+## Step 7 — Write structured routing files
 
-## Error Handling
+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.
 
-| Error | Action |
-|-------|--------|
-| Codebase path not found | Ask user for the correct path |
-| Output directory already exists | Ask user: overwrite, use different name, or resume |
-| No meaningful findings | Inform user — the codebase may be in good shape. Generate a minimal roadmap with maintenance sprints. |
-| Analysis scope too large | Break into phases. Analyze the most critical areas first, note others as "needs deeper analysis" finding. |
+## Output
 
----
+Report scope, work type, finding count, sprint count, sizing rationale, files created, and next action: run `kyro-forge` to plan Sprint 1.
 
-## References
+## Rules
 
-- [analysis-guide.md](../helpers/analysis-guide.md) — Analysis strategy per work type
-- [ROADMAP.md template](../templates/ROADMAP.md) — Roadmap structure
-- [PROJECT-README.md template](../templates/PROJECT-README.md) — Project README structure
-- [REENTRY-PROMPTS.md template](../templates/REENTRY-PROMPTS.md) — Re-entry prompts structure
-- [reentry-generator.md](../helpers/reentry-generator.md) — How to generate re-entry prompts
+- `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, execution modes, or unrelated analysis helpers during INIT.