@kody-ade/kody-engine-lite 0.1.20 → 0.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,401 +1,270 @@
1
1
  # Kody Engine Lite
2
2
 
3
- Autonomous SDLC pipeline runs a 7-stage pipeline (taskify plan build verify review review-fix ship) on your codebase using Claude Code as the execution engine.
3
+ Autonomous SDLC pipeline. Comment `@kody` on a GitHub issueKody classifies, plans, builds, tests, reviews, fixes, and ships a PR. Zero human intervention required.
4
4
 
5
5
  ## How it works
6
6
 
7
7
  ```
8
- @kody full <task-id> (comment on a GitHub issue)
9
-
10
- GitHub Actions workflow triggers
11
-
12
- Kody Engine Lite (npm package)
13
-
8
+ @kody (comment on a GitHub issue)
9
+
10
+ GitHub Actions workflow
11
+
14
12
  7-stage pipeline:
15
- 1. taskify — classify the task (haiku)
16
- 2. plan — create implementation plan (sonnet)
17
- 3. build — implement code changes (opus)
18
- 4. verify — run typecheck + tests + lint
19
- 5. review — code review (sonnet)
20
- 6. review-fix — fix review issues (opus)
21
- 7. ship — push branch + create PR
22
-
23
- PR created on your repo
13
+ 1. taskify — classify task, detect complexity, ask questions if unclear
14
+ 2. plan — TDD implementation plan (opus — deep reasoning)
15
+ 3. build — implement code changes (sonnet — tool use via Claude Code)
16
+ 4. verify — typecheck + tests + lint (auto-fix on failure)
17
+ 5. review — code review with severity levels (opus)
18
+ 6. review-fix — fix Critical/Major findings (sonnet)
19
+ 7. ship — push branch + create PR with Closes #N
20
+
21
+ PR created with What/Scope/Changes description
24
22
  ```
25
23
 
26
24
  ## Quick Start
27
25
 
28
- ### 1. Install
29
-
30
26
  ```bash
27
+ # Install
31
28
  npm install -g @kody-ade/kody-engine-lite
32
- ```
33
-
34
- ### 2. Init (run in your project root)
35
29
 
36
- ```bash
30
+ # Init (in your project root) — auto-detects everything
37
31
  cd your-project
38
32
  kody-engine-lite init
39
- ```
40
-
41
- This will:
42
- - Copy `.github/workflows/kody.yml` to your repo
43
- - Create `kody.config.json` (edit this)
44
- - Create `.kody/memory/architecture.md` (auto-detected)
45
- - Create `.kody/memory/conventions.md` (seed)
46
- - Add `.tasks/` to `.gitignore`
47
- - Run health checks (prerequisites, GitHub auth, secrets)
48
-
49
- ### 3. Configure
50
-
51
- Edit `kody.config.json`:
52
-
53
- ```json
54
- {
55
- "quality": {
56
- "typecheck": "pnpm tsc --noEmit",
57
- "lint": "pnpm lint",
58
- "lintFix": "pnpm lint:fix",
59
- "format": "",
60
- "formatFix": "",
61
- "testUnit": "pnpm test"
62
- },
63
- "git": {
64
- "defaultBranch": "main"
65
- },
66
- "github": {
67
- "owner": "your-org",
68
- "repo": "your-repo"
69
- },
70
- "paths": {
71
- "taskDir": ".tasks"
72
- },
73
- "agent": {
74
- "runner": "claude-code",
75
- "modelMap": {
76
- "cheap": "haiku",
77
- "mid": "sonnet",
78
- "strong": "opus"
79
- }
80
- }
81
- }
82
- ```
83
-
84
- ### 4. GitHub Setup
85
-
86
- #### Required Secret
87
-
88
- Add `ANTHROPIC_API_KEY` to your repo secrets:
89
-
90
- ```bash
91
- gh secret set ANTHROPIC_API_KEY --repo owner/repo
92
- ```
93
-
94
- #### Required Permissions
95
-
96
- Go to **Settings → Actions → General → Workflow permissions**:
97
33
 
