kyro-ai 3.2.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "kyro-ai",
+  "version": "3.2.0",
+  "description": "Portable sprint workflow kit for AI coding agents, with markdown artifacts, adapter guides, and formal debt tracking",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "npm run clean && tsc && npm run build:chmod",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "check:links": "node scripts/check-markdown-links.mjs",
+    "check:versions": "node scripts/check-versions.mjs",
+    "check": "npm run typecheck && npm run check:versions && npm run check:links",
+    "prepublishOnly": "npm run build",
+    "build:chmod": "node scripts/make-cli-executable.mjs"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-workflow",
+    "llm-workflow",
+    "agentic-development",
+    "markdown-workflow",
+    "workflow",
+    "sprint",
+    "planning",
+    "execution",
+    "debt-tracking",
+    "roadmap",
+    "iterative",
+    "adaptive",
+    "agents",
+    "claude-code",
+    "self-correction",
+    "worktrees",
+    "context-persistence"
+  ],
+  "author": {
+    "name": "SynapSync",
+    "url": "https://github.com/SynapSync"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SynapSync/kyro-ai.git"
+  },
+  "homepage": "https://synapsync.dev/cognitives/kyro-ai",
+  "skills": [
+    "./skills/sprint-forge",
+    "./skills/qa-review"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "typescript": "^5.7.3"
+  },
+  "files": [
+    "dist",
+    "commands",
+    "agents",
+    "skills",
+    "scripts",
+    "docs",
+    "rules",
+    "contexts",
+    "templates",
+    "config.json",
+    "WORKFLOW.yaml",
+    ".claude-plugin",
+    "settings.example.json",
+    "README.md"
+  ],
+  "bin": {
+    "kyro": "dist/cli.js",
+    "kyro-ai": "dist/cli.js"
+  }
+}

package/rules/context-persistence.md

@@ -0,0 +1,54 @@
+---
+description: Governs re-entry prompt management, context compaction safety, and session handoff procedures. Ensures zero mental context loss between sessions.
+globs: ["**/*.md"]
+alwaysApply: true
+---
+
+# Context Persistence
+
+Rules governing how mental context is preserved across sessions and compaction events.
+
+## R-CP-01: Update Re-Entry Prompts at Milestones
+
+Update re-entry prompts after INIT completes and after each executed sprint.
+
+- Re-entry prompts live in the project's sprint output directory.
+- They must contain: current sprint number, phase, last completed task, active debt items, and output directory path.
+- Stale re-entry prompts are worse than no prompts — they cause misaligned execution.
+
+## R-CP-02: Save State Before Compaction
+
+Save re-entry state before context compaction occurs.
+
+- The orchestrator should trigger this before compaction when possible.
+- State includes: current phase, task index, in-progress work, and any uncommitted decisions.
+- If compaction happens without a save, the session must restart from the last checkpoint.
+
+## R-CP-03: Handoff Document on Mid-Sprint Exit
+
+Generate a handoff document when ending a session mid-sprint.
+
+- The handoff must include:
+  - Current sprint and phase
+  - Last completed task and next pending task
+  - Any in-flight decisions or blockers
+  - Modified files not yet committed
+  - Active debt items relevant to current work
+- Use the handoff helper (`skills/sprint-forge/assets/helpers/handoff.md`) to generate enriched handoffs with mental model context.
+
+## R-CP-04: Re-Entry Prompts Are Source of Truth
+
+Re-entry prompts are the authoritative source for output directory paths.
+
+- Never hardcode or guess output paths — always read from the re-entry prompt.
+- If the re-entry prompt is missing or corrupted, ask the user to confirm the output directory before proceeding.
+- Output directory format: `{cwd}/.agents/kyro/scopes/{project}/`
+
+## R-CP-05: Session Continuity Verification
+
+When resuming a session, verify continuity:
+
+1. Read the re-entry prompt.
+2. Confirm the sprint file exists and matches the expected state.
+3. Check for any handoff documents from the previous session.
+4. If state is inconsistent, present the discrepancy to the user before proceeding.

package/rules/estimation.md

