@kody-ade/kody-engine-lite 0.1.25 → 0.1.27

package/README.md

@@ -1,269 +1,119 @@
 # Kody Engine Lite
 
-Autonomous SDLC pipeline. Comment `@kody` on a GitHub issue → Kody classifies, plans, builds, tests, reviews, fixes, and ships a PR. Zero human intervention required.
-
-## How it works
+**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  (comment on a GitHub issue)
-  ↓
-GitHub Actions workflow
-  ↓
-7-stage pipeline:
-  1. taskify  — classify task, detect complexity, ask questions if unclear
-  2. plan     — TDD implementation plan (opus — deep reasoning)
-  3. build    — implement code changes (sonnet — tool use via Claude Code)
-  4. verify   — typecheck + tests + lint (auto-fix on failure)
-  5. review   — code review with severity levels (opus)
-  6. review-fix — fix Critical/Major findings (sonnet)
-  7. ship     — push branch + create PR with Closes #N
-  ↓
-PR created with What/Scope/Changes description
+@kody  →  taskify → plan → build → verify → review → fix → ship  →  PR created
 ```
 
+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.
+
+## 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.
+
+| | 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 |
+| **Model flexible** | Any LLM via LiteLLM | GitHub models only | Proprietary | Cursor models |
+| **Open source** | MIT | Proprietary | Proprietary | Proprietary |
+| **Cost** | Your API costs only | $10-39/month | $20-500/month | Subscription |
+
+[Full comparison →](docs/COMPARISON.md)
+
 ## Quick Start
 
 ```bash
-# Install
+# 1. Install
 npm install -g @kody-ade/kody-engine-lite
 
-# Init (in your project root) — auto-detects everything
+# 2. Initialize (auto-detects everything)
 cd your-project
 kody-engine-lite init
 
-# Push and use
+# 3. Set up GitHub
+gh secret set ANTHROPIC_API_KEY --repo owner/repo
+# Settings → Actions → "Allow GitHub Actions to create and approve pull requests"
+
+# 4. Push
 git add .github/workflows/kody.yml kody.config.json .kody/
 git commit -m "chore: add kody engine"
 git push
 
-# Comment on any issue
+# 5. Comment on any issue
 @kody
 ```
 
-### What `init` does
+`init` spawns Claude Code to analyze your project and generates: workflow file, config with auto-detected quality commands, project memory (architecture + conventions), and 14 GitHub labels.
 
-Spawns Claude Code to analyze your project and auto-generates:
-- `.github/workflows/kody.yml` — full CI/CD workflow
-- `kody.config.json` — quality commands auto-detected from `package.json`
-- `.kody/memory/architecture.md` — project-specific tech stack and structure
-- `.kody/memory/conventions.md` — coding patterns, references to existing docs
-- 14 GitHub labels — lifecycle, complexity, and type labels
-- Health checks — CLI tools, GitHub auth, secrets, config validation
+**Prerequisites:** Node.js >= 22, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), [GitHub CLI](https://cli.github.com/), git
 
-### GitHub Setup
+## Pipeline
 
-**Required secret:**
-```bash
-gh secret set ANTHROPIC_API_KEY --repo owner/repo
+```
+@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
 ```
 
-**Required permission:**
-Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"
+Complexity auto-detected: **low** skips plan/review (4 stages), **medium** skips review-fix (6 stages), **high** runs all 7.
+
+[Pipeline details →](docs/PIPELINE.md)
 
 ## Commands
 
 ### GitHub Comments
 
-```
-@kody                         Run full pipeline (auto-generates task-id)
-@kody approve                 Answer questions and resume paused pipeline
-@kody fix                     Re-build from build stage (on issues or PRs)
-@kody fix                     Comment body = feedback for the fix
-  fix the auth middleware
-  to return 401 not 500
-@kody rerun                   Resume from failed/paused stage
-@kody rerun --from <stage>    Resume from specific stage
+```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
 ```
 
 ### CLI
 
 ```bash
-kody-engine-lite run --task "Add feature X" --cwd /path/to/project
-kody-engine-lite run --issue-number 42 --cwd /path/to/project
+kody-engine-lite run --issue-number 42 --local --cwd ./project
+kody-engine-lite run --task "Add retry utility" --local
 kody-engine-lite fix --issue-number 42 --feedback "Use middleware pattern"
