kyro-ai 3.2.0

package/skills/sprint-forge/assets/helpers/debt-tracker.md

@@ -0,0 +1,122 @@
+# Debt Tracker
+
+This helper defines the rules for the Accumulated Technical Debt table that persists across sprints.
+
+---
+
+## Core Principle
+
+> **Debt never disappears.** The debt table is a living ledger that grows as new debt is discovered and shrinks only when debt is explicitly resolved. It is never pruned, never reset, never "cleaned up."
+
+---
+
+## Table Format
+
+The debt table appears in every sprint file, starting from Sprint 1:
+
+| # | Item | Origin | Sprint Target | Status | Resolved In |
+|---|------|--------|--------------|--------|-------------|
+| 1 | Brief description of debt item | Where it was discovered | Sprint N | open | — |
+
+### Column Definitions
+
+| Column | Description |
+|--------|-------------|
+| **#** | Sequential number. Never reused, even if the item is resolved. New items get the next available number. |
+| **Item** | Brief, clear description of the debt. Specific enough to act on. |
+| **Origin** | Where and when the debt was discovered. Format: `Sprint {N} Phase {X}`, `INIT finding {NN}`, or `Sprint {N} retro`. |
+| **Sprint Target** | Which sprint is expected to resolve this item. Updated if deferred. |
+| **Status** | Current state: `open`, `in-progress`, `resolved`, `deferred`. |
+| **Resolved In** | Sprint number where the item was actually resolved. Empty (`—`) if not yet resolved. |
+
+---
+
+## Status Transitions
+
+```
+open → in-progress → resolved
+  ↓
+deferred → open → in-progress → resolved
+```
+
+- **open**: Known but not yet being worked on
+- **in-progress**: Actively being addressed in the current sprint
+- **resolved**: Fixed and verified. Record the sprint number.
+- **deferred**: Postponed to a later sprint. Requires justification.
+
+---
+
+## Inheritance Rules
+
+1. **Sprint 1**: The debt table starts with items discovered during INIT analysis (if any) or is empty.
+2. **Sprint N (N > 1)**: Copy the ENTIRE debt table from Sprint N-1. Do not omit resolved items — they remain as history.
+3. **Add new items**: Append at the bottom with the next available number.
+4. **Never delete rows**: Even resolved items stay in the table. The table is a complete history.
+5. **Preserve original numbers**: Item #3 is always Item #3, regardless of how many sprints pass.
+
+---
+
+## Adding New Debt
+
+New debt can be discovered at any point:
+
+- **During INIT analysis**: Origin = `INIT finding {NN}`
+- **During sprint generation**: Origin = `Sprint {N} generation` (from recommendations or roadmap analysis)
+- **During sprint execution**: Origin = `Sprint {N} Phase {X}` (specific phase where discovered)
+- **During sprint retro**: Origin = `Sprint {N} retro`
+
+When adding a new item:
+1. Use the next available number
+2. Set Status = `open`
+3. Set Sprint Target = best estimate of when it should be addressed
+4. Leave Resolved In empty (`—`)
+
+---
+
+## Closing Debt
+
+When a debt item is resolved during a sprint:
+
+1. Change Status to `resolved`
+2. Fill Resolved In with the current sprint number
+3. Optionally add a brief note: `Sprint 3 (migrated to new API)`
+
+---
+
+## Deferring Debt
+
+When a debt item cannot be addressed in its target sprint:
+
+1. Change Status to `deferred`
+2. Update Sprint Target to the new expected sprint
+3. Add justification — either inline or as a footnote:
+   - Inline: `deferred (blocked by external API release)`
+   - Footnote: `deferred [^1]` with `[^1]: Blocked by external API release, expected Sprint 5`
+
+**Rule**: Deferral must be justified. "Not enough time" is acceptable only with specifics (e.g., "sprint scope expanded due to emergent phase, deferring to Sprint 4").
+
+---
+
+## Reporting
+
+The STATUS mode uses the debt table for reporting:
+
+- **Open count**: Items with status `open` or `in-progress`
+- **Resolved count**: Items with status `resolved`
+- **Deferred count**: Items with status `deferred`
+- **Debt trend**: Is the open count growing or shrinking sprint over sprint?
+- **Oldest open items**: Items that have been open the longest (potential chronic debt)
+
+---
+
+## Example
+
+Sprint 3's debt table, showing history from sprints 1-3:
+
+| # | Item | Origin | Sprint Target | Status | Resolved In |
+|---|------|--------|--------------|--------|-------------|
+| 1 | Missing unit tests for auth module | INIT finding 02 | Sprint 2 | resolved | Sprint 2 |
+| 2 | Deprecated API calls in data layer | INIT finding 03 | Sprint 3 | in-progress | — |
+| 3 | Inconsistent error handling in controllers | Sprint 1 Phase 2 | Sprint 3 | open | — |
+| 4 | No input validation on user forms | Sprint 2 retro | Sprint 4 | deferred | — |
+| 5 | Circular dependency between modules A and B | Sprint 3 Phase 1 | Sprint 4 | open | — |

