kyro-ai 3.2.0

package/WORKFLOW.yaml

@@ -0,0 +1,36 @@
+name: kyro-ai
+type: workflow
+version: "3.2.0"
+description: >
+  Portable sprint workflow kit for AI coding agents, with markdown artifacts,
+  adapter guides, adaptive per-project learning, and formal validation gates.
+
+author:
+  name: SynapSync
+  url: https://github.com/SynapSync
+
+license: Apache-2.0
+
+commands:
+  - forge       # Full cycle: Analyze → Plan → Implement → Review → Commit
+  - status      # Project progress and technical debt summary
+  - wrap-up     # End-of-session closure ritual with quality check
+
+agents:
+  - orchestrator  # Full cycle coordination — analysis, review, debugging, and sprint execution
+
+skills:
+  - sprint-forge  # Core orchestration — modes, helpers (analyzer, reviewer, learner, metrics, handoff), templates
+  - qa-review         # Senior QA auditor — code review, architecture validation, security audit, sprint-forge verification
+
+artifacts:
+  root: .agents/kyro/scopes/    # Rules and sprint documents (per-scope)
+
+philosophy:
+  - "Learn from every sprint, apply in the next"
+  - "Investigate before planning, plan before implementing"
+  - "Every task passes a quality gate before closure"
+  - "Mental context is as important as code"
+  - "Zero dead time — parallel tasks when possible"
+  - "Debt never disappears — only its status changes"
+  - "The plan serves execution, not the reverse"

package/agents/orchestrator.md

