kyro-ai 3.2.0 → 3.2.2

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

@@ -1,204 +1,103 @@
-# INIT Mode — Analysis, Roadmap & Scaffolding
+# INIT Mode — 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 yet. INIT creates human-readable evidence plus structured routing files so future commands do not reread everything.
 
----
+## Inputs
 
-## When This Mode Activates
+- User request and current repository path.
+- `.agents/kyro/kyro.json` if present.
+- `../helpers/analysis-guide.md` for analysis strategy.
+- 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:
 
-## Prerequisites
+| Field | Rule |
+|-------|------|
+| scope | Short kebab-case work topic, not the repo name. |
+| codebasePath | Usually current working directory. |
+| outputDir | Default `.agents/kyro/scopes/{scope}/`. |
 
-- Access to the codebase (local path or repository)
-- No previous kyro-ai work for this project (if resuming, use SPRINT or STATUS mode)
+If scope or output directory is ambiguous, ask once. Then create the scoped directory structure.
 
----
+## Step 2 — Detect work type
 
-## Workflow
+Classify the request as audit/refactor, feature, bugfix, new project, or tech debt. If unclear, ask before analysis.
 
-### Step 1 — Detect Work Type
+## Step 3 — Analyze
 
-Determine the type of work from the user's request:
+Use project search/read tools to inspect only what the work type requires:
 
-| 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" |
+- 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.
 
-**Reference**: See [analysis-guide.md](../helpers/analysis-guide.md) for detailed guidance per work type.
+Let evidence determine findings. Do not force a fixed category list.
 
-If the work type is ambiguous, ask the user:
+## Step 4 — Write findings
 
-> "Is this an audit/refactor, a new feature, a bugfix, a new project, or tech debt cleanup?"
+Write each distinct finding to `{outputDir}/findings/NN-descriptive-slug.md`.
 
-### Step 2 — Resolve Configuration
+Each finding needs summary, severity, affected files, details, and recommendations. Use `analysis-guide.md` for the detailed format.
 
-Gather or detect the following configuration:
+## Step 5 — Write roadmap
 
-| 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) |
+Load `../templates/ROADMAP.md` only now. Write `{outputDir}/ROADMAP.md` with:
 
-**Resolve `{output_kyro_dir}`** — ask the user:
+- project paths
+- finding-to-sprint map
+- sprint dependencies
+- sprint title/focus/type/version target
+- suggested phases
+- sprint summary table
 
-> "Where should I save kyro-ai documents for **{scope}**?
->
-> 1. **Default** (Recommended) — `.agents/kyro/scopes/{scope}/`
-> 2. **Custom path** — provide your preferred directory"
+## Step 6 — Scaffold human artifacts
 
-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.
+Load templates only when writing:
 
-Confirm with the user:
+- `../templates/PROJECT-README.md` → `{outputDir}/README.md`
+- `../templates/REENTRY-PROMPTS.md` → `{outputDir}/RE-ENTRY-PROMPTS.md`
 
-> **Scope**: {scope}
-> **Codebase**: `{codebase_path}`
-> **Output**: `{output_kyro_dir}`
->
-> Proceed with this configuration?
+Create `{outputDir}/phases/` empty. Sprints are generated later.
 
-### Step 3 — Deep Analysis
+## Step 7 — Write structured routing files
 
-Perform thorough analysis based on the work type. This is the most critical step.
+Create:
 
-**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
+- `{outputDir}/state.json` from `../templates/state.json`
+- `{outputDir}/index.json` from `../templates/index.json`
+- `{outputDir}/ROADMAP.summary.json` from `../templates/ROADMAP.summary.json`
 
-**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.
+Initial values:
 
-**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.
-
-### Step 5 — Create Roadmap
-
-Using the [ROADMAP.md template](../templates/ROADMAP.md), create the adaptive roadmap:
-
-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
-
-**Location**: `{output_kyro_dir}/ROADMAP.md`
-
-### Step 6 — Scaffold Working Directory
-
-Create the full directory structure:
-
-```
-{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
-```
-
-**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
-
-### Step 7 — Generate Re-entry Prompts
-
-Using the [reentry-generator.md](../helpers/reentry-generator.md) helper:
-
-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`
-
-## 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.
+```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.
 
-## Error Handling
+## Output
 
-| 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. |
+Report:
 
----
+- scope
+- work type
+- number of findings
+- planned sprint count
+- files created
+- 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, or execution modes during INIT.
+- If the output directory already exists, ask whether to resume or choose a different scope.

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.