package/skills/sprint-forge/assets/helpers/handoff.md

@@ -0,0 +1,103 @@
+# Sprint Handoff — Enriched Context Transfer
+
+## Purpose
+
+Generates a handoff document that captures not just file state but **mental context** — the hypotheses, decisions, and reasoning that a new session needs to continue effectively.
+
+## Handoff Structure
+
+### 1. Sprint State
+
+```text
+## Sprint State
+- Active sprint: Sprint 3 (in progress)
+- Tasks completed: 5/8
+- Current task: T2.3 — "Implement rate limiting middleware"
+- Phase: 2 of 3
+- Last checkpoint: Phase 2 complete
+```
+
+### 2. Mental Context
+
+#### Active Hypotheses
+
+Ideas being investigated but not yet confirmed:
+
+```text
+### Active Hypotheses
+- "The performance issue in /api/users is likely an N+1 query at line 47 of userService.ts"
+- "The auth module may have a race condition under concurrent login attempts"
+- "The memory spike during CSV export correlates with unbounded stream buffering"
+```
+
+#### Pending Decisions
+
+Choices that need to be made before proceeding:
+
+```text
+### Pending Decisions
+- Redis vs in-memory cache backend (waiting for load test results)
+- Migrate to new payments API now or defer to Sprint 5 (cost-benefit unclear)
+- Monorepo restructure: packages/ or apps/ pattern?
+```
+
+#### Identified Blockers
+
+Things that are preventing progress:
+
+```text
+### Identified Blockers
+- Infra team hasn't provisioned staging environment (ETA unknown)
+- Payments API documentation is outdated (v2 docs reference v1 endpoints)
+- CI pipeline intermittent failures (flaky test in auth.spec.ts:142)
+```
+
+### 3. Recommended Next Action
+
+The single most important thing to do when resuming:
+
+```text
+### Next Action
+1. Check if infra provisioned staging (ask in #infra channel)
+2. If yes → run integration test suite against staging
+3. If no → continue with non-blocked tasks: T3.1 (UI polish), T3.2 (error messages)
+```
+
+### 4. Corrections & Rules This Session
+
+```text
+### Corrections Applied
+- User corrected: "Always use parameterized queries, never string concatenation"
+  → Saved as RULE-012
+
+### Rules Triggered
+- RULE-005: Added 20% buffer to DB migration estimate (Sprint 3, T1.2)
+```
+
+### 5. Files Context
+
+```text
+### Key Files
+- src/middleware/rate-limit.ts — work in progress, half-implemented
+- src/services/userService.ts:47 — suspected N+1 query
+- tests/auth.spec.ts:142 — flaky test causing CI failures
+```
+
+## Generation
+
+When generating a handoff:
+1. Read current sprint file for task state
+2. Review conversation for hypotheses and decisions
+3. Check git status for uncommitted work
+4. Check rules applied/proposed this session
+5. Write to `{output_kyro_dir}/handoffs/[date]-sprint-[N].md`
+6. Update re-entry prompts with handoff reference
+
+## Difference from Re-entry Prompts
+
+| Aspect | Re-entry Prompts | Handoff |
+|--------|-----------------|---------|
+| Focus | File paths and sprint state | Mental context and reasoning |
+| When | After INIT and each sprint | Any time during execution |
+| For whom | Any agent, any session | Specifically the next session |
+| Content | What to read | What to think about |