98
- 1. Select **"Read and write permissions"**
99
- 2. Check **"Allow GitHub Actions to create and approve pull requests"**
100
- 3. Save
101
-
102
- Without this, the ship stage cannot create PRs.
103
-
104
- ### 5. Push and Use
105
-
106
- ```bash
34
+ # Push and use
107
35
  git add .github/workflows/kody.yml kody.config.json .kody/
108
36
  git commit -m "chore: add kody engine"
109
37
  git push
110
- ```
111
-
112
- Then comment on any issue:
113
38
 
114
- ```
39
+ # Comment on any issue
115
40
  @kody
116
41
  ```
117
42
 
118
- ## CLI Usage
119
-
120
- ### Run locally
121
-
122
- ```bash
123
- # Run against current directory
124
- kody-engine-lite run --task "Add a sum function to src/math.ts with tests"
125
-
126
- # Run against a different project
127
- kody-engine-lite run --task "Add feature X" --cwd /path/to/project
128
-
129
- # Run from a GitHub issue (fetches issue body as task)
130
- kody-engine-lite run --issue-number 1 --cwd /path/to/project
131
-
132
- # Dry run (no agent calls)
133
- kody-engine-lite run --task "Test" --dry-run
134
-
135
- # Resume from a failed/paused stage (auto-detects which stage)
136
- kody-engine-lite rerun --issue-number 1
43
+ ### What `init` does
137
44
 
138
- # Fix rerun from build stage (skip taskify/plan)
139
- kody-engine-lite fix --issue-number 1
140
-
141
- # Fix with feedback
142
- kody-engine-lite fix --issue-number 1 --feedback "Use middleware pattern instead"
143
-
144
- # Check pipeline status
145
- kody-engine-lite status --task-id my-task
146
- ```
45
+ Spawns Claude Code to analyze your project and auto-generates:
46
+ - `.github/workflows/kody.yml` full CI/CD workflow
47
+ - `kody.config.json` — quality commands auto-detected from `package.json`
48
+ - `.kody/memory/architecture.md` project-specific tech stack and structure
49
+ - `.kody/memory/conventions.md` coding patterns, references to existing docs
50
+ - 14 GitHub labels — lifecycle, complexity, and type labels
51
+ - Health checks — CLI tools, GitHub auth, secrets, config validation
147
52
 
148
- ### Init a new project
53
+ ### GitHub Setup
149
54
 
55
+ **Required secret:**
150
56
  ```bash
151
- cd your-project
152
- kody-engine-lite init # setup workflow, config, memory
153
- kody-engine-lite init --force # overwrite existing workflow
57
+ gh secret set ANTHROPIC_API_KEY --repo owner/repo
154
58
  ```
155
59
 
156
- ### GitHub Comment Triggers
157
-
158
- Comment on any issue:
159
-
160
- ```
161
- @kody # Run full pipeline (auto-generates task-id)
162
- @kody full <task-id> # Run with specific task-id
163
- @kody rerun # Resume latest task (auto-detects stage)
164
- @kody rerun --from <stage> # Resume from specific stage
165
- @kody fix # Re-build from build stage (skip taskify/plan)
166
- @kody fix --feedback "Use X instead of Y" # Fix with specific guidance
167
- @kody approve # Approve + provide answers to questions
168
- @kody status <task-id> # Check status
169
- ```
60
+ **Required permission:**
61
+ Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"
170
62
 
171
- ### Approve Flow (Question Gate)
63
+ ## Commands
172
64
 
173
- When Kody encounters unclear requirements or architecture decisions, it pauses and posts questions:
65
+ ### GitHub Comments
174
66
 
175
67
  ```
176
- Kody: 🤔 Kody has questions before proceeding:
177
- 1. Should the search be case-sensitive?
178
- 2. Which users should have access?
179
-
180
- Reply with @kody approve and your answers in the comment body.
68
+ @kody Run full pipeline (auto-generates task-id)
69
+ @kody approve Answer questions and resume paused pipeline
70
+ @kody fix Re-build from build stage (on issues or PRs)
71
+ @kody fix Comment body = feedback for the fix
72
+ fix the auth middleware
73
+ to return 401 not 500
74
+ @kody rerun Resume from failed/paused stage
75
+ @kody rerun --from <stage> Resume from specific stage
181
76
  ```
182
77
 