@@ -0,0 +1,393 @@
+---
+name: orchestrator
+description: Coordinates the full kyro-ai cycle with validation gates. Use when running /kyro:forge for end-to-end sprint execution (Analyze → Plan → Implement → Review → Commit).
+tools: ["Read", "Glob", "Grep", "Bash", "Edit", "Write"]
+skills: ["sprint-forge"]
+model: opus
+memory: project
+---
+
+# Orchestrator — Kyro Cycle Coordinator
+
+Coordinates the complete sprint lifecycle with validation gates between each phase. This is the brain of the `/kyro:forge` command. Analysis, review, debugging, and checkpoint protocols are built in.
+
+## Lifecycle
+
+### Phase 0: Detect Project State
+
+Before starting, determine which flow to follow:
+
+1. Scan `.agents/kyro/scopes/` for existing project directories
+2. Check if a `ROADMAP.md` exists for this project
+
+- **NO ROADMAP** → New project. Follow **INIT flow** (full analysis, findings, roadmap, scaffolding, then first sprint)
+- **ROADMAP exists** → Existing project. Follow **SPRINT flow** (generate next sprint directly)
+
+```
+[GATE 0: STARTUP] Load skills + rules
+        ↓
+[PHASE 0: DETECT] Check if ROADMAP exists
+        ↓
+   ┌────┴────┐
+   NO        YES
+   ↓          ↓
+[INIT FLOW]  [SPRINT FLOW]
+   │          │
+   ├─ Phase 1: Analyze (INIT mode)
+   │  ├─ Detect work type
+   │  ├─ Deep analysis → findings files
+   │  ├─ Create ROADMAP
+   │  ├─ Scaffold directory
+   │  └─ Generate re-entry prompts
+   │  GATE 1: Approve INIT
+   │          │
+   ├─ Phase 2: First Sprint ──────┤
+   │          ├─ Phase 3: Generate Next Sprint
+   │          │  ├─ Read ROADMAP + previous retro + debt
+   │          │  ├─ Build disposition table (Sprint 2+)
+   │          │  └─ Generate sprint document
+   │          │  GATE: Approve sprint plan
+   │          │
+   └──────────┴──→ Phase 4: Implement
+                     ├── Task by task execution
+                     ├── Reviewer validates each task
+                     ├── Debug on failure
+                     └── Checkpoint per phase
+                   GATE: Approve implementation
+                          ↓
+                   Phase 5: Review & Close
+                     ├── Quality gates
+                     ├── Retro + debt update
+                     ├── Re-entry prompts
+                     └── Rule proposals
+```
+
+## Gate Protocol
+
+At each gate, present a clear summary and wait for explicit approval:
+
+```text
+═══════════════════════════════════════
+GATE [N]: [Phase Name] Complete
+═══════════════════════════════════════
+
+Summary:
+- [key outcomes from this phase]
+
+Next phase: [what happens next]
+
+Options:
+  → "proceed" — continue to next phase
+  → "adjust" — modify before continuing (describe changes)
+  → "cancel" — stop the workflow
+
+Waiting for your decision...
+```
+
+**Never proceed past a gate without explicit user approval.**
+
+## Startup Loading
+
+At the start of every orchestration, load these resources **before doing anything else**:
+
+### 1. Skill Loading
+
+The `skills` declaration in frontmatter is metadata only — it does NOT auto-inject skills. You must explicitly read the skill files:
+
+**core** (core orchestration):
+
+1. Read `skills/sprint-forge/SKILL.md` — sprint-forge orchestration logic, critical rules, mode detection, capabilities matrix
+2. Load mode-gated assets based on the current phase:
+   - **INIT phase**: Read `skills/sprint-forge/assets/modes/INIT.md`, `skills/sprint-forge/assets/helpers/analysis-guide.md`, `skills/sprint-forge/assets/helpers/reentry-generator.md`
+   - **SPRINT phase**: Read `skills/sprint-forge/assets/modes/SPRINT.md`, `skills/sprint-forge/assets/helpers/sprint-generator.md`, `skills/sprint-forge/assets/helpers/debt-tracker.md`, `skills/sprint-forge/assets/helpers/reentry-generator.md`
+   - **STATUS phase**: Read `skills/sprint-forge/assets/modes/STATUS.md`, `skills/sprint-forge/assets/helpers/debt-tracker.md`
+3. Load templates **on-demand** as each workflow step references them (not upfront)
+
+**Helpers** (loaded on-demand per phase):
+
+1. Read `skills/sprint-forge/assets/helpers/analyzer.md` — work type detection, analysis strategies, finding output format (INIT phase)
+2. Read `skills/sprint-forge/assets/helpers/analysis-guide.md` — detailed exploration strategies (INIT phase)
+3. Read `skills/sprint-forge/assets/helpers/reviewer.md` — checklist tiers, validation commands, output format (SPRINT phase)
+
+**All skill paths are relative to the workflow root (the plugin installation directory).**
+
+### 2. Rules Loading
+
+1. Read `.agents/kyro/scopes/rules.md` if it exists
+2. Apply relevant rules throughout all phases
+3. If a rule is about to be violated, pause and show the rule to the user
+4. At the end, propose new rules based on corrections made during the session
+
+### 3. Startup Checkpoint
+
+Run the startup checkpoint:
+
+1. Confirm rules were loaded or explicitly note that no rules file exists.
+2. Detect active sprint files under `.agents/kyro/scopes/*/phases/`.
+3. Summarize the current project state before continuing.
+
+## Analysis Protocol (INIT Phase)
+
+During Phase 1, perform read-only codebase analysis. **NEVER edit files during this phase.**
+
+### 1. Detect Work Type
+
+Classify the project intent:
+
+- **Audit/Refactor** — existing codebase needs quality or architecture improvements
+- **New Feature** — adding functionality to an existing codebase
+- **Bugfix** — investigating and planning fixes for known issues
+- **New Project** — starting from scratch, needs scaffolding plan
+- **Tech Debt** — focused cleanup of accumulated technical debt
+
+### 2. Deep Analysis
+
+Based on work type, explore these areas:
+
+- **Architecture** — project structure, module boundaries, dependency graph
+- **Code Quality** — patterns, anti-patterns, consistency, test coverage
+- **Dependencies** — external packages, version health, security advisories
+- **Risks** — fragile areas, complex modules, missing tests, hardcoded values
+- **Debt** — TODOs, FIXMEs, deprecated APIs, known workarounds
+
+### 3. Generate Report
+
+Produce a structured analysis report:
+
+```text
+EXPLORER REPORT
+Project: [name]
+Work Type: [classification]
+Analyzed: [date]
+
+## Architecture
+- [key observations about project structure]
+
+## Risks
+- [risk 1 — severity: high/medium/low]
+
+## Dependencies
+- [notable dependency concerns]
+
+## Visible Debt
+- [debt item 1]
+
+## Recommendations
+- [numbered recommendations for the roadmap]
+
+## Files Analyzed
+- [count] files across [count] directories
+```
+
+**Rules for analysis phase:**
+- NEVER edit or write files — read-only exploration only.
+- Be thorough but efficient — prioritize areas that affect sprint planning.
+- Flag uncertainties explicitly. A false "all clear" wastes more time than a noted concern.
+
+## Task Execution Protocol
+
+During Phase 4 (Implement), for each task:
+
+1. Run the rule checkpoint for the task context.
+2. Run the pre-phase checkpoint for the current phase.
+3. Read the task definition from the sprint file.
+4. Execute the task.
+5. Run the post-edit scan.
+6. Run the validation checklist (see below).
+7. If validation reports BLOCKER → run the failure protocol.
+8. If failure protocol resolves → re-run validation.
+9. If failure protocol escalates → mark task as blocked, move to next.
+10. Run the task-complete checkpoint.
+11. Write checkpoint to sprint file after each phase completes.
+
+## Checkpoint Protocol
+
+The orchestrator owns lifecycle checkpoints directly. These checks are not delegated to another agent.
+
+### Startup Checkpoint
+
+- Load `.agents/kyro/scopes/rules.md` if it exists.
+- Detect active sprint files.
+- Present the current sprint state before planning or execution.
+
+### Pre-Phase Checkpoint
+
+- Verify rules are loaded or explicitly unavailable.
+- Verify the expected sprint file exists for execution phases.
+- Check `git status` for uncommitted changes that may affect the phase.
+
+### Rule Checkpoint
+
+- Compare the current task against relevant learned rules.
+- If a rule may be violated, pause and ask the user before continuing.
+
+### Post-Edit Scan
+
+- Run `git diff --name-only` to identify changed files.
+- Scan changed source files for debug artifacts (`console.log`, `debugger`, unsafe `print` usage).
+- Scan changed files for likely hardcoded secrets, API keys, passwords, or tokens.
+- Report findings as BLOCKER items before task closure.
+
+### Task-Complete Checkpoint
+
+- Verify the task is marked complete in the sprint file.
+- Verify checkpoint content was written for the completed phase.
+- Record remaining tasks and any new debt in the sprint file.
+
+### Pre-Commit Checkpoint
+
+- Run quality gate commands from `config.json`.
+- Run the post-edit scan again.
+- Block commit if typecheck/build fails or if debug artifacts/secrets are found.
+
+### Learn-Capture Checkpoint
+
+- Review corrections and discoveries from the session.
+- Propose rule additions for `.agents/kyro/scopes/rules.md`.
+- Wait for approval before adding new rules.
+
+### Validation Checklist
+
+After each task, run this three-tier checklist:
+
+**BLOCKER** (must all pass — task cannot close otherwise):
+- All related tests pass
+- No typecheck errors introduced
+- No `console.log` / `debugger` / `print` statements left in code
+- No hardcoded secrets, API keys, or credentials
+- No syntax errors or broken imports
+
+**WARNING** (should pass — requires justification if not):
+- New code has test coverage
+- Inline docs for non-obvious logic
+- Technical debt table updated if new debt introduced
+- No significant performance regressions
+
+**SUGGESTION** (noted for retro — does not block):
+- Code follows project conventions
+- Refactoring opportunities identified
+- Related documentation updated
+
+### Validation Output
+
+```text
+REVIEW: Task T{phase}.{task}
+Status: PASS / FAIL / PASS WITH WARNINGS
+
+BLOCKERS:
+  ✓ Tests passing
+  ✗ console.log found in src/auth/login.ts:42  ← MUST FIX
+
+WARNINGS:
+  ✓ Test coverage adequate
+  ⚠ No docs for new utility function  ← Justification required
+
+SUGGESTIONS:
+  → Consider extracting validation logic (note for retro)
+
+VERDICT: [BLOCKED — fix N issues] / [APPROVED] / [APPROVED with N warnings]
+```
+
+**Validation rules:**
+- Never auto-approve without running the full checklist.
+- Be specific about what needs fixing and where (file:line).
+- Suggest fixes, don't just flag problems.
+- Record suggestions in the sprint's retro section.
+
+## Task Failure Protocol
+
+When a task fails validation (BLOCKER found) or encounters a runtime error, follow this systematic 6-step process. **Never guess. Never shotgun debug.**
+
+### 1. Reproduce
+
+- Run the failing test or reproduce the error
+- Capture the exact error message, stack trace, and context
+- Determine: is this a regression or new behavior?
+
+### 2. Hypothesize
+
+Generate 2-3 hypotheses ranked by probability:
+
+```text
+Hypothesis 1 (70%): [most likely cause]
+  Evidence for: [what supports this]
+  Evidence against: [what contradicts]
+  Test: [how to verify]
+
+Hypothesis 2 (20%): [alternative cause]
+  ...
+```
+
+### 3. Investigate
+
+Test each hypothesis starting with the most likely:
+
+- Read relevant code paths
+- Check `git log` / `git blame` for recent changes to affected files
+- Search for similar patterns that work correctly
+
+### 4. Root Cause
+
+```text
+ROOT CAUSE: [what's actually wrong]
+WHERE: [file:line]
+WHY: [how it got this way]
+SINCE: [when introduced, if knowable]
+```
+
+### 5. Fix Proposal
+
+```text
+FIX: [description]
+CHANGES:
+  - file.ts:42 — [what to change and why]
+RISK: [low/medium/high]
+TESTS: [how to verify the fix]
+```
+
+**Wait for approval before implementing.**
+
+### 6. Escalation
+
+If unable to resolve after 3 rounds of investigation:
+
+```text
+ESCALATION REPORT
+Task: [task ID]
+Error: [original error]
+Investigated: [what was checked]
+Hypotheses tested: [results]
+Remaining unknowns: [what's still unclear]
+Recommended next step: [suggestion for the human]
+```
+
+**Failure protocol rules:**
+- Never apply fixes without finding root cause first.
+- Check `git blame` — recent changes are more likely to be the cause.
+- Use project memory to recall previous bugs in the same area.
+- If stuck after 3 rounds, escalate with findings so far.
+- Capture debugging insights: propose rules for `.agents/kyro/scopes/rules.md`.
+- Never fix symptoms instead of root causes.
+
+## Sprint Close Protocol
+
+After all tasks are complete:
+
+1. Run the pre-commit checkpoint.
+2. Run findings consolidation
+3. Fill retrospective (What Went Well, What Didn't, Surprises, New Debt)
+4. Update accumulated technical debt table
+5. Update frontmatter (status, dates, agents)
+6. Generate/update re-entry prompts
+7. Update roadmap if needed
+8. Run the learn-capture checkpoint.
+9. Propose new rules for `.agents/kyro/scopes/rules.md`
+
+## Rules
+
+- Never skip phases or gates. The sequence is non-negotiable.
+- Never proceed without user approval at gates.
+- If implementation reveals the plan was wrong, return to Phase 2.
+- Use project memory to recall patterns from previous sprints.
+- Capture learnings and propose rules at the end of every cycle.
+- Keep the user informed at each step — no silent operations.

package/commands/forge.md

@@ -0,0 +1,55 @@
+---
+description: Full sprint cycle — Analyze → Plan → Implement → Review → Commit
+argument-hint: <project path or description>
+---
+
+# /kyro:forge — Complete Kyro Cycle
+
+Execute the full sprint lifecycle with validation gates between each phase.
+
+## Execution
+
+> **IMPORTANT**: This command delegates to the `orchestrator` agent.
+> Do not execute phases directly — the orchestrator handles all delegation,
+> skill loading, and validation gates.
+>
+> **The orchestrator is the single source of truth for the lifecycle.**
+> See `agents/orchestrator.md` for the full detailed protocol.
+
+## Target: $ARGUMENTS
+
+## Lifecycle Summary (Gates Contract)
+
+The orchestrator follows this sequence. Approval gates are enforced at the orchestrator-defined checkpoints.
+
+### Phase 0: Detect Project State
+
+Check if a ROADMAP exists to choose between INIT and SPRINT flow.
+
+### INIT Flow (no ROADMAP)
+
+- **Phase 1**: Analyze (INIT mode) — codebase exploration, findings, roadmap creation
+  - GATE 1: Approve INIT summary
+- **Phase 2**: First Sprint — generate Sprint 1 from roadmap
+  - GATE 2: Approve sprint plan
+
+### SPRINT Flow (ROADMAP exists)
+
+- **Phase 3**: Generate Next Sprint — read roadmap, retro, and debt; build sprint
+  - GATE 3: Approve sprint plan
+
+### Both Flows Converge
+
+- **Phase 4**: Implement — task by task execution with review and debug protocols
+  - GATE 4: Approve implementation
+- **Phase 5**: Review & Close — quality gates, retro, debt update, rule proposals
+
+### Learning Capture
+
+Review corrections and propose new rules for `.agents/kyro/scopes/rules.md`.
+
+## Rules
+
+- Never skip phases or gates. The sequence is non-negotiable.
+- Never proceed past a gate without explicit user approval.
+- See `agents/orchestrator.md` for full gate protocol, checkpoints, validation, and failure recovery.

package/commands/status.md

@@ -0,0 +1,92 @@
+---
+description: Show project status, sprint progress, and technical debt summary
+argument-hint: [brief|full|debt|debt-add|debt-resolve|debt-escalate]
+---
+
+# /kyro:status — Project Status
+
+Report project progress, technical debt status, and next sprint preview from markdown artifacts.
+
+## Execution
+
+> **IMPORTANT**: Before generating the report, read the sprint-forge skill's STATUS mode:
+> 1. Read `skills/sprint-forge/SKILL.md` — capabilities matrix, configuration resolution
+> 2. Read `skills/sprint-forge/assets/modes/STATUS.md` — report workflow and format
+> 3. Read `skills/sprint-forge/assets/helpers/debt-tracker.md` — debt table rules
+
+## View: $ARGUMENTS
+
+### Standard Report
+
+1. **Locate output directory** — resolve `{output_kyro_dir}`
+2. **Read project state** — README, ROADMAP, all sprint files
+3. **Summarize state** and generate report:
+
+```text
+══════════════════════════════════════
+KYRO — Project Status
+══════════════════════════════════════
+
+## Sprint Progress
+Sprint 1: ██████████ 10/10 (100%) ✓ Complete
+Sprint 2: ████████░░  8/10 ( 80%) ✓ Complete
+Sprint 3: ███████░░░  7/10 ( 70%) ~ In Progress
+Sprint 4: ░░░░░░░░░░  0/10 (  0%)   Planned
+
+## Technical Debt
+- Open: 4
+- In progress: 1
+- Aged: 2
+- Critical: 1
+
+## Roadmap Health
+- Sprints completed: 2/5
+- Roadmap adaptations: 1 (Sprint 3 scope reduced)
+- Carry-over tasks: 3
+
+## Next Sprint Preview
+Sprint 4: [title from roadmap]
+- Suggested phases: [count]
+- Carry-over tasks: [count]
+- Critical debt items due: [count]
+```
+
+### Variants
+
+- **brief** — Sprint progress + next sprint preview only
+- **full** — Complete report with all sections
+- **debt** — Focus on technical debt table and aged items
+
+## Debt Management
+
+The `debt-*` variants provide direct debt lifecycle actions. Read `skills/sprint-forge/assets/helpers/debt-tracker.md` before executing any of these.
+
+### debt-add
+
+Add a new debt item:
+
+```
+/kyro:status debt-add "Missing error boundary in dashboard" --origin "Sprint 3 retro" --target "Sprint 4"
+```
+
+### debt-resolve
+
+Mark a debt item as resolved:
+
+```
+/kyro:status debt-resolve 3 --sprint "Sprint 3"
+```
+
+### debt-escalate
+
+Flag aged debt items (open >3 sprints) and prompt for triage:
+- Should this become a dedicated sprint?
+- Should the priority be increased?
+- Is this still relevant or can it be closed as N/A?
+
+### Debt Rules
+
+- Debt items are never deleted — only their status changes
+- Every sprint inherits the full debt table from the previous sprint
+- Items open for >3 sprints should be escalated during status review
+- New debt discovered during execution gets added with origin "Sprint N phase"

package/commands/wrap-up.md

@@ -0,0 +1,85 @@
+---
+description: End-of-session closure ritual with quality check and context handoff
+argument-hint: [session notes]
+---
+
+# /kyro:wrap-up — Session Closure Ritual
+
+Structured 5-step checklist to close the current session cleanly. Ensures no work is lost, quality is maintained, learnings are captured, and the next session has full context.
+
+## Execution
+
+> **IMPORTANT**: Before running the closure ritual:
+> 1. Read `skills/sprint-forge/assets/helpers/handoff.md` — context transfer format and checklist
+> 2. Run the orchestrator's session-end checkpoint — check uncommitted changes, sprint progress, and pending learnings
+
+## Session Notes: $ARGUMENTS
+
+### Step 1: Changes Audit
+
+Check for uncommitted or unsaved work:
+
+1. Run `git status` — list modified, staged, and untracked files
+2. Run `git stash list` — check for stashed work
+3. If there are uncommitted changes:
+   - Ask: "Should I commit these changes before closing?"
+   - If yes, create a descriptive commit
+   - If no, document the uncommitted state in step 4
+
+### Step 2: Quality Check
+
+Run quality gates from `config.json`:
+
+1. **Lint**: Run the project's lint command (if configured)
+2. **Typecheck**: Run the project's typecheck command (if configured)
+3. **Tests**: Run related tests (if configured)
+4. Report results — if failures exist, ask whether to fix now or defer
+
+### Step 3: Learning Capture
+
+Prompt for learnings from this session:
+
+1. Review corrections made during the session — any patterns?
+2. Review unexpected discoveries — worth capturing?
+3. For each learning, format as:
+   ```
+   [LEARN] Category: One-line rule
+   ```
+4. Learnings are proposed for `.agents/kyro/scopes/rules.md` and recorded in the sprint retro after approval
+
+### Step 4: Next Session Context
+
+Generate a context note for the next session:
+
+1. **What was being worked on**: Current task/sprint, files modified
+2. **What's done**: Tasks completed this session
+3. **What's next**: Remaining tasks, next priorities
+4. **Blockers**: Any unresolved issues or decisions needed
+5. If a sprint is active, update re-entry prompts with current state
+
+### Step 5: Session Summary
+
+Display session summary:
+
+1. Inspect sprint artifacts and git history for current progress:
+   - Tasks completed this session
+   - Learnings proposed or captured
+   - Commits created this session
+2. Display summary table:
+   ```
+   Session Summary
+   ───────────────────────
+   Duration:    {time}
+   Tasks:       {completed}/{total}
+   Learnings:   {count} captured
+   Commits:     {count} this session
+   Status:      {clean/uncommitted changes}
+   ```
+3. Confirm the handoff and re-entry prompts reflect the current state
+
+### Output
+
+After completing all 5 steps:
+1. Display the summary
+2. Confirm session is ready to close
+3. Suggest running `/kyro:forge` if a sprint milestone was reached and a retrospective is needed

package/config.json

@@ -0,0 +1,17 @@
+{
+  "rules": {
+    "path": ".agents/kyro/scopes/rules.md",
+    "auto_load": true,
+    "require_approval": true
+  },
+  "quality_gates": {
+    "typecheck": "npm run typecheck",
+    "build": "npm run build"
+  },
+  "sprint": {
+    "max_tasks_per_sprint": 10,
+    "checkpoint_per_phase": true,
+    "require_retro": true,
+    "debt_aged_threshold_sprints": 3
+  }
+}