package/skills/sprint-forge/assets/helpers/learner.md

@@ -0,0 +1,69 @@
+# Kyro Learner — Per-Project Rule Accumulation
+
+## Purpose
+
+Captures corrections, patterns, and estimation insights as persistent rules stored in `.agents/kyro/scopes/rules.md`. These rules are project-scoped and accumulated across sprints.
+
+## Rule Format
+
+```markdown
+# Kyro — Learned Rules
+
+## Estimation
+- [RULE-001] DB migration tasks: add 20% buffer to estimates (2026-02-20, project: nebux-api)
+- [RULE-002] Auth tasks frequently reveal hidden dependencies (2026-02-22, project: nebux-api)
+
+## Quality
+- [RULE-003] Always validate version compatibility before adding dependencies (2026-02-25, project: synap-sync)
+
+## Architecture
+- [RULE-004] Extract shared validation logic before 3rd duplication (2026-03-01, project: skills-registry)
+
+## Testing
+- [RULE-005] E2E tests for auth flows catch integration issues that unit tests miss (2026-03-03, project: nebux-api)
+
+## Process
+- [RULE-006] Run full quality gates before closing sprint, not just per-task (2026-03-05, project: synap-sync)
+```
+
+## Capture Flow
+
+When the user corrects the agent or a pattern is identified:
+
+1. Detect the correction or pattern
+2. Propose the rule in standard format:
+
+```text
+Detected a pattern worth remembering:
+
+[RULE-XXX] Category: One-line rule
+  Context: Why this rule exists
+  Source: Sprint N, Project: project-name
+
+Save this rule? (yes/no/edit)
+```
+
+3. On approval, append to `.agents/kyro/scopes/rules.md`
+4. Log in the sprint's LEARNED section
+
+## Rule Application
+
+At the start of every session:
+1. Load `.agents/kyro/scopes/rules.md`
+2. Before generating sprint estimates, check estimation rules
+3. Before architecture decisions, check architecture rules
+4. If about to violate a rule, pause and show it (RuleViolation event)
+
+## Rule Lifecycle
+
+- **Active** — Applied automatically in relevant contexts
+- **Deprecated** — User marks as no longer relevant (kept for history)
+- **Evolved** — Updated rule replaces a previous version (link to original)
+
+## Rules About Rules
+
+- Never add duplicate rules. Check existing rules before proposing.
+- Rules must be specific and actionable, not vague platitudes.
+- Include the date and project where the rule was learned.
+- Rules from corrections have higher confidence than proactive suggestions.
+- Maximum 50 active rules. After that, consolidate or deprecate.

package/skills/sprint-forge/assets/helpers/metrics.md