183
- You reply:
184
-
185
- ```
186
- @kody approve
78
+ ### CLI
187
79
 
188
- 1. Yes, case-sensitive
189
- 2. Only admin users
80
+ ```bash
81
+ kody-engine-lite run --task "Add feature X" --cwd /path/to/project
82
+ kody-engine-lite run --issue-number 42 --cwd /path/to/project
83
+ kody-engine-lite fix --issue-number 42 --feedback "Use middleware pattern"
84
+ kody-engine-lite rerun --issue-number 42
85
+ kody-engine-lite status --task-id <id>
86
+ kody-engine-lite init [--force]
190
87
  ```
191
88
 
192
- Kody resumes automatically from where it paused, with your answers injected as context.
193
-
194
89
  ## Pipeline Stages
195
90
 
196
91
  | Stage | Model | What it does |
197
92
  |-------|-------|-------------|
198
- | taskify | haiku | Classifies task from issue body → `task.json` |
199
- | plan | opus | Deep reasoning: creates TDD implementation plan → `plan.md` |
200
- | build | sonnet | Implements code changes (Claude Code tools handle execution) |
201
- | verify | — | Runs typecheck + tests + lint (from `kody.config.json`) |
202
- | review | opus | Thorough code review → `review.md` (PASS/FAIL + findings) |
203
- | review-fix | sonnet | Applies known fixes from review findings |
204
- | ship | — | Pushes branch + creates PR + comments on issue |
93
+ | taskify | haiku | Classify task → `task.json` (type, scope, risk, questions) |
94
+ | plan | opus | Create TDD plan → `plan.md` (deep reasoning) |
95
+ | build | sonnet | Implement code using Claude Code tools (Read/Write/Edit/Bash) |
96
+ | verify | — | Run typecheck + tests + lint from `kody.config.json` |
97
+ | review | opus | Code review → `review.md` (PASS/FAIL + Critical/Major/Minor) |
98
+ | review-fix | sonnet | Fix Critical and Major findings |
99
+ | ship | — | Push branch, create PR, comment on issue |
205
100
 
206
- ### Branch Syncing
207
-
208
- On every run/rerun/fix, Kody automatically:
209
- 1. Checks out (or creates) the feature branch
210
- 2. Pulls latest from the default branch and merges into the feature branch
211
- 3. If there's a merge conflict, skips the sync and warns
101
+ ## Key Features
212
102
 
213
- This ensures the feature branch is always up-to-date before building.
103
+ ### Question Gates
214
104
 
215
- ### Automatic Loops
105
+ Kody asks before building if something is unclear:
216
106
 
217
- - **Verify + autofix**: If verify fails, runs lint-fix + format-fix + autofix agent, retries up to 2 times
218
- - **Review + fix**: If review verdict is FAIL, runs review-fix agent then re-reviews
107
+ - **Taskify** asks product/requirements questions ("Should search be case-sensitive?")
108
+ - **Plan** asks architecture/technical questions ("Recommend middleware pattern approve?")
109
+ - Pipeline pauses with `kody:waiting` label
110
+ - Resume with `@kody approve` + your answers in the comment body
219
111
 
220
- ## Memory System
112
+ ### Complexity-Based Stage Skipping
221
113
 
222
- Kody maintains project memory in `.kody/memory/`:
114
+ Auto-detected from taskify's risk assessment, or override with `--complexity`:
223
115
 
224
- - **`architecture.md`** auto-detected on `init` (framework, language, testing, directory structure)
225
- - **`conventions.md`** — auto-learned after each successful pipeline run
116
+ | Complexity | Runs | Skips |
117
+ |-----------|------|-------|
118
+ | low | taskify → build → verify → ship | plan, review, review-fix |
119
+ | medium | taskify → plan → build → verify → review → ship | review-fix |
120
+ | high | all 7 stages | nothing |
226
121
 
227
- Memory is prepended to every agent prompt, giving Claude Code project context.
122
+ ### Branch Syncing
228
123
 
229
- ## Configuration Reference
124
+ Every run merges latest from the default branch into the feature branch before building.
230
125
 
231
- ### `kody.config.json`
126
+ ### Verify + Autofix Loop
232
127
 
233
- | Field | Description | Default |
234
- |-------|-------------|---------|
235
- | `quality.typecheck` | Typecheck command | `pnpm -s tsc --noEmit` |
236
- | `quality.lint` | Lint command | `pnpm -s lint` |
237
- | `quality.lintFix` | Lint fix command | `pnpm lint:fix` |
238
- | `quality.format` | Format check command | `""` |
239
- | `quality.formatFix` | Format fix command | `""` |
240
- | `quality.testUnit` | Test command | `pnpm -s test` |
241
- | `git.defaultBranch` | Default branch | `dev` |
242
- | `github.owner` | GitHub org/user | `""` |
243
- | `github.repo` | GitHub repo name | `""` |
244
- | `paths.taskDir` | Task artifacts directory | `.tasks` |
245
- | `agent.modelMap.cheap` | Model for taskify | `haiku` |
246
- | `agent.modelMap.mid` | Model for build/review-fix/autofix | `sonnet` |
247
- | `agent.modelMap.strong` | Model for plan/review (deep reasoning) | `opus` |
128
+ If verify fails: runs lint-fix format-fix → autofix agent → retries (up to 2 attempts).
248
129
 
249
- ### Environment Variables
130
+ ### Review + Fix Loop
250
131
 
251
- | Variable | Required | Description |
252
- |----------|----------|-------------|
253
- | `ANTHROPIC_API_KEY` | Yes | Claude API key (set as repo secret) |
254
- | `GH_TOKEN` | Auto | GitHub token (provided by Actions) |
255
- | `GH_PAT` | No | Personal access token (preferred over GH_TOKEN) |
256
- | `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error` (default: `info`) |
257
- | `LITELLM_BASE_URL` | No | LiteLLM proxy URL for model routing |
132
+ If review verdict is FAIL: runs review-fix agent → re-reviews.
258
133
 
259
- ## Multi-Runner Support
134
+ ### Rich PR Description
260
135
 
261
- Use different agent runners per stage. For example, use OpenCode (MiniMax) for reasoning and Claude Code for code execution:
136
+ ```markdown
137
+ ## What
138
+ Add authentication middleware to 8 unprotected API routes
262
139
 