-kody-engine-lite rerun --issue-number 42
-kody-engine-lite status --task-id <id>
+kody-engine-lite rerun --issue-number 42 --from verify
+kody-engine-lite status --task-id 42-260327-102254
 kody-engine-lite init [--force]
 ```
 
-## Pipeline Stages
-
-| Stage | Model | What it does |
-|-------|-------|-------------|
-| taskify | haiku | Classify task → `task.json` (type, scope, risk, questions) |
-| plan | opus | Create TDD plan → `plan.md` (deep reasoning) |
-| build | sonnet | Implement code using Claude Code tools (Read/Write/Edit/Bash) |
-| verify | — | Run typecheck + tests + lint from `kody.config.json` |
-| review | opus | Code review → `review.md` (PASS/FAIL + Critical/Major/Minor) |
-| review-fix | sonnet | Fix Critical and Major findings |
-| ship | — | Push branch, create PR, comment on issue |
-
 ## Key Features
 
-### Question Gates
-
-Kody asks before building if something is unclear:
-
-- **Taskify** asks product/requirements questions ("Should search be case-sensitive?")
-- **Plan** asks architecture/technical questions ("Recommend middleware pattern — approve?")
-- Pipeline pauses with `kody:waiting` label
-- Resume with `@kody approve` + your answers in the comment body
-
-### Complexity-Based Stage Skipping
-
-Auto-detected from taskify's risk assessment, or override with `--complexity`:
-
-| Complexity | Runs | Skips |
-|-----------|------|-------|
-| low | taskify → build → verify → ship | plan, review, review-fix |
-| medium | taskify → plan → build → verify → review → ship | review-fix |
-| high | all 7 stages | nothing |
-
-### Branch Syncing
-
-Every run merges latest from the default branch into the feature branch before building.
-
-### Verify + Autofix Loop
-
-If verify fails: runs lint-fix → format-fix → autofix agent → retries (up to 2 attempts).
-
-### Review + Fix Loop
-
-If review verdict is FAIL: runs review-fix agent → re-reviews.
-
-### Rich PR Description
-
-```markdown
-## What
-Add authentication middleware to 8 unprotected API routes
-
-## Scope
-- `src/middleware/auth.ts`
-- `src/app/api/cron/route.ts`
-
-**Type:** bugfix | **Risk:** high
-
-## Changes
-Added auth middleware to all cron routes and copilotkit endpoint.
-
-**Review:** ✅ PASS
-**Verify:** ✅ typecheck + tests + lint passed
-
-<details><summary>📋 Implementation plan</summary>
-...
-</details>
-
-Closes #42
-```
-
-### Labels
-
-`init` creates 14 labels:
-- **Lifecycle:** `kody:planning`, `kody:building`, `kody:review`, `kody:done`, `kody:failed`, `kody:waiting`
-- **Complexity:** `kody:low`, `kody:medium`, `kody:high`
-- **Type:** `kody:feature`, `kody:bugfix`, `kody:refactor`, `kody:docs`, `kody:chore`
-
-### Memory System
-
-`.kody/memory/` files are prepended to every agent prompt:
-- `architecture.md` — auto-generated by `init`
-- `conventions.md` — auto-learned after each successful run
-
-## Using Non-Anthropic Models (LiteLLM)
-
-Claude Code can use **any model** through a LiteLLM proxy. Tested with MiniMax (full tool use: Write, Read, Edit, Bash, Grep).
-
-```bash
-# Start LiteLLM proxy
-docker run -d -p 4000:4000 \
-  -e MINIMAX_API_KEY=your-key \
-  -v config.yaml:/app/config.yaml \
-  ghcr.io/berriai/litellm:main-latest --config /app/config.yaml
-```
-
-```yaml
-# config.yaml
-model_list:
-  - model_name: minimax
-    litellm_params:
-      model: minimax/MiniMax-M2.7-highspeed
-      api_key: os.environ/MINIMAX_API_KEY
-```
-
-```json
-// kody.config.json
-{
-  "agent": {
-    "litellmUrl": "http://localhost:4000",
-    "modelMap": { "cheap": "minimax", "mid": "minimax", "strong": "minimax" }
-  }
-}
-```
-
-LiteLLM translates Anthropic's tool-use protocol to the target provider's format. No code changes needed.
-
-## Configuration
-
-### `kody.config.json`
-
-| Field | Description | Default |
-|-------|-------------|---------|
-| `quality.typecheck` | Typecheck command | `pnpm -s tsc --noEmit` |
-| `quality.lint` | Lint command | `""` |
-| `quality.lintFix` | Auto-fix lint | `""` |
-| `quality.testUnit` | Unit test command | `pnpm -s test` |
-| `git.defaultBranch` | Default branch | `dev` |
-| `github.owner` | GitHub org/user | auto-detected |
-| `github.repo` | Repository name | auto-detected |
-| `agent.modelMap.cheap` | Taskify model | `haiku` |
-| `agent.modelMap.mid` | Build/fix model | `sonnet` |
-| `agent.modelMap.strong` | Plan/review model | `opus` |
-| `agent.litellmUrl` | LiteLLM proxy URL | — |
-
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ANTHROPIC_API_KEY` | Yes | Claude API key (repo secret) |
-| `GH_TOKEN` | Auto | GitHub token (provided by Actions) |
-| `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error` |
-
-## Architecture
-
-```
-src/
-├── entry.ts          — CLI: run/rerun/fix/status, arg parsing, CI mode
-├── state-machine.ts  — Pipeline loop, stage dispatch, question gates, complexity
-├── agent-runner.ts   — Claude Code subprocess wrapper (thin — spawn, pipe, timeout)
-├── context.ts        — Prompt assembly + memory + task context injection
-├── definitions.ts    — 7-stage pipeline config
-├── types.ts          — TypeScript interfaces
-├── config.ts         — kody.config.json loader + constants
-├── git-utils.ts      — Branch, commit, push, sync, diff
-├── github-api.ts     — Issues, labels, PRs, comments via gh CLI
-├── verify-runner.ts  — Quality gate execution
-├── validators.ts     — Output validation (task.json, plan.md, review.md)
-├── memory.ts         — .kody/memory/ reader
-├── logger.ts         — Structured logging with CI groups
-├── preflight.ts      — Startup health checks
-├── kody-utils.ts     — Task directory utilities
-└── bin/cli.ts        — Package CLI: init (LLM-powered), run, version
-```
-
-## Development
-
-```bash
-pnpm install          # Install deps
-pnpm typecheck        # Type check
-pnpm test             # 125 tests (16 files)
-pnpm build            # Build npm package
-pnpm kody run ...     # Dev mode (tsx)
-npm publish --access public  # Publish
-```
-
-## Security
-
-Only GitHub collaborators (COLLABORATOR, MEMBER, OWNER) can trigger `@kody`. External contributors cannot.
+- **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))
+- **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))
+- **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 |
+| [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 |
+| [Architecture](docs/ARCHITECTURE.md) | Source tree, state machine diagram, development guide |
+| [FAQ](docs/FAQ.md) | Common questions about usage, models, security, cost |
 
 ## License
 

package/dist/agent-runner.d.ts

@@ -0,0 +1,4 @@
+import type { AgentRunner } from "./types.js";
+import type { KodyConfig } from "./config.js";
+export declare function createClaudeCodeRunner(): AgentRunner;
+export declare function createRunners(config: KodyConfig): Record<string, AgentRunner>;

package/dist/agent-runner.js

@@ -0,0 +1,122 @@
+import { spawn, execFileSync } from "child_process";
+const SIGKILL_GRACE_MS = 5000;
+const STDERR_TAIL_CHARS = 500;
+function writeStdin(child, prompt) {
+    return new Promise((resolve, reject) => {
+        if (!child.stdin) {
+            resolve();
+            return;
+        }
+        child.stdin.write(prompt, (err) => {
+            if (err)
+                reject(err);
+            else {
+                child.stdin.end();
+                resolve();
+            }
+        });
+    });
+}
+function waitForProcess(child, timeout) {
+    return new Promise((resolve) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!child.killed)
+                    child.kill("SIGKILL");
+            }, SIGKILL_GRACE_MS);
+        }, timeout);
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            resolve({
+                code,
+                stdout: Buffer.concat(stdoutChunks).toString(),
+                stderr: Buffer.concat(stderrChunks).toString(),
+            });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: -1, stdout: "", stderr: err.message });
+        });
+    });
+}
+async function runSubprocess(command, args, prompt, timeout, options) {
+    const child = spawn(command, args, {
+        cwd: options?.cwd ?? process.cwd(),
+        env: {
+            ...process.env,
+            SKIP_BUILD: "1",
+            SKIP_HOOKS: "1",
+            ...options?.env,
+        },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    try {
+        await writeStdin(child, prompt);
+    }
+    catch (err) {
+        return {
+            outcome: "failed",
+            error: `Failed to send prompt: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const { code, stdout, stderr } = await waitForProcess(child, timeout);
+    if (code === 0) {
+        return { outcome: "completed", output: stdout };
+    }
+    return {
+        outcome: code === null ? "timed_out" : "failed",
+        error: `Exit code ${code}\n${stderr.slice(-STDERR_TAIL_CHARS)}`,
+    };
+}
+function checkCommand(command, args) {
+    try {
+        execFileSync(command, args, { timeout: 10_000, stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Claude Code Runner ──────────────────────────────────────────────────────
+export 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);
+        },
+        async healthCheck() {
+            return checkCommand("claude", ["--version"]);
+        },
+    };
+}
+// ─── Runner Factory ──────────────────────────────────────────────────────────
+const RUNNER_FACTORIES = {
+    "claude-code": createClaudeCodeRunner,
+};
+export function createRunners(config) {
+    // New multi-runner config
+    if (config.agent.runners && Object.keys(config.agent.runners).length > 0) {
+        const runners = {};
+        for (const [name, runnerConfig] of Object.entries(config.agent.runners)) {
+            const factory = RUNNER_FACTORIES[runnerConfig.type];
+            if (factory) {
+                runners[name] = factory();
+            }
+        }
+        return runners;
+    }
+    // Legacy single-runner fallback
+    const runnerType = config.agent.runner ?? "claude-code";
+    const factory = RUNNER_FACTORIES[runnerType];
+    const defaultName = config.agent.defaultRunner ?? "claude";
+    return { [defaultName]: factory ? factory() : createClaudeCodeRunner() };
+}