@@ -0,0 +1,81 @@
+# Kyro Metrics — Velocity & Debt Analytics
+
+## Purpose
+
+Provides quantitative analysis of sprint execution history to identify patterns, improve estimation accuracy, and visualize technical debt distribution.
+
+## Metrics
+
+### Velocity Trend
+
+Track completion rate per sprint:
+
+```text
+## Velocity Trend
+Sprint 1: ████████░░  8/10 tasks (80%)
+Sprint 2: ██████████ 10/10 tasks (100%)
+Sprint 3: ███████░░░  7/10 tasks (70%) ← underperformance: DB tasks x2
+Sprint 4: █████████░  9/10 tasks (90%)
+
+Average velocity: 85%
+Trend: stable (±10%)
+```
+
+### Debt Heatmap
+
+Show debt concentration by directory/module:
+
+```text
+## Debt Heatmap
+src/auth/    ████████ 4 items (2 critical, aged: 3 sprints)
+src/db/      █████░░░ 3 items (1 critical)
+src/api/     ██░░░░░░ 1 item
+src/ui/      ░░░░░░░░ 0 items
+
+Total: 8 items (3 critical, 2 aged >3 sprints)
+```
+
+### Underestimation Patterns
+
+Identify task types that are consistently underestimated:
+
+```text
+## Underestimation Patterns
+- DB/migration tasks: underestimated by ~40% (3 occurrences)
+- Auth tasks: reveal hidden dependencies in 67% of cases
+- UI tasks: generally accurate (±10%)
+- API tasks: underestimated by ~15% when involving auth
+```
+
+### Sprint Health Score
+
+Composite score based on:
+- Velocity (weight: 30%)
+- Debt trend — increasing or decreasing (weight: 25%)
+- Carry-over count (weight: 20%)
+- Estimation accuracy (weight: 25%)
+
+```text
+## Sprint Health
+Score: 72/100 (Good)
+  Velocity:    ████████░░ 85% (25.5/30)
+  Debt trend:  ██████░░░░ ↗ increasing (15/25)
+  Carry-over:  ████████░░ 2 tasks (16/20)
+  Estimation:  ██████░░░░ ±25% avg error (15.5/25)
+```
+
+## Data Sources
+
+- Sprint files: task counts, completion status, retro data
+- Debt tables: accumulated across all sprints
+- Roadmap: planned vs actual sprint scope
+- Rules file: estimation adjustment rules
+
+## Calculation
+
+Read all sprint files in `{output_kyro_dir}/phases/` and compute:
+
+1. Count tasks per sprint (total, completed, blocked, skipped, carry-over)
+2. Map debt items to source directories
+3. Track item age (sprint introduced vs current sprint)
+4. Compare planned phases vs actual phases (including emergent)

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