263
- ```json
264
- {
265
- "agent": {
266
- "defaultRunner": "claude",
267
- "runners": {
268
- "claude": { "type": "claude-code" },
269
- "opencode": { "type": "opencode" }
270
- },
271
- "stageRunners": {
272
- "taskify": "opencode",
273
- "plan": "opencode",
274
- "build": "claude",
275
- "review": "opencode",
276
- "review-fix": "claude",
277
- "autofix": "claude"
278
- }
279
- }
280
- }
281
- ```
140
+ ## Scope
141
+ - `src/middleware/auth.ts`
142
+ - `src/app/api/cron/route.ts`
282
143
 
283
- Available runner types:
284
- - `claude-code` — Claude Code CLI (`claude --print`). Supports tool use (Read, Write, Edit, Bash).
285
- - `opencode` — OpenCode CLI (`opencode github run`). Supports MiniMax, OpenAI, Anthropic, Gemini.
144
+ **Type:** bugfix | **Risk:** high
286
145
 
287
- If no `runners`/`stageRunners` config, defaults to Claude Code for all stages.
146
+ ## Changes
147
+ Added auth middleware to all cron routes and copilotkit endpoint.
288
148
 
289
- ## Complexity-Based Stage Skipping
149
+ **Review:** PASS
150
+ **Verify:** ✅ typecheck + tests + lint passed
290
151
 
291
- Skip stages based on task complexity to save time and cost:
152
+ <details><summary>📋 Implementation plan</summary>
153
+ ...
154
+ </details>
292
155
 
293
- ```bash
294
- # Simple fix — skip plan and review
295
- kody-engine-lite run --task-id fix-typo --task "Fix typo in README" --complexity low
156
+ Closes #42
157
+ ```
296
158
 
297
- # Standard feature — skip review-fix
298
- kody-engine-lite run --task-id add-feature --task "Add search" --complexity medium
159
+ ### Labels
299
160
 
