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

package/README.md

@@ -1,306 +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 — 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.
+
+| | 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 |
+| **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)
+
 ## Quick Start
 
 ```bash
-# Install
+# 1. Install
 npm install -g @kody-ade/kody-engine-lite
 
-# Init (in your project root) — auto-detects everything
+# 2. Set up GitHub secret
+gh secret set ANTHROPIC_API_KEY --repo owner/repo
+# Settings → Actions → "Allow GitHub Actions to create and approve pull requests"
+
+# 3. Initialize (auto-detects, commits, and pushes)
 cd your-project
 kody-engine-lite init
 
-# Push and use
-git add .github/workflows/kody.yml kody.config.json .kody/
-git commit -m "chore: add kody engine"
-git push
-
-# Comment on any issue
+# 4. 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), 14 GitHub labels — then commits and pushes everything.
 
-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
+```
+
+Complexity auto-detected: **low** skips plan/review (4 stages), **medium** skips review-fix (6 stages), **high** runs all 7.
 
-**Required permission:**
-Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"
+[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.
-
-## Branching Convention (Recommended)
-
-Give Kody a dedicated unprotected branch so it can push freely, while keeping your default branch protected for human review.
-
-```
-main (protected — require PR + review + status checks)
-  └── kody/develop (unprotected — Kody's integration branch)
-       ├── kody/task-123  (per-task, short-lived)
-       └── kody/task-456
-```
-
-### Workflow
-
-1. **Task start** — Kody creates `kody/task-<id>` from `kody/develop`
-2. **Work** — Kody pushes freely (commits, quality gates, iterations)
-3. **Task done** — Kody merges task branch into `kody/develop` (squash or fast-forward)
-4. **Ship batch** — PR from `kody/develop` → `main` (human reviews accumulated features)
-5. **After merge** — Rebase `kody/develop` onto updated `main`
-
-### GitHub Setup
-
-Configure via **Settings → Rules → Rulesets**:
-
-| Branch pattern | Protection |
-|---|---|
-| `main` | Require PR, require review, require status checks |
-| `kody/**` | No protection (optionally require status checks for CI) |
-
-Add your GitHub Actions bot as a **bypass actor** so Kody can push to `kody/*` branches even under org-wide rules.
-
-### Guidelines
-
-- **Keep `kody/develop` fresh** — rebase onto `main` after each merge to avoid drift
-- **Always branch from HEAD** — task branches should come from current `kody/develop`
-- **Critical fixes bypass** — for urgent fixes, Kody can branch directly from `main` and PR to `main`, skipping `kody/develop`
-- **Batch size** — PR to `main` after 2-3 related tasks, or on a regular cadence
+- **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))
+- **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 |
+| [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/bin/cli.js

@@ -698,6 +698,16 @@ ${truncated}${spec.length > MAX_TASK_CONTEXT_SPEC ? "\n..." : ""}
     context += `
 ## Plan Summary
 ${truncated}${plan.length > MAX_TASK_CONTEXT_PLAN ? "\n..." : ""}
+`;
+  }
+  const contextMdPath = path4.join(taskDir, "context.md");
+  if (fs4.existsSync(contextMdPath)) {
+    const accumulated = fs4.readFileSync(contextMdPath, "utf-8");
+    const truncated = accumulated.slice(-MAX_ACCUMULATED_CONTEXT);
+    const prefix = accumulated.length > MAX_ACCUMULATED_CONTEXT ? "...(earlier context truncated)\n" : "";
+    context += `
+## Previous Stage Context
+${prefix}${truncated}
 `;
   }
   if (feedback) {
@@ -726,7 +736,7 @@ function resolveModel(modelTier, stageName) {
   if (mapped) return mapped;
   return DEFAULT_MODEL_MAP[modelTier] ?? "sonnet";
 }
-var DEFAULT_MODEL_MAP, MAX_TASK_CONTEXT_PLAN, MAX_TASK_CONTEXT_SPEC;
+var DEFAULT_MODEL_MAP, MAX_TASK_CONTEXT_PLAN, MAX_TASK_CONTEXT_SPEC, MAX_ACCUMULATED_CONTEXT;
 var init_context = __esm({
   "src/context.ts"() {
     "use strict";
@@ -739,6 +749,7 @@ var init_context = __esm({
     };
     MAX_TASK_CONTEXT_PLAN = 1500;
     MAX_TASK_CONTEXT_SPEC = 2e3;
+    MAX_ACCUMULATED_CONTEXT = 4e3;
   }
 });
 
@@ -894,8 +905,25 @@ async function executeAgentStage(ctx, def) {
       }
     }
   }
+  appendStageContext(ctx.taskDir, def.name, result.output);
   return { outcome: "completed", outputFile: def.outputFile, retries: 0 };
 }
+function appendStageContext(taskDir, stageName, output) {
+  const contextPath = path5.join(taskDir, "context.md");
+  const timestamp2 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19);
+  let summary;
+  if (output && output.trim()) {
+    summary = output.slice(0, 500);
+    if (output.length > 500) summary += "\n...(truncated)";
+  } else {
+    summary = "(stage completed via tool use \u2014 no text output)";
+  }
+  const entry = `
+### ${stageName} (${timestamp2})
+${summary}
+`;
+  fs5.appendFileSync(contextPath, entry);
+}
 var init_agent = __esm({
   "src/stages/agent.ts"() {
     "use strict";
@@ -3279,12 +3307,39 @@ ${archItems.join("\n")}
     fs19.writeFileSync(conventionsPath, "# Conventions\n\n<!-- Auto-learned conventions will be appended here -->\n");
     console.log("  \u2713 .kody/memory/conventions.md (seed)");
   }
+  console.log("\n\u2500\u2500 Git \u2500\u2500");
+  const filesToCommit = [
+    ".github/workflows/kody.yml",
+    "kody.config.json",
+    ".kody/memory/architecture.md",
+    ".kody/memory/conventions.md"
+  ].filter((f) => fs19.existsSync(path18.join(cwd, f)));
+  if (filesToCommit.length > 0) {
+    try {
+      execFileSync11("git", ["add", ...filesToCommit], { cwd, stdio: "pipe" });
+      const staged = execFileSync11("git", ["diff", "--cached", "--name-only"], { cwd, encoding: "utf-8" }).trim();
+      if (staged) {
+        execFileSync11("git", ["commit", "--no-gpg-sign", "-m", "chore: add kody engine"], { cwd, stdio: "pipe" });
+        console.log(`  \u2713 Committed: ${filesToCommit.join(", ")}`);
+        try {
+          execFileSync11("git", ["push"], { cwd, stdio: "pipe", timeout: 3e4 });
+          console.log("  \u2713 Pushed to origin");
+        } catch {
+          console.log("  \u25CB Push failed \u2014 run 'git push' manually");
+        }
+      } else {
+        console.log("  \u25CB No new changes to commit");
+      }
+    } catch (err) {
+      console.log(`  \u25CB Git commit skipped: ${err instanceof Error ? err.message : err}`);
+    }
+  }
   const allChecks = [...checks, ghAuth, ghRepo];
   const failed = allChecks.filter((c) => !c.ok);
   console.log("\n\u2500\u2500 Summary \u2500\u2500");
   if (failed.length === 0) {
     console.log("  \u2713 All checks passed! Ready to use.");
-    console.log("\n  Next: Comment '@kody full <task-id>' on a GitHub issue");
+    console.log("\n  Next: Comment '@kody' on a GitHub issue");
   } else {
     console.log(`  \u26A0 ${failed.length} issue(s) to fix:`);
     for (const c of failed) {

package/package.json

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