@@ -0,0 +1,121 @@
+# Re-entry Generator
+
+This helper defines how to generate and update re-entry prompts that allow context recovery across sessions.
+
+---
+
+## What Are Re-entry Prompts
+
+Re-entry prompts are pre-written instructions that a new agent (or the same agent in a new session) can use to recover full project context. They specify:
+
+- Which files to read and in what order
+- What the current state of the project is
+- What action to take next
+
+They are the **context persistence mechanism** of Kyro.
+
+---
+
+## 4 Scenarios
+
+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 |
+
+---
+
+## Prompt Structure
+
+Each prompt must include:
+
+1. **Project identifier**: Name and brief description
+2. **Files to read**: Ordered list of files with absolute paths
+3. **Current state**: What sprint is current, what's been done
+4. **Action**: What the agent should do (invoke `/kyro:forge` with specific intent)
+5. **Key notes**: Any important context (e.g., "Sprint 3 had a blocked task")
+
+---
+
+## Template Variables
+
+The following variables are filled with actual values during INIT and updated after each sprint:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{scope}` | Work scope (kebab-case topic) | `nebux-design-system-audit` |
+| `{codebase_path}` | Absolute path to the codebase | `/Users/dev/projects/nebux` |
+| `{output_kyro_dir}` | Working directory for sprint artifacts | `/Users/dev/projects/nebux/.agents/kyro/scopes/nebux-design-system-audit` |
+| `{current_sprint}` | Current sprint number | `3` |
+| `{last_sprint_file}` | Filename of the last completed sprint | `SPRINT-2-api-surface.md` |
+| `{next_finding_file}` | Finding file for the next sprint | `03-component-quality.md` |
+| `{latest_sprint_file}` | Filename of the latest sprint (may be in-progress) | `SPRINT-3-component-quality.md` |
+
+---
+
+## When to Generate
+
+### After INIT
+
+Generate ALL 4 prompts with:
+- Actual project paths (codebase, output dir)
+- Sprint 1 as the current/next sprint
+- Finding file 01 as the first finding
+- Write to `{output_kyro_dir}/RE-ENTRY-PROMPTS.md`
+
+### After Each Sprint Execution
+
+Update prompts 2, 3, and 4:
+- Increment current sprint number
+- Update last sprint file reference
+- Update next finding file reference
+- Update any paths that may have changed
+- Update Quick Reference table with new sprint status
+
+Prompt 1 (First Sprint) can be left as-is or marked as "N/A — Sprint 1 already completed."
+
+---
+
+## Generation Process
+
+1. Read the `REENTRY-PROMPTS.md` template from `assets/templates/`
+2. Fill in all template variables with actual values
+3. Write to `{output_kyro_dir}/RE-ENTRY-PROMPTS.md`
+
+For updates (after sprint execution):
+1. Read the existing `RE-ENTRY-PROMPTS.md`
+2. Update the relevant sections with new values
+3. Update the Quick Reference table
+4. Update the "Last updated" date
+5. Write back
+
+---
+
+## Quick Reference Table
+
+The re-entry prompts file includes a quick reference table that maps sprints to files:
+
+| Sprint | File | Status |
+|--------|------|--------|
+| 1 | `phases/SPRINT-1-architecture.md` | completed |
+| 2 | `phases/SPRINT-2-api-surface.md` | completed |
+| 3 | `phases/SPRINT-3-components.md` | in-progress |
+| 4 | (not yet generated) | pending |
+
+This table is updated after each sprint execution.
+
+---
+
+## Validation
+
+After generating or updating re-entry prompts, verify:
+
+- [ ] All file paths are absolute and correct
+- [ ] Current sprint number matches reality
+- [ ] Last sprint file exists at the specified path
+- [ ] Quick Reference table matches actual sprint files
+- [ ] Each scenario prompt has complete file read instructions

package/skills/sprint-forge/assets/helpers/reviewer.md

@@ -0,0 +1,71 @@
+# Kyro Reviewer — Task Quality Validation
+
+## Purpose
+
+Provides a structured quality checklist that runs after each sprint task completes. Tasks cannot be marked as done until all BLOCKER items pass.
+
+## Checklist Tiers
+
+### BLOCKER (must pass — blocks task closure)
+
+1. **Tests pass** — all related tests run successfully
+2. **Type safety** — no typecheck errors introduced
+3. **No debug artifacts** — no console.log, debugger, print statements in production code
+4. **No secrets** — no hardcoded API keys, passwords, tokens, or credentials
+5. **No broken imports** — all imports resolve correctly
+
+### WARNING (should pass — requires justification to skip)
+
+1. **Test coverage** — new code has test coverage
+2. **Documentation** — non-obvious logic has inline comments
+3. **Debt tracking** — technical debt table updated if new debt introduced
+4. **Performance** — no visible performance regressions (O(n^2) loops, unbounded queries)
+
+### SUGGESTION (noted for retro — doesn't block)
+
+1. **Conventions** — code follows project patterns and naming conventions
+2. **Refactoring opportunities** — visible DRY violations or simplification opportunities
+3. **Documentation updates** — related docs should be updated
+
+## Validation Commands
+
+The orchestrator uses these commands during the review step to validate (adapt to project stack):
+
+```bash
+# Typecheck
+npm run typecheck
+# or: mypy, go vet
+
+# Build
+npm run build
+
+# Tests and lint
+# Run the target project's configured test/lint commands when they exist.
+# Examples: pytest, go test, dart test, flutter test, ruff, golangci-lint
+
+# Debug artifacts
+grep -rn "console\.log\|debugger\|print(" src/ --include="*.ts" --include="*.tsx"
+
+# Secrets
+grep -rn "apikey\|api_key\|secret\|password\|token" src/ --include="*.ts" -i
+```
+
+## Output Format
+
+```text
+REVIEW: Task T{phase}.{task} — "{task title}"
+
+BLOCKERS:          [0 found / N found]
+  ✓ Tests passing
+  ✓ Type safety
+  ✗ Debug artifact: console.log at src/auth/login.ts:42
+
+WARNINGS:          [0 found / N found]
+  ✓ Test coverage
+  ⚠ Missing documentation for validateToken()
+
+SUGGESTIONS:       [0 found / N found]
+  → Consider extracting email validation to shared util
+
+VERDICT: PASS / FAIL (N blockers) / PASS WITH WARNINGS (N)
+```