300
- # Complex task — run all stages (default)
301
- kody-engine-lite run --task-id refactor --task "Refactor auth" --complexity high
302
- ```
161
+ `init` creates 14 labels:
162
+ - **Lifecycle:** `kody:planning`, `kody:building`, `kody:review`, `kody:done`, `kody:failed`, `kody:waiting`
163
+ - **Complexity:** `kody:low`, `kody:medium`, `kody:high`
164
+ - **Type:** `kody:feature`, `kody:bugfix`, `kody:refactor`, `kody:docs`, `kody:chore`
303
165
 
304
- | Complexity | Stages | Skipped |
305
- |-----------|--------|---------|
306
- | low | taskify → build → verify → ship | plan, review, review-fix |
307
- | medium | taskify → plan → build → verify → review → ship | review-fix |
308
- | high | taskify → plan → build → verify → review → review-fix → ship | none |
166
+ ### Memory System
309
167
 
310
- If `--complexity` is not provided, it's auto-detected from the taskify stage's `risk_level` output. A complexity label (`kody:low`, `kody:medium`, `kody:high`) is set on the issue.
168
+ `.kody/memory/` files are prepended to every agent prompt:
169
+ - `architecture.md` — auto-generated by `init`
170
+ - `conventions.md` — auto-learned after each successful run
311
171
 
312
- ## LiteLLM (Optional)
172
+ ## Using Non-Anthropic Models (LiteLLM)
313
173
 
314
- For multi-provider model routing with fallback:
174
+ Claude Code can use **any model** through a LiteLLM proxy. Tested with MiniMax (full tool use: Write, Read, Edit, Bash, Grep).
315
175
 
316
176
  ```bash
317
- pip install litellm[proxy]
318
- litellm --config litellm-config.yaml --port 4000
177
+ # Start LiteLLM proxy
178
+ docker run -d -p 4000:4000 \
179
+ -e MINIMAX_API_KEY=your-key \
180
+ -v config.yaml:/app/config.yaml \
181
+ ghcr.io/berriai/litellm:main-latest --config /app/config.yaml
319
182
  ```
320
183
 
321
- Then set in `kody.config.json`:
184
+ ```yaml
185
+ # config.yaml
186
+ model_list:
187
+ - model_name: minimax
188
+ litellm_params:
189
+ model: minimax/MiniMax-M2.7-highspeed
190
+ api_key: os.environ/MINIMAX_API_KEY
191
+ ```
322
192
 
323
193
  ```json
194
+ // kody.config.json
324
195
  {
325
196
  "agent": {
326
197
  "litellmUrl": "http://localhost:4000",
327
- "modelMap": { "cheap": "cheap", "mid": "mid", "strong": "strong" }
198
+ "modelMap": { "cheap": "minimax", "mid": "minimax", "strong": "minimax" }
328
199
  }
329
200
  }
330
201
  ```
331
202
 
332
- ## Task Artifacts
203
+ LiteLLM translates Anthropic's tool-use protocol to the target provider's format. No code changes needed.
333
204
 
334
- Each pipeline run creates artifacts in `.tasks/<task-id>/`:
205
+ ## Configuration
335
206
 
336
- | File | Created by | Content |
337
- |------|-----------|---------|
338
- | `task.md` | entry / issue fetch | Task description |
339
- | `task.json` | taskify stage | Structured classification |
340
- | `plan.md` | plan stage | Implementation steps |
341
- | `verify.md` | verify stage | Quality gate results |
342
- | `review.md` | review stage | Code review + verdict |
343
- | `ship.md` | ship stage | PR URL |
344
- | `status.json` | state machine | Pipeline state (per-stage) |
207
+ ### `kody.config.json`
345
208
 
346
- ## Architecture
209
+ | Field | Description | Default |
210
+ |-------|-------------|---------|
211
+ | `quality.typecheck` | Typecheck command | `pnpm -s tsc --noEmit` |
212
+ | `quality.lint` | Lint command | `""` |
213
+ | `quality.lintFix` | Auto-fix lint | `""` |
214
+ | `quality.testUnit` | Unit test command | `pnpm -s test` |
215
+ | `git.defaultBranch` | Default branch | `dev` |
216
+ | `github.owner` | GitHub org/user | auto-detected |
217
+ | `github.repo` | Repository name | auto-detected |
218
+ | `agent.modelMap.cheap` | Taskify model | `haiku` |
219
+ | `agent.modelMap.mid` | Build/fix model | `sonnet` |
220
+ | `agent.modelMap.strong` | Plan/review model | `opus` |
221
+ | `agent.litellmUrl` | LiteLLM proxy URL | — |
347
222
 
348
- ```
349
- @kody-ade/kody-engine-lite (npm package)
350
- ├── dist/bin/cli.js — CLI entry point
351
- ├── prompts/ — Stage prompt templates
352
- │ ├── taskify.md
353
- │ ├── plan.md
354
- │ ├── build.md
355
- │ ├── review.md
356
- │ ├── review-fix.md
357
- │ └── autofix.md
358
- └── templates/
359
- └── kody.yml — GitHub Actions workflow template
360
- ```
223
+ ### Environment Variables
224
+
225
+ | Variable | Required | Description |
226
+ |----------|----------|-------------|
227
+ | `ANTHROPIC_API_KEY` | Yes | Claude API key (repo secret) |
228
+ | `GH_TOKEN` | Auto | GitHub token (provided by Actions) |
229
+ | `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error` |
361
230
 
362
- Source files (in this repo):
231
+ ## Architecture
363
232
 
364
233
  ```