@@ -0,0 +1,56 @@
+---
+description: Governs task estimation practices including rule loading, historical calibration, buffer allocation, and error tracking for continuous improvement.
+globs: ["**/*.md"]
+alwaysApply: true
+---
+
+# Estimation
+
+Rules governing how tasks are estimated and how estimation accuracy is tracked over time.
+
+## R-ES-01: Load Estimation Rules Before Estimating
+
+Load estimation rules from `.agents/kyro/scopes/rules.md` before producing any estimate.
+
+- Filter for rules tagged with estimation-related keywords (estimate, duration, complexity, underestimate).
+- Apply relevant corrections to the base estimate.
+- If the rules file is unavailable, proceed with base estimates but flag the sprint as "uncalibrated."
+
+## R-ES-02: Buffer for Historically Underestimated Types
+
+Add buffer for task types that have been historically underestimated.
+
+Common underestimation patterns:
+- **Migration tasks**: Add 30% buffer (data edge cases, rollback planning)
+- **Integration tasks**: Add 25% buffer (API mismatches, auth flows)
+- **Refactoring tasks**: Add 20% buffer (hidden dependencies, test updates)
+- **First-time frameworks**: Add 40% buffer (learning curve, configuration)
+
+These defaults are overridden by project-specific learned rules when available.
+
+## R-ES-03: Track Actual vs Estimated
+
+Track actual completion time against estimates for every task.
+
+- Record in the sprint file: `estimated: Xh | actual: Yh | delta: ±Z%`
+- Deltas are inputs to the retro's estimation accuracy analysis.
+- The metrics helper aggregates these across sprints for trend detection.
+
+## R-ES-04: Flag Significant Estimation Errors
+
+Flag tasks with greater than 30% estimation error in the retrospective.
+
+- Over-estimates (>30% faster than expected) suggest the task was simpler than anticipated or the estimator is being too conservative.
+- Under-estimates (>30% slower than expected) suggest hidden complexity or scope creep.
+- For each flagged task, record:
+  - Root cause of the error
+  - Whether a learned rule should be created
+  - Adjusted buffer for similar future tasks
+
+## R-ES-05: Estimation Units
+
+Use consistent estimation units across all sprints.
+
+- Unit: story points mapped to approximate hours (1 SP = ~1h for a senior developer).
+- Range: 1-8 SP per task. Tasks estimated above 8 SP must be decomposed.
+- If the user prefers different units, calibrate once and record the mapping in the project's sprint config.

package/rules/learning-rules.md

@@ -0,0 +1,66 @@
+---
+description: Governs the capture, formatting, and lifecycle of learned rules in .agents/kyro/scopes/rules.md. Ensures rules are specific, actionable, and do not accumulate without bound.
+globs: ["**/*.md"]
+alwaysApply: true
+---
+
+# Learning Rules
+
+Rules governing how Kyro captures and manages per-project learnings.
+
+## R-LR-01: Capture Corrections as Rules
+
+When a correction is made during a sprint (user overrides a decision, a pattern causes a bug, an estimation is wrong), capture it as a rule.
+
+Format:
+```
+[LEARN] <date> (<project>) — <specific, actionable rule>
+```
+
+Example:
+```
+[LEARN] 2026-01-15 (api-gateway) — Always check for null middleware before calling next() in Express error handlers
+```
+
+## R-LR-02: Rules Must Be Specific and Actionable
+
+Rules must describe a concrete behavior to adopt or avoid. Vague rules are rejected.
+
+- BAD: "Be more careful with error handling"
+- GOOD: "Wrap all external API calls in try/catch and log the operation on failure"
+- BAD: "Tests are important"
+- GOOD: "Add integration tests for every new API endpoint before closing the task"
+
+## R-LR-03: Include Provenance
+
+Every rule must include the date it was learned and the project where the lesson originated.
+
+- This enables filtering rules by recency and relevance.
+- When applying rules to a new project, prioritize rules from similar project types.
+- Rules without provenance are flagged for update during the next retro.
+
+## R-LR-04: Check Before Adding
+
+Before proposing a new rule, check `.agents/kyro/scopes/rules.md` for existing rules that cover the same concern.
+
+- If a match exists, update or refine the existing rule instead of adding a duplicate.
+- If the new rule contradicts an existing one, present both to the user for resolution.
+- Use the learner helper's search capability to find semantic matches.
+
+## R-LR-05: Maximum 50 Active Rules
+
+The active rule set must not exceed 50 rules.
+
+- When the limit is reached, trigger a consolidation review:
+  1. Merge rules that cover the same domain into a single, broader rule.
+  2. Deprecate rules that have not been triggered in the last 5 sprints.
+  3. Archive deprecated rules to `.agents/kyro/scopes/rules-archive.md`.
+- Present the consolidation plan to the user for approval before modifying.
+
+## R-LR-06: Rule Application Tracking
+
+Track which rules are applied during each sprint.
+
+- Record rule applications in the sprint file's "Applied Rules" section.
+- Rules that are consistently applied become candidates for automation or linting.
+- Rules that are never triggered become candidates for deprecation.

package/rules/quality-gates.md

