karajan-code 1.51.0 → 1.53.0

package/README.md

@@ -14,6 +14,7 @@
   <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
+  <a href="https://github.com/manufosela/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-orange.svg" alt="Homebrew"></a>
 </p>
 
 <p align="center">
@@ -52,19 +53,33 @@ If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-
 
 ## Install
 
-**One-liner** (detects your OS, installs via npm):
+**npm** (recommended):
+```bash
+npm install -g karajan-code
+```
+
+**Homebrew** (macOS):
+```bash
+brew tap manufosela/tap
+brew install karajan-code
+```
 
+**One-liner** (detects OS, installs via npm):
 ```bash
 curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
 ```
 
-**Or directly with npm:**
+**Docker** (no Node.js needed):
+```bash
+docker run --rm -v $(pwd):/workspace karajan-code kj --version
+```
 
+**Python**:
 ```bash
-npm install -g karajan-code
+cd wrappers/python && pip install .
 ```
 
-That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages it). No config files to copy. `kj init` auto-detects your installed agents.
+That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
 
 ## Three ways to use Karajan
 
@@ -260,3 +275,8 @@ Issues and pull requests welcome. If something doesn't work as documented, [open
 ---
 
 Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ npm packages published.
+
+### Contributors
+
+- [@aitormf](https://github.com/aitormf) — OpenCode agent (5th built-in agent)
+- [@reiaguilera](https://github.com/reiaguilera) — Beta testing, feature proposals, and quality feedback

package/docs/README.es.md

@@ -14,6 +14,7 @@
   <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
+  <a href="https://github.com/manufosela/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-orange.svg" alt="Homebrew"></a>
 </p>
 
 <p align="center">
@@ -52,11 +53,28 @@ Si Claude Code es un programador de pares inteligente, Karajan es el pipeline CI
 
 ## Instalacion
 
+**npm** (recomendado):
 ```bash
 npm install -g karajan-code
 ```
 
-Eso es todo. No requiere Docker (SonarQube usa Docker, pero Karajan lo gestiona automaticamente). Sin ficheros de configuracion que copiar. `kj init` auto-detecta tus agentes instalados.
+**Homebrew** (macOS):
+```bash
+brew tap manufosela/tap
+brew install karajan-code
+```
+
+**One-liner** (detecta SO, instala via npm):
+```bash
+curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
+```
+
+**Docker** (sin Node.js):
+```bash
+docker run --rm -v $(pwd):/workspace karajan-code kj --version
+```
+
+`kj init` auto-detecta tus agentes instalados e instala RTK para optimizacion de tokens.
 
 ## Tres formas de usar Karajan
 
@@ -230,3 +248,8 @@ Issues y pull requests bienvenidos. Si algo no funciona como esta documentado, [
 ---
 
 Construido por [@manufosela](https://github.com/manufosela). Head of Engineering en Geniova Technologies, co-organizador de NodeJS Madrid, autor de [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ paquetes npm publicados.
+
+### Contributors
+
+- [@aitormf](https://github.com/aitormf) — Agente OpenCode (5o agente built-in)
+- [@reiaguilera](https://github.com/reiaguilera) — Beta testing, propuestas de mejora y feedback de calidad

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli.js

@@ -86,6 +86,7 @@ program
   .option("--enable-triage")
   .option("--enable-discover")
   .option("--enable-architect")
+  .option("--plan <planId>", "Plan ID from kj plan. Loads persisted plan context and skips researcher/architect/planner.")
   .option("--enable-hu-reviewer")
   .option("--hu-file <path>", "YAML file with HU stories to certify before coding")
   .option("--enable-serena")

package/src/commands/plan.js

@@ -60,8 +60,26 @@ export async function planCommand({ task, config, logger, json, context }) {
 
   const parsed = parseMaybeJsonString(result.output);
 
+  // Persist plan
+  let planId = null;
+  try {
+    const { savePlan } = await import("../plan/plan-store.js");
+    const projectDir = config.projectDir || process.cwd();
+    planId = await savePlan(projectDir, {
+      task,
+      researchContext: null,
+      architectContext: null,
+      plan: parsed || result.output,
+      raw: result.output
+    });
+  } catch (err) {
+    logger.warn(`Plan persistence failed: ${err.message}`);
+  }
+
   if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
+    const jsonOutput = parsed || result.output;
+    const outputObj = typeof jsonOutput === "object" ? { ...jsonOutput, planId } : { plan: jsonOutput, planId };
+    console.log(JSON.stringify(outputObj, null, 2));
     return;
   }
 
@@ -70,4 +88,9 @@ export async function planCommand({ task, config, logger, json, context }) {
   } else {
     console.log(result.output);
   }
+
+  if (planId) {
+    console.log(`\nPlan saved: ${planId}`);
+    console.log(`Use it with: kj run --plan ${planId} "<task>"`);
+  }
 }

package/src/guards/intent-guard.js

@@ -6,6 +6,23 @@ import { VALID_TASK_TYPES } from "./policy-resolver.js";
  * Evaluated top-down; first match with confidence >= threshold wins.
  */
 const INTENT_PATTERNS = [
+  // No-code tasks (data analysis, document generation, SQL queries, CSV transforms)
+  // Placed before audit so specific multi-word patterns win over single-word "analizar"/"analyze"
+  {
+    id: "no-code",
+    keywords: [
+      "generate report", "create document", "analyze data", "transform csv",
+      "sql query", "sql queries", "generate queries", "data analysis", "process data",
+      "export to", "import from", "convert data", "parse file",
+      "generar informe", "crear documento", "analizar datos", "transformar csv",
+      "consulta sql", "generar consultas", "analisis de datos", "procesar datos",
+      "exportar a", "importar de", "convertir datos", "parsear fichero",
+    ],
+    taskType: "no-code",
+    level: "simple",
+    confidence: 0.9,
+    message: "No-code task detected — TDD and SonarQube disabled, coder generates non-code output",
+  },
   // Audit / analysis tasks (no code changes, read-only analysis)
   {
     id: "audit",

package/src/guards/policy-resolver.js

@@ -1,4 +1,4 @@
-export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "audit", "analysis"]);
+export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "audit", "analysis", "no-code"]);
 
 export const DEFAULT_POLICIES = {
   sw:        { tdd: true,  sonar: true,  reviewer: true, testsRequired: true  },
@@ -8,6 +8,7 @@ export const DEFAULT_POLICIES = {
   refactor:  { tdd: true,  sonar: true,  reviewer: true, testsRequired: false },
   audit:     { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
   analysis:  { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
+  "no-code": { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
 };
 
 const FALLBACK_TYPE = "sw";

package/src/mcp/handlers/direct-handlers.js

@@ -70,6 +70,76 @@ export async function handlePlanDirect(a, server, extra) {
   );
   const emitter = buildDirectEmitter(server, runLog, extra);
   const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+
+  // --- Phase 1: Researcher (codebase context) ---
+  let researchContext = null;
+  try {
+    const { ResearcherRole } = await import("../../roles/researcher-role.js");
+    const researcherRole = resolveRole(config, "researcher");
+    const researcherOnOutput = ({ stream, line }) => {
+      emitter.emit("progress", { type: "agent:output", stage: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
+    };
+    const researcherStall = createStallDetector({
+      onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
+    });
+
+    sendTrackerLog(server, "researcher", "running", researcherRole.provider);
+    runLog.logText(`[researcher] agent launched for plan context...`);
+    const researcher = new ResearcherRole({ config, logger, emitter });
+    await researcher.init({ task: a.task });
+    let researchOutput;
+    try {
+      researchOutput = await researcher.run({ task: a.task, onOutput: researcherStall.onOutput });
+    } finally {
+      researcherStall.stop();
+    }
+    if (researchOutput.ok) {
+      researchContext = researchOutput.result;
+      sendTrackerLog(server, "researcher", "done");
+      runLog.logText(`[researcher] completed — context available`);
+    } else {
+      sendTrackerLog(server, "researcher", "failed");
+      runLog.logText(`[researcher] failed: ${researchOutput.summary || "unknown"}`);
+    }
+  } catch (err) {
+    logger.warn(`Researcher phase skipped: ${err.message}`);
+  }
+
+  // --- Phase 2: Architect (solution design) ---
+  let architectContext = null;
+  try {
+    const { ArchitectRole } = await import("../../roles/architect-role.js");
+    const architectRole = resolveRole(config, "architect");
+    const architectOnOutput = ({ stream, line }) => {
+      emitter.emit("progress", { type: "agent:output", stage: "architect", message: line, detail: { stream, agent: architectRole.provider } });
+    };
+    const architectStall = createStallDetector({
+      onOutput: architectOnOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
+    });
+
+    sendTrackerLog(server, "architect", "running", architectRole.provider);
+    runLog.logText(`[architect] agent launched for plan context...`);
+    const architect = new ArchitectRole({ config, logger, emitter });
+    await architect.init({ task: a.task });
+    let architectOutput;
+    try {
+      architectOutput = await architect.run({ task: a.task, researchContext, onOutput: architectStall.onOutput });
+    } finally {
+      architectStall.stop();
+    }
+    if (architectOutput.ok) {
+      architectContext = architectOutput.result;
+      sendTrackerLog(server, "architect", "done");
+      runLog.logText(`[architect] completed — context available`);
+    } else {
+      sendTrackerLog(server, "architect", "failed");
+      runLog.logText(`[architect] failed: ${architectOutput.summary || "unknown"}`);
+    }
+  } catch (err) {
+    logger.warn(`Architect phase skipped: ${err.message}`);
+  }
+
+  // --- Phase 3: Planner (with research + architecture context) ---
   const onOutput = ({ stream, line }) => {
     emitter.emit("progress", { type: "agent:output", stage: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
   };
@@ -78,7 +148,7 @@ export async function handlePlanDirect(a, server, extra) {
   });
 
   const planner = createAgent(plannerRole.provider, config, logger);
-  const prompt = buildPlannerPrompt({ task: a.task, context: a.context });
+  const prompt = buildPlannerPrompt({ task: a.task, context: a.context, architectContext });
   sendTrackerLog(server, "planner", "running", plannerRole.provider);
   runLog.logText(`[planner] agent launched, waiting for response...`);
   let result;
@@ -111,7 +181,24 @@ export async function handlePlanDirect(a, server, extra) {
 
   sendTrackerLog(server, "planner", "done");
   const parsed = parseMaybeJsonString(result.output);
-  return { ok: true, plan: parsed || result.output, raw: result.output };
+
+  // --- Persist plan ---
+  let planId = null;
+  try {
+    const { savePlan } = await import("../../plan/plan-store.js");
+    planId = await savePlan(projectDir, {
+      task: a.task,
+      researchContext,
+      architectContext,
+      plan: parsed || result.output,
+      raw: result.output
+    });
+    runLog.logText(`[kj_plan] plan persisted — planId=${planId}`);
+  } catch (err) {
+    logger.warn(`Plan persistence failed (non-blocking): ${err.message}`);
+  }
+
+  return { ok: true, plan: parsed || result.output, raw: result.output, planId, researchContext, architectContext };
 }
 
 export async function handleCodeDirect(a, server, extra) {

package/src/mcp/tools.js

@@ -53,6 +53,7 @@ export const tools = [
       required: ["task"],
       properties: {
         task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042)" },
+        plan: { type: "string", description: "Plan ID from kj_plan. Loads persisted plan context and skips researcher/architect/planner stages." },
         projectDir: { type: "string", description: "Absolute path to the project directory. Required when KJ MCP server runs from a different directory than the target project." },
         pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
         pgProject: { type: "string", description: "Planning Game project ID (e.g., 'Karajan Code'). Required when pgTask is used." },

package/src/orchestrator.js

@@ -984,6 +984,44 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
     pipelineFlags.securityEnabled = false;
   }
 
+  // --- Plan injection: skip researcher/architect/planner if a persisted plan is loaded ---
+  if (flags.plan) {
+    try {
+      const { loadPlan } = await import("./plan/plan-store.js");
+      const projectDir = updatedConfig.projectDir || process.cwd();
+      const loadedPlan = await loadPlan(projectDir, flags.plan);
+      if (loadedPlan) {
+        logger.info(`Loaded persisted plan: ${flags.plan}`);
+        emitProgress(emitter, makeEvent("plan:loaded", { ...eventBase, stage: "plan" }, {
+          message: `Plan loaded from kj_plan: ${flags.plan}`,
+          detail: { planId: flags.plan, task: loadedPlan.task, createdAt: loadedPlan.createdAt }
+        }));
+        stageResults.researcher = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
+        stageResults.architect = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
+        stageResults.planner = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
+        // Inject contexts into session for downstream stages
+        session.research_context = loadedPlan.researchContext || null;
+        session.architect_context = loadedPlan.architectContext || null;
+        session.loaded_plan = loadedPlan.plan || null;
+        await saveSession(session);
+
+        // Build the planned task from the plan steps
+        const plan = loadedPlan.plan;
+        let plannedTask = task;
+        if (plan && typeof plan === "object" && plan.steps) {
+          const stepList = plan.steps.map((s, idx) => `${idx + 1}. ${s.description || s}`).join("\n");
+          plannedTask = `${task}\n\n## Implementation Plan\n${plan.approach || ""}\n\n## Steps\n${stepList}`;
+        } else if (typeof plan === "string") {
+          plannedTask = `${task}\n\n## Implementation Plan\n${plan}`;
+        }
+        return { plannedTask, updatedConfig };
+      }
+      logger.warn(`Plan ${flags.plan} not found — falling back to normal pipeline`);
+    } catch (err) {
+      logger.warn(`Plan loading failed: ${err.message} — falling back to normal pipeline`);
+    }
+  }
+
   // --- Researcher → Planner ---
   const { plannedTask } = await runPlanningPhases({ config: updatedConfig, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion });
 
@@ -1085,7 +1123,7 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };
 
-  const skipSonarForTaskType = new Set(["infra", "doc"]);
+  const skipSonarForTaskType = new Set(["infra", "doc", "no-code"]);
   const effectiveTaskType = session.resolved_policies?.taskType || null;
   if (config.sonarqube.enabled && !skipSonarForTaskType.has(effectiveTaskType)) {
     const sonarResult = await runSonarStage({

package/src/plan/plan-store.js

@@ -0,0 +1,116 @@
+/**
+ * Plan persistence — save, load, list plans generated by kj_plan.
+ * Plans are stored at ~/.kj/plans/<projectSlug>/<planId>.json
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+function getKjHome() {
+  return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
+}
+
+function projectSlug(projectDir) {
+  return projectDir
+    .replace(/^\//, "")
+    .replace(/[/\\]/g, "_")
+    .replace(/[^a-zA-Z0-9_.-]/g, "")
+    .slice(0, 120);
+}
+
+function plansDir(projectDir) {
+  return path.join(getKjHome(), "plans", projectSlug(projectDir));
+}
+
+function generatePlanId() {
+  const now = new Date();
+  const ts = now.toISOString().replace(/[-:T]/g, "").replace(/\.\d+Z$/, "");
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `plan-${ts}-${rand}`;
+}
+
+/**
+ * Save a plan result to disk.
+ * @param {string} projectDir - Absolute path to the project
+ * @param {object} planResult - { task, researchContext, architectContext, plan, raw }
+ * @returns {Promise<string>} planId
+ */
+export async function savePlan(projectDir, planResult) {
+  const dir = plansDir(projectDir);
+  await fs.mkdir(dir, { recursive: true });
+
+  const planId = generatePlanId();
+  const record = {
+    planId,
+    task: planResult.task || null,
+    researchContext: planResult.researchContext || null,
+    architectContext: planResult.architectContext || null,
+    plan: planResult.plan || null,
+    raw: planResult.raw || null,
+    createdAt: new Date().toISOString()
+  };
+
+  const filePath = path.join(dir, `${planId}.json`);
+  await fs.writeFile(filePath, JSON.stringify(record, null, 2), "utf8");
+  return planId;
+}
+
+/**
+ * Load a saved plan by ID.
+ * @param {string} projectDir
+ * @param {string} planId
+ * @returns {Promise<object|null>} { planId, task, researchContext, architectContext, plan, createdAt } or null
+ */
+export async function loadPlan(projectDir, planId) {
+  const filePath = path.join(plansDir(projectDir), `${planId}.json`);
+  try {
+    const data = await fs.readFile(filePath, "utf8");
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all plans for a project, sorted by creation time (newest first).
+ * @param {string} projectDir
+ * @returns {Promise<Array<{planId: string, task: string, createdAt: string}>>}
+ */
+export async function listPlans(projectDir) {
+  const dir = plansDir(projectDir);
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const plans = [];
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const data = await fs.readFile(path.join(dir, file), "utf8");
+      const record = JSON.parse(data);
+      plans.push({
+        planId: record.planId,
+        task: record.task,
+        createdAt: record.createdAt
+      });
+    } catch { /* skip corrupt files */ }
+  }
+
+  plans.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+  return plans;
+}
+
+/**
+ * Get the most recent plan for a project.
+ * @param {string} projectDir
+ * @returns {Promise<object|null>}
+ */
+export async function getLatestPlan(projectDir) {
+  const all = await listPlans(projectDir);
+  if (all.length === 0) return null;
+  return loadPlan(projectDir, all[0].planId);
+}

package/src/prompts/triage.js

@@ -40,13 +40,14 @@ export function buildTriagePrompt({ task, instructions, availableRoles }) {
       "- **architect**: Enable when creating new modules/apps, changing data models or APIs, medium/complex tasks, or when design approach is ambiguous. Disable for simple fixes, doc-only, or CSS-only changes.",
       "- **hu-reviewer**: Enable for medium/complex tasks that benefit from story decomposition and certification. Disable for trivial/simple tasks, doc-only, or CSS-only changes.",
       "- **audit/analysis taskType**: Set taskType to \"audit\" or \"analysis\" for tasks that only require reading/inspecting code without making changes (e.g., audit, review, analyze, check, verify, inspect, scan, auditar, revisar, analizar, comprobar, verificar, inspeccionar). The coder and reviewer will be skipped entirely for these tasks.",
+      "- **no-code taskType**: Use no-code when the task is about data analysis, document generation, SQL queries, CSV transformation, report generation, or any non-programming task. The coder will generate output (not source code), and TDD/SonarQube will be disabled. The reviewer still runs to validate logic/correctness.",
       "",
       "Note: coder is ALWAYS active for coding tasks — you don't need to decide on it. However, for audit/analysis taskTypes the coder is skipped."
     ].join("\n"),
     "Classify the task complexity, determine its taskType, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
     "Keep the reasoning short and practical.",
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect|hu-reviewer"],"taskType":"sw|infra|doc|add-tests|refactor|audit|analysis","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
+    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect|hu-reviewer"],"taskType":"sw|infra|doc|add-tests|refactor|audit|analysis|no-code","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
     `## Task\n${task}`
   );
 

package/src/review/tdd-policy.js

@@ -19,7 +19,7 @@ function isSourceFile(file, extensions = []) {
   return extensions.some((ext) => file.endsWith(ext));
 }
 
-const SKIP_TDD_TASK_TYPES = new Set(["doc", "infra"]);
+const SKIP_TDD_TASK_TYPES = new Set(["doc", "infra", "no-code"]);
 
 const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec.", "/src/test/", "/test/", "Test.java", "Test.kt", "test_", "_test.py", "_test.go", "Test.cs", "_spec.rb", "Test.php", "_test.dart", "Tests.swift"];
 const DEFAULT_SOURCE_EXTENSIONS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".kt", ".rb", ".php", ".cs", ".rs", ".swift", ".dart"];

package/src/skills/skill-detector.js

@@ -67,6 +67,15 @@ const TASK_TEXT_PATTERNS = [
   { pattern: /\bflutter\b/i, skill: "flutter" },
   { pattern: /\bswift\b/i, skill: "swift" },
   { pattern: /\bphp\b/i, skill: "php" },
+  { pattern: /\bSQL\b/i, skill: "sql-analysis" },
+  { pattern: /\bquer(?:y|ies)\b/i, skill: "sql-analysis" },
+  { pattern: /\bdatabase\b/i, skill: "sql-analysis" },
+  { pattern: /\bCSV\b/i, skill: "csv-transform" },
+  { pattern: /\btransform\b/i, skill: "csv-transform" },
+  { pattern: /\bparse\b/i, skill: "csv-transform" },
+  { pattern: /\breport\b/i, skill: "data-report" },
+  { pattern: /\banalysis\b/i, skill: "data-report" },
+  { pattern: /\bfindings\b/i, skill: "data-report" },
 ];
 
 /**

package/templates/skills/kj-csv-transform.md

@@ -0,0 +1,40 @@
+# kj-csv-transform — CSV & Data Transformation
+
+Transform, validate, and process CSV and tabular data files.
+
+## Your task
+
+$ARGUMENTS
+
+## Coder instructions
+
+When working with CSV or tabular data:
+
+1. **Auto-detect delimiter** — do not assume comma. Detect the actual delimiter (comma, semicolon, tab, pipe) by inspecting the first few lines. Use libraries that support delimiter sniffing when available.
+2. **Handle encoding** — detect and handle file encoding (UTF-8, UTF-8 BOM, Latin-1/ISO-8859-1, Windows-1252). Convert to UTF-8 for processing.
+3. **Validate data types per column** — after parsing, verify that each column contains the expected data type (string, number, date, boolean). Flag rows with type mismatches.
+4. **Handle missing values explicitly** — define a strategy for missing/empty values (keep as null, fill with default, skip row). Never silently drop rows with missing data.
+5. **Preserve row count** — track input vs output row counts. Log any rows filtered, merged, or split so the transformation is auditable.
+6. **Quote fields correctly** — when writing CSV output, properly escape fields containing delimiters, quotes, or newlines.
+7. **Header normalization** — trim whitespace from headers, handle duplicate column names, and normalize casing if needed.
+8. **Large file support** — for files that may be large, use streaming/chunked processing instead of loading everything into memory.
+
+## Reviewer checklist
+
+When reviewing CSV/data transformation code, check for:
+
+- [ ] **Data integrity** — input row count matches expected output row count (accounting for intentional filters)?
+- [ ] **No silent data loss** — missing values are handled explicitly, not silently dropped?
+- [ ] **Correct transformations** — type conversions, date parsing, and numeric formatting are accurate?
+- [ ] **Encoding handled** — non-ASCII characters preserved correctly through the pipeline?
+- [ ] **Delimiter consistency** — detection works for the actual file, not just assumed comma?
+- [ ] **Edge cases** — empty files, single-row files, files with only headers, fields with embedded newlines?
+- [ ] **Memory safety** — large files processed via streams, not loaded entirely into memory?
+- [ ] **Output format** — output CSV is well-formed (proper quoting, consistent line endings)?
+
+## Output
+
+Provide the transformation code with:
+- Clear input/output format documentation
+- Row count summary (input rows, output rows, filtered rows, error rows)
+- Sample of transformed data for verification

package/templates/skills/kj-data-report.md

@@ -0,0 +1,44 @@
+# kj-data-report — Data Report Generation
+
+Generate structured data reports with clear findings, methodology, and recommendations.
+
+## Your task
+
+$ARGUMENTS
+
+## Coder instructions
+
+When generating data reports:
+
+1. **Structure the report** — follow this format:
+   - **Executive summary** — 2-3 sentences with the key takeaway
+   - **Methodology** — data sources, time range, filters applied, tools used
+   - **Findings** — organized by theme or priority, each with supporting data
+   - **Recommendations** — actionable next steps based on the findings
+2. **Include data tables** — present data in tables with clear headers, units, and formatting. Align numbers right, text left.
+3. **Highlight anomalies and outliers** — flag data points that deviate significantly from the norm. Quantify the deviation (e.g., "3x above average", "lowest in 12 months").
+4. **Quantify everything** — use percentages, counts, averages, medians, and trends. Avoid vague language like "significant increase" without numbers.
+5. **Show comparisons** — include period-over-period comparisons (MoM, YoY) and benchmarks where available.
+6. **Cite data sources** — reference the specific dataset, query, or file that produced each finding.
+7. **Separate facts from interpretation** — clearly distinguish what the data shows from what you conclude.
+8. **Include limitations** — note any data gaps, sample size issues, or caveats that affect conclusions.
+
+## Reviewer checklist
+
+When reviewing data reports, check for:
+
+- [ ] **Conclusions match data** — every claim is supported by the data presented? No logical leaps?
+- [ ] **No cherry-picking** — all relevant data included, not just data that supports a narrative?
+- [ ] **Methodology is sound** — data sources are appropriate, filters are justified, time ranges are sensible?
+- [ ] **Numbers add up** — percentages sum correctly, counts are consistent across sections?
+- [ ] **Anomalies explained** — outliers are acknowledged and investigated, not ignored?
+- [ ] **Actionable recommendations** — recommendations are specific, feasible, and tied to findings?
+- [ ] **Clear formatting** — tables are readable, units are specified, dates are unambiguous?
+- [ ] **Limitations disclosed** — caveats and data quality issues are transparently noted?
+
+## Output
+
+Deliver the report in the structured format above, with:
+- All data tables properly formatted
+- Key metrics highlighted
+- Clear separation between data, analysis, and recommendations

package/templates/skills/kj-sql-analysis.md

@@ -0,0 +1,40 @@
+# kj-sql-analysis — SQL Analysis & Generation
+
+Generate and review SQL queries with a focus on correctness, performance, and security.
+
+## Your task
+
+$ARGUMENTS
+
+## Coder instructions
+
+When writing or modifying SQL queries:
+
+1. **Parameterized queries only** — never concatenate user input into SQL strings. Use prepared statements or parameterized queries (`$1`, `?`, `:param`) to prevent injection.
+2. **Comment complex logic** — add inline comments explaining non-obvious JOINs, subqueries, CTEs, and window functions.
+3. **Validate against schema** — if a schema or migration files are available, verify that table names, column names, and types match the actual schema.
+4. **Prefer explicit column lists** — avoid `SELECT *`; list the columns you need.
+5. **Use aliases consistently** — when joining multiple tables, alias every table and prefix all column references.
+6. **Index-aware queries** — structure WHERE clauses and JOINs to leverage existing indexes. Avoid wrapping indexed columns in functions.
+7. **Limit result sets** — add `LIMIT` / `TOP` for queries that could return unbounded rows unless the full result is explicitly needed.
+8. **Handle NULLs explicitly** — use `COALESCE`, `IS NULL`, or `IS NOT NULL` where NULL values could affect logic.
+
+## Reviewer checklist
+
+When reviewing SQL-related code, check for:
+
+- [ ] **Injection risk** — any string concatenation or template literals building SQL?
+- [ ] **N+1 queries** — loops executing individual queries instead of a single batch/join?
+- [ ] **Missing indexes** — queries filtering or joining on columns without indexes?
+- [ ] **Correct JOINs** — LEFT vs INNER vs CROSS used intentionally? Accidental cartesian products?
+- [ ] **Transaction safety** — multi-statement operations wrapped in transactions where needed?
+- [ ] **Schema alignment** — column names, types, and constraints match the current schema?
+- [ ] **Performance** — unnecessary subqueries that could be CTEs or JOINs? Missing LIMIT on large tables?
+- [ ] **NULL handling** — aggregations, comparisons, and JOINs account for NULL values?
+
+## Output
+
+Provide the SQL queries with:
+- Inline comments for complex sections
+- Explanation of the query plan and expected performance characteristics
+- Any schema changes needed (new indexes, columns, tables)