365
234
  src/
366
- ├── entry.ts — CLI argument parsing, pipeline dispatch
235
+ ├── entry.ts — CLI: run/rerun/fix/status, arg parsing, CI mode
236
+ ├── state-machine.ts — Pipeline loop, stage dispatch, question gates, complexity
237
+ ├── agent-runner.ts — Claude Code subprocess wrapper (thin — spawn, pipe, timeout)
238
+ ├── context.ts — Prompt assembly + memory + task context injection
239
+ ├── definitions.ts — 7-stage pipeline config
367
240
  ├── types.ts — TypeScript interfaces
368
- ├── definitions.ts 7-stage pipeline configuration
369
- ├── state-machine.ts Pipeline orchestration loop
370
- ├── agent-runner.ts Claude Code subprocess wrapper
371
- ├── context.ts — Prompt assembly + task context injection
372
- ├── memory.ts — Project memory reader
373
- ├── config.ts — Config loading (kody.config.json)
374
- ├── logger.ts — Structured logging
375
- ├── preflight.ts — Startup checks
376
- ├── validators.ts — Output validation
241
+ ├── config.ts kody.config.json loader + constants
242
+ ├── git-utils.ts Branch, commit, push, sync, diff
243
+ ├── github-api.ts Issues, labels, PRs, comments via gh CLI
377
244
  ├── verify-runner.ts — Quality gate execution
245
+ ├── validators.ts — Output validation (task.json, plan.md, review.md)
246
+ ├── memory.ts — .kody/memory/ reader
247
+ ├── logger.ts — Structured logging with CI groups
248
+ ├── preflight.ts — Startup health checks
378
249
  ├── kody-utils.ts — Task directory utilities
379
- ├── git-utils.ts Git operations
380
- ├── github-api.ts — GitHub API via gh CLI
381
- └── bin/cli.ts — Package CLI (init, run, version)
250
+ └── bin/cli.ts Package CLI: init (LLM-powered), run, version
382
251
  ```
383
252
 
384
253
  ## Development
385
254
 
386
255
  ```bash
387
- # Install deps
388
- pnpm install
256
+ pnpm install # Install deps
257
+ pnpm typecheck # Type check
258
+ pnpm test # 125 tests (16 files)
259
+ pnpm build # Build npm package
260
+ pnpm kody run ... # Dev mode (tsx)
261
+ npm publish --access public # Publish
262
+ ```
389
263
 
390
- # Type check
391
- pnpm typecheck
264
+ ## Security
392
265
 
393
- # Run locally (dev mode)
394
- pnpm kody run --task-id test --task "Add feature" --cwd /path/to/project
266
+ Only GitHub collaborators (COLLABORATOR, MEMBER, OWNER) can trigger `@kody`. External contributors cannot.
395
267
 
396
- # Build package
397
- pnpm build
268
+ ## License
398
269
 
399
- # Publish
400
- npm publish --access public
401
- ```
270
+ MIT