@@ -0,0 +1,65 @@
+---
+description: Defines mandatory quality checks before closing any task. Classifies issues as BLOCKER, WARNING, or SUGGESTION and enforces resolution policies for each.
+globs: ["**/*.{ts,tsx,js,jsx,py,rs,go}"]
+alwaysApply: true
+---
+
+# Quality Gates
+
+Rules governing code quality enforcement during sprint execution.
+
+## R-QG-01: Run All Checks Before Closing
+
+Run lint, typecheck, and tests before closing any task.
+
+- Commands are defined in `config.json` under `quality_gates`.
+- All three must pass. A single failure keeps the task open.
+- If a check is not applicable (e.g., no test suite), document why in the task notes.
+
+## R-QG-02: BLOCKER Items Must Be Fixed
+
+BLOCKER-level issues must be fixed before the task can be marked complete. No exceptions.
+
+- BLOCKERs include: failing tests, type errors, lint errors that indicate bugs, security vulnerabilities.
+- If a BLOCKER cannot be fixed within the current task scope, escalate to the user with a clear description.
+- Never downgrade a BLOCKER to WARNING to bypass this rule.
+
+## R-QG-03: WARNING Items Require Justification
+
+WARNING-level issues may be skipped, but only with explicit justification recorded in the sprint file.
+
+- WARNINGs include: style violations, missing edge-case tests, minor lint warnings.
+- Justification must explain why the warning is acceptable and when it will be addressed.
+- Unjustified warnings are treated as BLOCKERs.
+
+## R-QG-04: No Debug Artifacts in Production Code
+
+The following are prohibited in production code:
+
+- `console.log` / `console.debug` / `console.warn` (use a proper logger)
+- `debugger` statements
+- `print()` statements used for debugging (Python)
+- Commented-out code blocks longer than 3 lines
+- `TODO` or `FIXME` without an associated debt table entry
+
+Detection is handled by the orchestrator post-edit scan.
+
+## R-QG-05: No Hardcoded Secrets
+
+No hardcoded secrets, API keys, tokens, or credentials in source code.
+
+- Use environment variables or a secrets manager.
+- If a placeholder is needed, use the format `PLACEHOLDER_<SERVICE>_<TYPE>` (e.g., `PLACEHOLDER_STRIPE_API_KEY`).
+- The orchestrator pre-commit checkpoint scans for common secret patterns before allowing commits.
+
+## R-QG-06: Review Checklist
+
+After each task, the orchestrator runs a review checklist:
+
+1. Does the change match the task description?
+2. Are there any regressions in existing functionality?
+3. Are quality gates passing?
+4. Is there new debt that needs to be tracked?
+5. Are there any SUGGESTION-level improvements worth noting?
+
+SUGGESTION items are recorded but do not block task completion.

package/rules/sprint-discipline.md

@@ -0,0 +1,49 @@
+---
+description: Enforces sequential sprint execution, mandatory retrospectives, and debt continuity. Prevents batch-planning and ensures every recommendation is tracked across sprints.
+globs: ["**/*.md"]
+alwaysApply: true
+---
+
+# Sprint Discipline
+
+Rules governing sprint lifecycle integrity. These ensure that sprints are deliberate, sequential, and accountable.
+
+## R-SD-01: One Sprint at a Time
+
+Always generate sprints one at a time. Never batch-generate multiple sprints in a single session.
+
+- Each sprint depends on the outcomes and learnings of the previous one.
+- Batch planning ignores emergent work and produces stale plans.
+- If the user asks for "the next 3 sprints," generate Sprint N, execute it, retro it, then generate Sprint N+1.
+
+## R-SD-02: Retro Before Next Sprint
+
+A retrospective is mandatory before generating the next sprint.
+
+- The retro produces recommendations, estimation corrections, and debt updates.
+- These feed directly into Sprint N+1 planning.
+- If no retro exists for Sprint N, refuse to generate Sprint N+1 and prompt the user to run the retrospective phase of forge first.
+
+## R-SD-03: Disposition Table Completeness
+
+Every recommendation from Sprint N-1's retro must appear in Sprint N's disposition table.
+
+- Valid dispositions: `ADOPTED`, `DEFERRED`, `REJECTED (reason)`, `PARTIAL (details)`
+- No recommendation may be silently dropped.
+- The disposition table is the first section of every sprint plan after the header.
+
+## R-SD-04: Debt Table Inheritance
+
+The debt table is inherited complete from the previous sprint. Never delete rows.
+
+- New debt items are appended.
+- Resolved items change status to `RESOLVED` with the sprint number and date.
+- Aged items (open for more than 3 sprints) are flagged with `[AGED]`.
+- The debt table is a living document — deletion is data loss.
+
+## R-SD-05: Checkpoint After Each Phase
+
+Save the sprint file after each phase completes.
+
+- If context is lost mid-sprint, the last checkpoint is the recovery point.
+- Checkpoints include: phase status, completed tasks, updated debt, and discovered work.

