@kody-ade/engine 0.1.0

package/kody.config.schema.json

@@ -0,0 +1,299 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Kody Engine Lite Configuration",
+  "description": "Configuration for the Kody autonomous SDLC pipeline. See https://github.com/aharonyaircohen/Kody-Engine-Lite",
+  "type": "object",
+  "properties": {
+    "quality": {
+      "type": "object",
+      "description": "Quality gate commands run during the verify stage. Leave empty string to skip.",
+      "properties": {
+        "typecheck": {
+          "type": "string",
+          "description": "TypeScript type checking command (e.g., 'pnpm typecheck', 'pnpm tsc --noEmit')",
+          "default": "pnpm -s tsc --noEmit"
+        },
+        "lint": {
+          "type": "string",
+          "description": "Lint command (e.g., 'pnpm lint'). Empty to skip.",
+          "default": ""
+        },
+        "lintFix": {
+          "type": "string",
+          "description": "Auto-fix lint command, run when verify fails (e.g., 'pnpm lint:fix')",
+          "default": ""
+        },
+        "formatFix": {
+          "type": "string",
+          "description": "Auto-fix format command, run when verify fails (e.g., 'pnpm format')",
+          "default": ""
+        },
+        "testUnit": {
+          "type": "string",
+          "description": "Unit test command. Use test:unit to exclude integration/e2e tests (e.g., 'pnpm test:unit')",
+          "default": "pnpm -s test"
+        }
+      },
+      "additionalProperties": false
+    },
+    "git": {
+      "type": "object",
+      "description": "Git configuration",
+      "properties": {
+        "defaultBranch": {
+          "type": "string",
+          "description": "Default branch for PR base and branch syncing (e.g., 'main', 'dev')",
+          "default": "dev"
+        }
+      },
+      "additionalProperties": false
+    },
+    "github": {
+      "type": "object",
+      "description": "GitHub repository settings. Auto-detected from git remote by init.",
+      "properties": {
+        "owner": {
+          "type": "string",
+          "description": "GitHub organization or username (e.g., 'my-org')"
+        },
+        "repo": {
+          "type": "string",
+          "description": "GitHub repository name (e.g., 'my-repo')"
+        },
+        "postSummary": {
+          "type": "boolean",
+          "description": "Post a structured pipeline summary comment on the issue after completion. Default: true in CI, false locally.",
+          "default": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "timeouts": {
+      "type": "object",
+      "description": "Per-stage timeout overrides in seconds. Defaults: taskify=600, plan=600, build=2400, verify=300, review=600, review-fix=1200, ship=240",
+      "properties": {
+        "taskify": { "type": "number", "description": "Taskify stage timeout in seconds", "default": 600 },
+        "plan": { "type": "number", "description": "Plan stage timeout in seconds", "default": 600 },
+        "build": { "type": "number", "description": "Build stage timeout in seconds", "default": 2400 },
+        "verify": { "type": "number", "description": "Verify stage timeout in seconds", "default": 300 },
+        "review": { "type": "number", "description": "Review stage timeout in seconds", "default": 600 },
+        "review-fix": { "type": "number", "description": "Review-fix stage timeout in seconds", "default": 1200 },
+        "ship": { "type": "number", "description": "Ship stage timeout in seconds", "default": 240 }
+      },
+      "additionalProperties": false
+    },
+    "agent": {
+      "type": "object",
+      "description": "Agent execution configuration",
+      "properties": {
+        "modelMap": {
+          "type": "object",
+          "description": "Maps model tiers to actual model names. When provider is set, values should be the provider's model names.",
+          "properties": {
+            "cheap": {
+              "type": "string",
+              "description": "Fast/cheap model for taskify stage (e.g., 'haiku' or provider model name)",
+              "default": "haiku"
+            },
+            "mid": {
+              "type": "string",
+              "description": "Mid-tier model for build, review-fix, autofix (e.g., 'sonnet' or provider model name)",
+              "default": "sonnet"
+            },
+            "strong": {
+              "type": "string",
+              "description": "Strongest model for plan, review — deep reasoning (e.g., 'opus' or provider model name)",
+              "default": "opus"
+            }
+          },
+          "additionalProperties": false
+        },
+        "provider": {
+          "type": "string",
+          "description": "LLM provider name. When set (and not 'anthropic'), engine auto-starts LiteLLM proxy and routes model calls to this provider. modelMap values should be the provider's model names.",
+          "examples": ["anthropic", "minimax", "openai", "google"]
+        },
+        "defaultRunner": {
+          "type": "string",
+          "description": "Name of the default runner when multiple runners are configured (advanced)",
+          "default": "claude"
+        },
+        "runners": {
+          "type": "object",
+          "description": "Named runner definitions (advanced)",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["claude-code"]
+              }
+            },
+            "required": ["type"]
+          }
+        },
+        "stageRunners": {
+          "type": "object",
+          "description": "Per-stage runner assignment (advanced). Maps stage name to runner name.",
+          "properties": {
+            "taskify": { "type": "string" },
+            "plan": { "type": "string" },
+            "build": { "type": "string" },
+            "autofix": { "type": "string" },
+            "review": { "type": "string" },
+            "review-fix": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "default": {
+          "type": "object",
+          "description": "Default provider + model for all stages. Overridden by per-stage entries in 'stages'.",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "description": "Provider name: 'claude' for direct Anthropic API, anything else routes through LiteLLM proxy",
+              "examples": ["claude", "minimax", "openai", "google"]
+            },
+            "model": {
+              "type": "string",
+              "description": "Full model ID (e.g., 'claude-sonnet-4-6', 'gpt-4o')"
+            }
+          },
+          "required": ["provider", "model"],
+          "additionalProperties": false
+        },
+        "stages": {
+          "type": "object",
+          "description": "Per-stage provider + model overrides. Takes precedence over 'default' and 'modelMap'.",
+          "properties": {
+            "taskify": { "$ref": "#/properties/agent/properties/default" },
+            "plan": { "$ref": "#/properties/agent/properties/default" },
+            "build": { "$ref": "#/properties/agent/properties/default" },
+            "verify": { "$ref": "#/properties/agent/properties/default" },
+            "review": { "$ref": "#/properties/agent/properties/default" },
+            "review-fix": { "$ref": "#/properties/agent/properties/default" },
+            "ship": { "$ref": "#/properties/agent/properties/default" }
+          },
+          "additionalProperties": false
+        },
+        "escalateOnTimeout": {
+          "type": "boolean",
+          "description": "Escalate to a stronger model tier when a stage times out and retries. Default: true.",
+          "default": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "watch": {
+      "type": "object",
+      "description": "Kody Watch — periodic health monitoring. Runs every 30 minutes via GitHub Actions to check pipeline health, security, and configuration.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable Kody Watch periodic monitoring",
+          "default": false
+        },
+        "digestIssue": {
+          "type": "number",
+          "description": "GitHub issue number for posting digest reports. Auto-created by bootstrap."
+        },
+        "model": {
+          "type": "string",
+          "description": "Model for watch agents. When provider is set in agent config, this should be the provider's model name. Falls back to agent.modelMap.cheap if not set.",
+          "examples": ["claude-sonnet-4-6", "claude-haiku-4-5-20251001", "MiniMax-M1"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "mcp": {
+      "type": "object",
+      "description": "MCP (Model Context Protocol) server configuration. Enables external tools like browser automation.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable MCP server integration",
+          "default": false
+        },
+        "servers": {
+          "type": "object",
+          "description": "Named MCP server definitions. Each key is a server name.",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string",
+                "description": "Command to start the MCP server (e.g., 'npx')"
+              },
+              "args": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Command arguments"
+              },
+              "env": {
+                "type": "object",
+                "additionalProperties": { "type": "string" },
+                "description": "Environment variables for the server process"
+              }
+            },
+            "required": ["command"]
+          }
+        },
+        "stages": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Stages that can use MCP tools. Defaults to [\"build\", \"verify\", \"review\", \"review-fix\"]",
+          "default": ["build", "verify", "review", "review-fix"]
+        },
+        "devServer": {
+          "type": "object",
+          "description": "DEPRECATED: Use top-level devServer instead. Kept for backward compatibility.",
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "Command to start the dev server (e.g., 'pnpm dev')"
+            },
+            "url": {
+              "type": "string",
+              "description": "URL where the dev server will be accessible (e.g., 'http://localhost:3000')"
+            },
+            "readyPattern": {
+              "type": "string",
+              "description": "Regex pattern to match in stdout when server is ready. Default: 'Ready in|compiled|started server|Local:'"
+            },
+            "readyTimeout": {
+              "type": "number",
+              "description": "Seconds to wait for the server to be ready. Default: 180"
+            }
+          },
+          "required": ["command", "url"]
+        }
+      },
+      "required": ["enabled", "servers"],
+      "additionalProperties": false
+    },
+    "devServer": {
+      "type": "object",
+      "description": "Dev server configuration for browser tool verification. Works with any provider (MCP or CLI-based).",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Command to start the dev server (e.g., 'pnpm dev')"
+        },
+        "url": {
+          "type": "string",
+          "description": "URL where the dev server will be accessible (e.g., 'http://localhost:3000')"
+        },
+        "readyPattern": {
+          "type": "string",
+          "description": "Regex pattern to match in stdout when server is ready. Default: 'Ready in|compiled|started server|Local:'"
+        },
+        "readyTimeout": {
+          "type": "number",
+          "description": "Seconds to wait for the server to be ready. Default: 180"
+        }
+      },
+      "required": ["command", "url"]
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kody-ade/engine",
+  "version": "0.1.0",
+  "description": "Kody ADE — the free, autonomous development engine. Issue to tested, reviewed PR.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kody-engine": "./dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "templates",
+    "kody.config.schema.json"
+  ],
+  "scripts": {
+    "kody": "tsx src/entry.ts",
+    "claude": "tsx scripts/kody.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build",
+    "release": "npm publish --access public && bash scripts/wait-for-npm.sh"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.7",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "~5.7.0",
+    "vitest": "^4.1.1"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/prompts/autofix.md

@@ -0,0 +1,52 @@
+---
+name: autofix
+description: Investigate root cause then fix verification errors (typecheck, lint, test failures)
+mode: primary
+tools: [read, write, edit, bash, glob, grep]
+---
+
+You are an autofix agent following the Superpowers Systematic Debugging methodology. The verification stage failed. Fix the errors below.
+
+IRON LAW: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. If you haven't completed Phase 1, you cannot propose fixes.
+
+## Phase 1 — Root Cause Investigation (BEFORE any edits)
+1. Read the full error output — what exactly failed? Full stack traces, line numbers, error codes.
+2. Identify the affected files — Read them to understand context.
+3. Check recent changes: run `git diff HEAD~1` to see what changed.
+4. Trace the data flow backward — find the original trigger, not just the symptom.
+5. Classify the failure pattern:
+   - **Type error**: mismatched types, missing properties, wrong generics
+   - **Test failure**: assertion mismatch, missing mock, changed behavior
+   - **Lint error**: style violation, unused import, naming convention
+   - **Runtime error**: null reference, missing dependency, config issue
+   - **Integration failure**: API contract mismatch, schema drift
+6. Identify root cause — is this a direct error in new code, or a side effect of a change elsewhere?
+
+## Phase 2 — Pattern Analysis
+1. Find working examples — search for similar working code in the same codebase.
+2. Compare against the working version — what's different?
+3. Form a single hypothesis: "I think X is the root cause because Y."
+
+## Phase 3 — Fix (only after root cause is clear)
+1. Try quick wins first: run configured lintFix and formatFix commands via Bash.
+2. Implement a single fix — ONE change at a time, not multiple changes at once.
+3. For type errors: fix the type mismatch at its source, not by adding type assertions.
+4. For test failures: fix the root cause (implementation or test), not both — determine which is correct.
+5. For lint errors: apply the specific fix the linter suggests.
+6. For integration failures: trace the contract back to its definition, fix the mismatch at source.
+7. After EACH fix, re-run the failing command to verify it passes.
+8. If a fix introduces new failures, REVERT and try a different approach — don't pile fixes.
+9. Do NOT commit or push — the orchestrator handles git.
+
+## Red Flags — STOP and return to Phase 1 if you catch yourself:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see"
+- "I don't fully understand but this might work"
+- Proposing solutions before tracing the data flow
+
+## Rules
+- Fix ONLY the reported errors. Do NOT make unrelated changes.
+- Minimal diff — use Edit for surgical changes, not Write for rewrites.
+- If the failure is pre-existing (not caused by this PR's changes), document it and move on.
+
+{{TASK_CONTEXT}}

package/prompts/build.md

@@ -0,0 +1,26 @@
+---
+name: build
+description: Implement code changes following Superpowers Executing Plans methodology
+mode: primary
+tools: [read, write, edit, bash, glob, grep]
+---
+
+You are a code implementation agent following the Superpowers Executing Plans methodology.
+
+CRITICAL RULES:
+1. Follow the plan EXACTLY — step by step, in order. Do not skip or reorder steps.
+2. Read existing code BEFORE modifying (use Read tool first, always).
+3. Verify each step after completion (use Bash to run tests/typecheck).
+4. Write COMPLETE, working code — no stubs, no TODOs, no placeholders.
+5. Do NOT commit or push — the orchestrator handles git.
+6. If the plan says to write tests first, write tests first.
+7. Document any deviations from the plan (if absolutely necessary).
+
+Implementation discipline:
+- Use Edit for surgical changes to existing files (prefer over Write for modifications)
+- Use Write only for new files
+- Run `pnpm test` after each logical group of changes
+- Run `pnpm tsc --noEmit` periodically to catch type errors early
+- If a test fails after your change, fix it immediately — don't continue
+
+{{TASK_CONTEXT}}

package/prompts/decompose.md

@@ -0,0 +1,77 @@
+---
+name: decompose
+description: Analyze implementation plan and decompose into parallel sub-tasks
+mode: primary
+tools: [read, glob, grep]
+---
+
+You are a task decomposition agent. You analyze an implementation plan and determine whether it can be split into independent sub-tasks that can be built in parallel.
+
+## Input
+
+You receive the full implementation plan (plan.md) and task classification (task.json) via the task context below.
+
+## Analysis Process
+
+1. **Parse plan steps** — identify each `## Step N` or numbered implementation step with its target files
+2. **Map file dependencies** — for each step, identify which files it reads from vs writes to
+3. **Detect coupling** — steps that share files, or where one step's output is another's input, are coupled
+4. **Cluster into groups** — group tightly-coupled steps together; independent groups become sub-tasks
+5. **Score complexity** — rate 1-10 based on: file count, directory spread, inter-step coupling, risk level
+
+## Scoring Guide
+
+| Score | Description | Decompose? |
+|-------|-------------|------------|
+| 1-3   | Simple: few files, single area | No |
+| 4-5   | Moderate: several files, some coupling | Usually no |
+| 6-7   | Complex: many files, multiple areas, manageable coupling | Yes (2 sub-tasks) |
+| 8-9   | Very complex: many files, multiple domains, some coupling | Yes (2-3 sub-tasks) |
+| 10    | Extremely complex: cross-cutting, many domains | Yes (3-4 sub-tasks) |
+
+## Rules
+
+- Maximum 4 sub-tasks (more causes merge complexity that outweighs parallelism benefit)
+- Each sub-task MUST have exclusive file ownership — no file appears in two sub-tasks' scope
+- Each plan step MUST be assigned to exactly one sub-task — no step in two sub-tasks' plan_steps
+- If steps are tightly coupled (shared files, import chains), they MUST be in the same sub-task
+- Set `decomposable: false` when: score < 6, fewer than 4 files total, or all steps are tightly coupled
+- `depends_on` should reference sub-task IDs that must complete first (empty = fully independent)
+- `shared_context` describes what this sub-task needs to know about sibling sub-tasks' work
+
+## Output
+
+Output ONLY valid JSON. No markdown fences. No explanation. No extra text before or after the JSON.
+
+```json
+{
+  "decomposable": true,
+  "reason": "Plan steps cluster into N independent groups by file ownership...",
+  "complexity_score": 7,
+  "recommended_subtasks": 2,
+  "sub_tasks": [
+    {
+      "id": "part-1",
+      "title": "Short descriptive title",
+      "description": "What this sub-task implements and why",
+      "scope": ["src/path/file1.ts", "src/path/file2.ts"],
+      "plan_steps": [1, 2, 3],
+      "depends_on": [],
+      "shared_context": "Uses TypeFoo defined in part-2's scope — import will resolve after merge"
+    }
+  ]
+}
+```
+
+When not decomposable:
+```json
+{
+  "decomposable": false,
+  "reason": "All plan steps share src/core/main.ts — cannot split without file conflicts",
+  "complexity_score": 4,
+  "recommended_subtasks": 1,
+  "sub_tasks": []
+}
+```
+
+{{TASK_CONTEXT}}

package/prompts/plan.md

@@ -0,0 +1,65 @@
+---
+name: plan
+description: Create a step-by-step implementation plan following Superpowers Writing Plans methodology
+mode: primary
+tools: [read, glob, grep]
+---
+
+You are a planning agent following the Superpowers Writing Plans methodology.
+
+## MANDATORY: Pattern Discovery Before Planning
+
+Before writing ANY plan, you MUST search for existing patterns in the codebase:
+
+1. **Find similar implementations** — Grep/Glob for how the same problem is already solved elsewhere. E.g., if the task involves localization, search for how other collections handle localization. If adding auth, find existing auth patterns.
+2. **Reuse existing patterns** — If the codebase already solves a similar problem, your plan MUST follow that pattern unless there's a strong reason not to (document the reason in Questions).
+3. **Check decisions.md** — If `.kody/memory/decisions.md` exists, read it for prior architectural decisions that may apply.
+4. **Never invent when you can reuse** — Proposing a new pattern when an existing one covers the use case is a planning failure.
+
+After pattern discovery, examine the codebase to understand existing code structure, patterns, and conventions. Use Read, Glob, and Grep.
+
+Output a markdown plan. Start with the steps, then optionally add a Questions section at the end.
+
+## Step N: <short description>
+**File:** <exact file path>
+**Change:** <precisely what to do>
+**Why:** <rationale>
+**Verify:** <command to run to confirm this step works>
+
+Superpowers Writing Plans rules:
+1. TDD ordering — write tests BEFORE implementation
+2. Each step completable in 2-5 minutes (bite-sized)
+3. Exact file paths — not "the test file" but "src/utils/foo.test.ts"
+4. Include COMPLETE code for new files (not snippets or pseudocode)
+5. Include verification step for each task (e.g., "Run `pnpm test` to confirm")
+6. Order for incremental building — each step builds on the previous
+7. If modifying existing code, show the exact function/line to change
+8. Keep it simple — avoid unnecessary abstractions (YAGNI)
+
+If there are architecture decisions or technical tradeoffs that need input, add a Questions section at the END of your plan:
+
+## Questions
+
+- <question about architecture decision or tradeoff>
+
+Questions rules:
+- ONLY ask about significant architecture/technical decisions that affect the implementation
+- Ask about: design pattern choice, database schema decisions, API contract changes, performance tradeoffs
+- Recommend an approach with rationale — don't just ask open-ended questions
+- Do NOT ask about requirements — those should be clear from task.json
+- Do NOT ask about things you can determine from the codebase
+- If no questions, omit the Questions section entirely
+- Maximum 3 questions — only decisions with real impact
+
+Good questions: "Recommend middleware pattern vs wrapper — middleware is simpler but wrapper allows caching. Approve middleware?"
+Bad questions: "What should I name the function?", "Should I add tests?"
+
+## Pattern Discovery Report
+
+After the plan steps and before Questions, include a brief report of what existing patterns you found and how your plan reuses them:
+
+## Existing Patterns Found
+- <pattern found>: <how it's reused in the plan>
+- <if no existing patterns found, explain what you searched for>
+
+{{TASK_CONTEXT}}

package/prompts/review-fix.md

@@ -0,0 +1,27 @@
+---
+name: review-fix
+description: Fix Critical and Major issues found during code review
+mode: primary
+tools: [read, write, edit, bash, glob, grep]
+---
+
+You are a review-fix agent following the Superpowers Executing Plans methodology.
+
+The code review found issues that need fixing. Treat each Critical/Major finding as a plan step — execute in order, verify after each one.
+
+RULES (Superpowers Executing Plans discipline):
+1. Fix ONLY Critical and Major issues (ignore Minor findings)
+2. Use Edit for surgical changes — do NOT rewrite entire files
+3. Run tests after EACH fix to verify nothing breaks
+4. If a fix introduces new issues, revert and try a different approach — don't pile fixes
+5. Document any deviations from the expected fix
+6. Do NOT commit or push — the orchestrator handles git
+
+For each Critical/Major finding:
+1. Read the affected file to understand full context
+2. Understand the root cause — don't just patch the symptom
+3. Make the minimal change to fix the issue
+4. Run tests to verify the fix
+5. Move to the next finding
+
+{{TASK_CONTEXT}}