@kody-ade/kody-engine-lite 0.1.28 → 0.1.30

package/README.md

@@ -1,86 +1,163 @@
 # Kody Engine Lite
 
-**Issue → PR in one command.** Comment `@kody` on a GitHub issue and Kody autonomously classifies, plans, builds, tests, reviews, fixes, and ships a pull request.
+[![npm](https://img.shields.io/npm/v/@kody-ade/kody-engine-lite)](https://www.npmjs.com/package/@kody-ade/kody-engine-lite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-```
-@kody  →  taskify → plan → build → verify → review → fix → ship  →  PR created
-```
+**Issue → PR in one command.** Comment `@kody` on a GitHub issue and Kody autonomously classifies, plans, builds, tests, reviews, fixes, and ships a pull request.
 
-Kody is a 7-stage autonomous SDLC pipeline that runs in GitHub Actions. It uses Claude Code (or any LLM via LiteLLM) to turn issues into production-ready PRs — with quality gates, AI-powered failure diagnosis, risk-based human approval, and self-improving memory.
+Kody is a 7-stage autonomous SDLC pipeline that runs in GitHub Actions. It uses Claude Code (or any LLM via LiteLLM) to turn issues into production-ready PRs — with quality gates, AI-powered failure diagnosis, risk-based human approval, and shared context between stages.
 
 ## Why Kody?
 
-Most AI coding tools are **autocomplete** (Copilot) or **chat-based** (Cursor, Cline). You still drive. Kody is different: it's an **autonomous pipeline** that takes an issue and delivers a tested, reviewed PR — even for complex, multi-file features that single-agent tools choke on.
-
-Single agents hit context limits on large tasks. Kody splits work into focused stages — each with a fresh context window but access to curated context from previous stages. A 27-minute auth system build (JWT, sessions, middleware, RBAC, 7 stages, 3 autofix retries) completes end-to-end without losing track.
+Most AI coding tools are **autocomplete** (Copilot) or **chat-based** (Cursor, Cline). You still drive. Kody is an **autonomous pipeline** — comment `@kody`, walk away, come back to a PR.
 
 | | Kody | Copilot Workspace | Devin | Cursor Agent |
 |---|---|---|---|---|
 | **Runs in CI** | GitHub Actions | GitHub Cloud | Devin Cloud | Local IDE |
-| **Fire and forget** | Comment `@kody`, walk away | Must interact | Must interact | Must be open |
-| **Quality gates** | typecheck + tests + lint + AI diagnosis + auto-retry | Basic | Runs tests | Runs tests |
-| **Risk gate** | Pauses HIGH-risk tasks for human approval | No | No | No |
+| **Fire and forget** | Yes | No — interactive | Partially | No — IDE must be open |
+| **Pipeline stages** | 7 stages with quality gates | Plan → implement | Single agent | Single agent |
+| **Shared sessions** | Stages share Claude Code sessions (no cold starts) | Single conversation | Single conversation | Single conversation |
+| **Risk gate** | Pauses HIGH-risk for human approval | No | No | No |
+| **AI failure diagnosis** | Classifies errors before retry (fixable/infra/abort) | No | No | No |
 | **Model flexible** | Any LLM via LiteLLM | GitHub models only | Proprietary | Cursor models |
 | **Open source** | MIT | Proprietary | Proprietary | Proprietary |
-| **Accumulated context** | Curated context flows between stages | Single conversation | Single agent | Single agent |
-| **Complex tasks** | 27-min auth system with 7 stages + autofix | Struggles with large scope | Better | Struggles with large scope |
 | **Cost** | Your API costs only | $10-39/month | $20-500/month | Subscription |
 
 [Full comparison →](docs/COMPARISON.md)
 
+## Pipeline
+
+```
+  ┌─────────────────────────────────────────────────────────────┐
+  │                      @kody on issue                         │
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ① TASKIFY         Tier: cheap                              │
+  │  Classify task, detect complexity, ask questions → task.json │
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+                ┌────────────▼────────────┐
+                │  LOW?  skip to ④        │
+                │  MEDIUM?  continue      │
+                │  HIGH?  continue        │
+                └────────────┬────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ② PLAN            Tier: strong                             │
+  │  TDD implementation plan (deep reasoning)        → plan.md  │
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+                ┌────────────▼────────────┐
+                │  HIGH risk?             │
+                │  🛑 Pause for approval  │──── @kody approve
+                └────────────┬────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ③ BUILD           Tier: mid                                │
+  │  Implement code via Claude Code tools    → code + git commit│
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ④ VERIFY          (deterministic gate)                     │
+  │  typecheck + tests + lint                                   │
+  │  ┌───────────────────────────────────────────────────┐      │
+  │  │  Fail? → AI diagnosis → autofix → retry (up to 2) │      │
+  │  └───────────────────────────────────────────────────┘      │
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ⑤ REVIEW          Tier: strong                             │
+  │  Code review: PASS/FAIL + Critical/Major/Minor  → review.md │
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ⑥ REVIEW-FIX      Tier: mid                               │
+  │  Fix Critical and Major findings             → code + commit│
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │  ⑦ SHIP            (deterministic)                          │
+  │  Push branch + create PR with Closes #N       → ship.md + PR│
+  └──────────────────────────┬──────────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────────┐
+  │                 ✅ PR created & ready for review             │
+  └─────────────────────────────────────────────────────────────┘
+```
+
+**Tiers are configurable** — cheap/mid/strong map to any model via `modelMap` in config. Defaults: haiku/sonnet/opus. Route to MiniMax, GPT, Gemini, or local models via [LiteLLM](docs/LITELLM.md).
+
+**Shared sessions** — stages in the same group share a Claude Code session: taskify+plan (explore), build+autofix+review-fix (implementation), review (fresh perspective). No cold-start re-exploration between stages.
+
+[Pipeline details →](docs/PIPELINE.md)
+
 ## Quick Start
 
+**Prerequisites:** Node.js >= 22, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), [GitHub CLI](https://cli.github.com/), git
+
+### 1. Install
+
 ```bash
-# 1. Install
 npm install -g @kody-ade/kody-engine-lite
+```
 
-# 2. Set up GitHub secret
+### 2. Set up GitHub
+
+```bash
 gh secret set ANTHROPIC_API_KEY --repo owner/repo
-# Settings → Actions → "Allow GitHub Actions to create and approve pull requests"
+```
+
+Then in GitHub: **Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"**
+
+### 3. Initialize
 
-# 3. Initialize (auto-detects, commits, and pushes)
+```bash
 cd your-project
 kody-engine-lite init
-
-# 4. Comment on any issue
-@kody
 ```
 
-`init` spawns Claude Code to analyze your project and generates: workflow file, config with auto-detected quality commands, project memory (architecture + conventions), 14 GitHub labels — then commits and pushes everything.
+This analyzes your project and generates workflow, config, memory, and labels — then commits and pushes.
 
-**Prerequisites:** Node.js >= 22, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), [GitHub CLI](https://cli.github.com/), git
+### 4. Use
 
-## Pipeline
+Comment on any GitHub issue:
 
 ```
-@kody on issue
-  ↓
-1. taskify   — classify task, detect complexity, ask questions     → task.json
-2. plan      — TDD implementation plan (deep reasoning)           → plan.md
-   ↓ HIGH risk? pause for human approval
-3. build     — implement code via Claude Code tools                → code changes
-4. verify    — typecheck + tests + lint (AI diagnosis + autofix)   → verify.md
-5. review    — code review: PASS/FAIL + Critical/Major/Minor      → review.md
-6. review-fix — fix Critical and Major findings                    → code changes
-7. ship      — push branch + create PR with Closes #N             → ship.md
-  ↓
-PR created
+@kody
 ```
 
-Complexity auto-detected: **low** skips plan/review (4 stages), **medium** skips review-fix (6 stages), **high** runs all 7.
+### Switch to a different model (optional)
 
-[Pipeline details →](docs/PIPELINE.md)
+Add `litellm-config.yaml` to route all tiers through MiniMax (or any LLM):
+
+```yaml
+# litellm-config.yaml
+model_list:
+  - model_name: claude-haiku-4-5-20251001
+    litellm_params:
+      model: minimax/MiniMax-M2.7-highspeed
+      api_key: os.environ/MINIMAX_API_KEY
+```
+
+```json
+// kody.config.json — add litellmUrl
+{ "agent": { "litellmUrl": "http://localhost:4000" } }
+```
+
+Kody auto-starts the proxy and loads API keys from `.env`. [Full LiteLLM guide →](docs/LITELLM.md)
 
 ## Commands
 
 ### GitHub Comments
 
-```bash
-@kody                              # Full pipeline
-@kody approve                      # Resume after questions or risk gate
-@kody fix                          # Re-build (comment body = feedback)
-@kody rerun --from <stage>         # Resume from specific stage
-```
+| Command | What it does |
+|---------|-------------|
+| `@kody` | Run full pipeline |
+| `@kody approve` | Resume after questions or risk gate |
+| `@kody fix` | Re-run from build stage. Write feedback in the comment body — it gets injected into the build prompt |
+| `@kody rerun` | Resume from the failed or paused stage |
+| `@kody rerun --from <stage>` | Resume from a specific stage |
 
 ### CLI
 
@@ -95,20 +172,20 @@ kody-engine-lite init [--force]
 
 ## Key Features
 
+- **Shared Sessions** — stages in the same group share a Claude Code session, eliminating cold-start codebase re-exploration ([details](docs/FEATURES.md#shared-sessions))
 - **Risk Gate** — HIGH-risk tasks pause for human plan approval before building ([details](docs/FEATURES.md#risk-gate))
 - **AI Failure Diagnosis** — classifies errors as fixable/infrastructure/pre-existing/abort before retry ([details](docs/FEATURES.md#ai-powered-failure-diagnosis))
 - **Question Gates** — asks product/architecture questions when the task is unclear ([details](docs/FEATURES.md#question-gates))
+- **Any LLM** — route through LiteLLM to use MiniMax, GPT, Gemini, local models ([setup guide](docs/LITELLM.md))
 - **Retrospective** — analyzes each run, identifies patterns, suggests improvements ([details](docs/FEATURES.md#retrospective-system))
 - **Auto-Learning** — extracts coding conventions from each successful run ([details](docs/FEATURES.md#auto-learning-memory))
-- **Accumulated Context** — each stage passes curated context to the next — fresh window, shared knowledge ([details](docs/FEATURES.md#accumulated-context))
-- **Any LLM** — route through LiteLLM to use MiniMax, GPT, Gemini, local models ([setup guide](docs/LITELLM.md))
 
 ## Documentation
 
 | Doc | What's in it |
 |-----|-------------|
-| [Pipeline](docs/PIPELINE.md) | Stage details, complexity skipping, artifacts, state machine |
-| [Features](docs/FEATURES.md) | Risk gate, diagnosis, retrospective, auto-learn, labels |
+| [Pipeline](docs/PIPELINE.md) | Stage details, shared sessions, complexity skipping, artifacts |
+| [Features](docs/FEATURES.md) | Risk gate, diagnosis, sessions, retrospective, auto-learn, labels |
 | [LiteLLM](docs/LITELLM.md) | Non-Anthropic model setup, auto-start, tested providers |
 | [Configuration](docs/CONFIGURATION.md) | Full config reference, env vars, workflow setup |
 | [Comparison](docs/COMPARISON.md) | vs Copilot, Devin, Cursor, Cline, SWE-agent, OpenHands |

package/dist/bin/cli.js

@@ -87,20 +87,22 @@ function checkCommand(command2, args2) {
 function createClaudeCodeRunner() {
   return {
     async run(_stageName, prompt, model, timeout, _taskDir, options) {
-      return runSubprocess(
-        "claude",
-        [
-          "--print",
-          "--model",
-          model,
-          "--dangerously-skip-permissions",
-          "--allowedTools",
-          "Bash,Edit,Read,Write,Glob,Grep"
-        ],
-        prompt,
-        timeout,
-        options
-      );
+      const args2 = [
+        "--print",
+        "--model",
+        model,
+        "--dangerously-skip-permissions",
+        "--allowedTools",
+        "Bash,Edit,Read,Write,Glob,Grep"
+      ];
+      if (options?.sessionId) {
+        if (options.resumeSession) {
+          args2.push("--resume", options.sessionId);
+        } else {
+          args2.push("--session-id", options.sessionId);
+        }
+      }
+      return runSubprocess("claude", args2, prompt, timeout, options);
     },
     async healthCheck() {
       return checkCommand("claude", ["--version"]);
@@ -824,6 +826,17 @@ var init_runner_selection = __esm({
 // src/stages/agent.ts
 import * as fs5 from "fs";
 import * as path5 from "path";
+function getSessionInfo(stageName, sessions) {
+  const group = SESSION_GROUP[stageName];
+  if (!group) return void 0;
+  const existing = sessions[group];
+  if (existing) {
+    return { sessionId: existing, resumeSession: true };
+  }
+  const newId = crypto.randomUUID();
+  sessions[group] = newId;
+  return { sessionId: newId, resumeSession: false };
+}
 function validateStageOutput(stageName, content) {
   switch (stageName) {
     case "taskify":
@@ -850,10 +863,16 @@ async function executeAgentStage(ctx, def) {
   if (config.agent.litellmUrl) {
     extraEnv.ANTHROPIC_BASE_URL = config.agent.litellmUrl;
   }
+  const sessions = ctx.sessions ?? {};
+  const sessionInfo = getSessionInfo(def.name, sessions);
+  if (sessionInfo) {
+    logger.info(`  session: ${SESSION_GROUP[def.name]} (${sessionInfo.resumeSession ? "resume" : "new"})`);
+  }
   const runner = getRunnerForStage(ctx, def.name);
   const result = await runner.run(def.name, prompt, model, def.timeout, ctx.taskDir, {
     cwd: ctx.projectDir,
-    env: extraEnv
+    env: extraEnv,
+    ...sessionInfo
   });
   if (result.outcome !== "completed") {
     return { outcome: result.outcome, error: result.error, retries: 0 };
@@ -924,6 +943,7 @@ ${summary}
 `;
   fs5.appendFileSync(contextPath, entry);
 }
+var SESSION_GROUP;
 var init_agent = __esm({
   "src/stages/agent.ts"() {
     "use strict";
@@ -932,6 +952,14 @@ var init_agent = __esm({
     init_config();
     init_runner_selection();
     init_logger();
+    SESSION_GROUP = {
+      taskify: "explore",
+      plan: "explore",
+      build: "build",
+      autofix: "build",
+      "review-fix": "build",
+      review: "review"
+    };
   }
 });
 
@@ -1006,6 +1034,7 @@ function runQualityGates(taskDir, projectRoot) {
   const cwd = projectRoot ?? process.cwd();
   const allErrors = [];
   const allSummary = [];
+  const rawOutputs = [];
   let allPass = true;
   const commands = [
     { name: "typecheck", cmd: config.quality.typecheck },
@@ -1027,10 +1056,11 @@ function runQualityGates(taskDir, projectRoot) {
       allPass = false;
       const errors = parseErrors(result.output);
       allErrors.push(...errors.map((e) => `[${name}] ${e}`));
+      rawOutputs.push({ name, output: result.output.slice(-3e3) });
     }
     allSummary.push(...extractSummary(result.output, name));
   }
-  return { pass: allPass, errors: allErrors, summary: allSummary };
+  return { pass: allPass, errors: allErrors, summary: allSummary, rawOutputs };
 }
 var init_verify_runner = __esm({
   "src/verify-runner.ts"() {
@@ -1162,6 +1192,18 @@ function executeGateStage(ctx, def) {
 `);
     for (const s of verifyResult.summary) {
       lines.push(`- ${s}
+`);
+    }
+  }
+  if (verifyResult.rawOutputs.length > 0) {
+    lines.push(`
+## Raw Output
+`);
+    for (const { name, output } of verifyResult.rawOutputs) {
+      lines.push(`### ${name}
+\`\`\`
+${output}
+\`\`\`
 `);
     }
   }
@@ -2072,6 +2114,7 @@ async function runPipelineInner(ctx) {
     state = initState(ctx.taskId);
     writeState(state, ctx.taskDir);
   }
+  ctx.sessions = state.sessions ?? {};
   if (state.state !== "running") {
     state.state = "running";
     for (const stage of STAGES) {
@@ -2159,6 +2202,7 @@ async function runPipelineInner(ctx) {
         error: isTimeout ? "Stage timed out" : result.error ?? "Stage failed"
       };
       state.state = "failed";
+      state.sessions = ctx.sessions;
       writeState(state, ctx.taskDir);
       logger.error(`[${def.name}] ${isTimeout ? "\u23F1 timed out" : `\u2717 failed: ${result.error}`}`);
       if (ctx.input.issueNumber && !ctx.input.local) {
@@ -2166,6 +2210,7 @@ async function runPipelineInner(ctx) {
       }
       break;
     }
+    state.sessions = ctx.sessions;
     writeState(state, ctx.taskDir);
   }
   const allCompleted = STAGES.every((s) => state.stages[s.name].state === "completed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine-lite",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Autonomous SDLC pipeline: Kody orchestration + Claude Code + LiteLLM",
   "license": "MIT",
   "type": "module",