package/scripts/check-markdown-links.mjs

@@ -0,0 +1,97 @@
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+
+function isMdFile(path) {
+  return path.endsWith('.md') && statSync(path).isFile();
+}
+
+import { readdirSync } from 'node:fs';
+
+function* walkMdFiles(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkMdFiles(full);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      yield full;
+    }
+  }
+}
+
+function collectFiles(patterns) {
+  const files = [];
+  for (const pattern of patterns) {
+    const full = resolve(root, pattern);
+    try {
+      if (statSync(full).isDirectory()) {
+        files.push(...walkMdFiles(full));
+      } else if (isMdFile(full)) {
+        files.push(full);
+      }
+    } catch {
+      // skip missing patterns
+    }
+  }
+  return files;
+}
+
+const linkRe = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+let exitCode = 0;
+
+function checkFile(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const baseDir = dirname(filePath);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let match;
+    linkRe.lastIndex = 0;
+
+    while ((match = linkRe.exec(line)) !== null) {
+      const target = match[2].trim();
+
+      // Skip external URLs, anchors, and wiki-links
+      if (target.startsWith('http://') || target.startsWith('https://') || target.startsWith('#') || target.startsWith('mailto:')) {
+        continue;
+      }
+
+      // Skip references starting with a slash (absolute paths in the filesystem, not markdown relative)
+      if (target.startsWith('/')) {
+        continue;
+      }
+
+      const resolved = resolve(baseDir, target);
+      if (!existsSync(resolved)) {
+        const relPath = relative(root, filePath);
+        console.error(`BROKEN LINK: ${relPath}:${i + 1} -> ${target}`);
+        exitCode = 1;
+      }
+    }
+  }
+}
+
+const patterns = [
+  'README.md',
+  'docs',
+  'skills',
+  'agents',
+  'commands',
+];
+
+const allFiles = collectFiles(patterns);
+
+for (const file of allFiles) {
+  checkFile(file);
+}
+
+if (exitCode === 0) {
+  console.log(`All relative links valid (${allFiles.length} files checked)`);
+}
+process.exit(exitCode);

package/scripts/check-versions.mjs

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function readJson(file) {
+  return JSON.parse(readFileSync(resolve(root, file), 'utf-8'));
+}
+
+function readYamlVersion(file) {
+  const text = readFileSync(resolve(root, file), 'utf-8');
+  const match = text.match(/^version:\s*["']?([^"'\n]+)["']?$/m);
+  if (!match) throw new Error(`Could not parse version from ${file}`);
+  return match[1];
+}
+
+const pkg = readJson('package.json');
+const plugin = readJson('.claude-plugin/plugin.json');
+const workflowVersion = readYamlVersion('WORKFLOW.yaml');
+
+const pkgVersion = pkg.version;
+const pluginVersion = plugin.version;
+
+let failed = false;
+
+if (pkgVersion !== pluginVersion) {
+  console.error(`ERROR: Version mismatch`);
+  console.error(`  package.json:                  ${pkgVersion}`);
+  console.error(`  .claude-plugin/plugin.json:    ${pluginVersion}`);
+  failed = true;
+}
+
+if (pkgVersion !== workflowVersion) {
+  console.error(`ERROR: Version mismatch`);
+  console.error(`  package.json:     ${pkgVersion}`);
+  console.error(`  WORKFLOW.yaml:    ${workflowVersion}`);
+  failed = true;
+}
+
+if (failed) {
+  console.error(`\nFix: update all version fields to match before committing.`);
+  process.exit(1);
+}
+
+console.log(`All versions match: ${pkgVersion}`);

package/scripts/make-cli-executable.mjs

@@ -0,0 +1,12 @@
+import { chmodSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const cliPath = resolve('dist/cli.js');
+
+if (!existsSync(cliPath)) {
+  console.error('ERROR: dist/cli.js does not exist. Run tsc before make-cli-executable.');
+  process.exit(1);
+}
+
+chmodSync(cliPath, 0o755);
+console.log('Made dist/cli.js executable');

package/settings.example.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "Bash(npm run typecheck*)",
+      "Bash(npm run build*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(git push --force*)",
+      "Bash(git reset --hard*)"
+    ]
+  },
+  "output": {
+    "markdown": true,
+    "spinner": {
+      "enabled": true,
+      "style": "dots"
+    }
+  }
+}