@kody-ade/kody-engine 0.3.18 → 0.3.20

package/README.md

@@ -6,73 +6,98 @@
 
 ```
 ┌─────────────────────────────────────────────┐
-│ Consumer repo workflow (.github/kody.yml)  │  triggers on @kody comments
+│ Consumer repo workflow (.github/kody.yml)  │  @kody comments · schedule · release PR merge
 └─────────────────────────────────────────────┘
                     ↓
 ┌─────────────────────────────────────────────┐
 │ kody CLI (@kody-ade/kody-engine)           │
-│   bin/kody.ts — parses argv                │
+│   bin/kody.ts — entrypoint                  │
+│   src/dispatch.ts — profile-driven routing  │
 │   src/executor.ts — runs one profile        │
-│   src/executables/<name>/profile.json       │
-│   src/scripts/*.ts — named hook catalog     │
+│   src/executables/<name>/                   │
+│     profile.json · prompt.md · *.sh         │
+│   src/scripts/*.ts — cross-cutting catalog  │
 └─────────────────────────────────────────────┘
 ```
 
-Every top-level command is its own auto-discovered executable (`run`, `fix`, `fix-ci`, `resolve`, `review`, `sync`, `plan`, `plan-verify`, `orchestrator`, `release`, `watch-*`, `init`). The router has no hardcoded command switch beyond `ci`/`help`/`version` — drop a new `src/executables/<name>/` directory with a `profile.json` + `prompt.md` and `kody <name>` starts working. The executor knows nothing about any specific command.
+Every top-level command is its own auto-discovered executable. The router has **zero executable names hardcoded** — comment dispatch resolves the first token after `@kody` through `config.aliases`, then falls back to `config.defaultExecutable` / `config.defaultPrExecutable`. Drop a new `src/executables/<name>/` directory with a `profile.json` + `prompt.md` (+ any colocated `.sh`) and `kody <name>` starts working.
 
-## Install in a consumer repo
-
-1. Copy `templates/kody.yml` to `.github/workflows/kody.yml`.
-2. Add `agent.model` to `kody.config.json` (see `kody.config.schema.json`).
-3. Secrets on the repo:
-   - At least one model key (e.g. `MINIMAX_API_KEY`, `ANTHROPIC_API_KEY`)
-   - Optional `KODY_TOKEN` PAT if you want kody's pushes to trigger downstream CI
+Executable directories contain **only** three kinds of files: `profile.json` (declaration), `prompt.md` (agent instructions), and `.sh` scripts (mechanical side-effect work). Cross-cutting TypeScript lives in [src/scripts/](src/scripts/); it can't import from `src/executables/` and can't branch on `profile.name`.
 
-## Commands
+## Install in a consumer repo
 
+```bash
+npx -y -p @kody-ade/kody-engine@latest kody init
 ```
-# issue-triggered, agent writes code
-kody run       --issue <N>                              # implement an issue end-to-end (branch, code, PR)
 
-# issue-triggered, agent read-only (no commits)
-kody plan      --issue <N>                              # produce a plan artifact for run
-kody research  --issue <N>                              # map repo context, surface questions/gaps
+`kody init` scaffolds [kody.config.json](kody.config.schema.json), [.github/workflows/kody.yml](templates/kody.yml), per-scheduled-executable workflow files, and (if a UI is detected) `.kody/qa-guide.md` for `ui-review`. Idempotent — pass `--force` to overwrite.
 
-# PR-triggered, agent writes code
-kody fix       --pr    <N> [--feedback ...]             # apply PR review feedback
-kody fix-ci    --pr    <N> [--run-id <ID>]              # fix failing CI
-kody resolve   --pr    <N>                              # merge default branch in, resolve conflicts
+Required repo secrets: at least one model provider key (e.g. `MINIMAX_API_KEY`, `ANTHROPIC_API_KEY`). Recommended: `KODY_TOKEN` PAT so kody's commits trigger downstream CI and can modify `.github/workflows/*`.
 
-# PR-triggered, agent read-only
-kody review    --pr    <N>                              # structured diff review (fast, diff only)
-kody ui-review --pr    <N> [--preview-url <URL>]        # UI/UX review — browses preview via Playwright
+The consumer workflow listens on three triggers: `issue_comment` (for `@kody …` dispatch), `workflow_dispatch` (manual runs, chat mode, mission wake), and `pull_request: [closed]` (auto-finalizes a merged `release/vX.Y.Z` PR).
 
-# no agent (deterministic)
-kody sync      --pr    <N>                              # merge default branch into PR branch
+## Commands
+
+```
+# agent, writes code
+kody run       --issue <N>                             # implement an issue end-to-end
+kody fix       --pr    <N> [--feedback ...]            # apply PR review feedback
+kody fix-ci    --pr    <N> [--run-id <ID>]             # fix failing CI
+kody resolve   --pr    <N> [--prefer ours|theirs]      # merge default branch, resolve conflicts
+
+# agent, read-only
+kody plan      --issue <N>                             # research + implementation plan
+kody research  --issue <N>                             # map repo context, surface gaps
+kody review    --pr    <N>                             # structured diff review
+kody ui-review --pr    <N> [--preview-url <URL>]       # UI review — browses preview via Playwright MCP
+kody classify  --issue <N>                             # pick a flow type (feature/bug/spec/chore)
+
+# flow orchestrators (no agent of their own — transition tables)
+kody feature   --issue <N>                             # research → plan → run → review (→ fix)
+kody bug       --issue <N>                             # plan → run → review (→ fix)
+kody spec      --issue <N>                             # research → plan (no code, terminates at plan)
+kody chore     --issue <N>                             # run → review (→ fix)
+
+# missions & watches (scheduled, coordinate work via issue state)
+kody mission-scheduler                                 # fans out to per-issue mission-tick
+kody mission-tick      --issue <N>                     # one tick of a kody:mission issue
+kody watch-stale-prs                                   # weekly stale-PR report
+
+# deterministic (no agent)
+kody sync      --pr    <N>                             # merge default into PR branch
 kody release   --mode  prepare|finalize [--bump patch|minor|major] [--dry-run]
-kody init      [--force]                                # scaffold consumer repo
-kody orchestrate --issue <N> [--flow plan-build-review] # chain plan → run → review → fix
+kody init      [--force]                               # scaffold consumer repo
 
 # engine entrypoints
-kody ci        --issue <N>                              # CI preflight + auto-dispatch from GHA event
-kody chat      [--session <id>]                         # dashboard-driven chat session
+kody ci                                                # auto-dispatches from the GHA event
+kody chat      [--session <id>]                        # dashboard-driven chat session
 ```
 
+### Flow orchestrators
+
+Each flow (`feature`, `bug`, `spec`, `chore`) is a declarative transition table: postflight entries dispatch the next executable based on `data.taskState.core.lastOutcome.type` via `runWhen`. No engine changes to add a new flow — drop a new `src/executables/<flow-name>/` with a different table. `classify` picks the flow for an unlabeled issue.
+
+### Missions
+
+A **mission** is a stateful, bounded goal expressed as a labeled GitHub issue (`kody:mission`). A **watch** is a stateless repeating loop. A **manager** is a mission whose job happens to be overseeing other missions. All three run on the same scheduled-executable substrate.
+
+`mission-scheduler` wakes on cron (default `*/5 * * * *`) or empty `workflow_dispatch`, finds every open `kody:mission` issue, and calls `mission-tick` once per issue. The tick agent reads the issue body (human-owned prose) and a dedicated state comment (bot-owned JSON), decides the next step, and emits a fenced `kody-mission-next-state` block the postflight persists. Children are spawned via `gh workflow run kody.yml` (not `@kody` comments — the default `GITHUB_TOKEN` can dispatch workflows but can't post auto-triggering comments).
+
 ### `ui-review`
 
-`ui-review` adds UI/UX verification to the review surface. It runs the usual diff-based review AND drives the running preview deployment via the Playwright CLI — writing a throwaway spec under `.kody/ui-review/`, running it, capturing screenshots, and folding the observed behavior into the review verdict.
+Drives the running preview deployment via the Playwright MCP server alongside the usual diff review.
+
+- Preview URL: `--preview-url` → `$PREVIEW_URL` → `http://localhost:3000`. Unreachable → falls back to diff-only.
+- Credentials: `.kody/qa-guide.md` (committed, scaffolded by `kody init` with `CHANGE_ME` placeholders).
+- Auto-discovery: routes, roles, login/admin paths, Payload CMS collections, API routes, env vars — fed to the agent as context.
 
-- Preview URL resolution: `--preview-url` flag → `$PREVIEW_URL` → `http://localhost:3000`.
-- Credentials: committed in `.kody/qa-guide.md` (scaffolded by `kody init` when a UI is detected, with `CHANGE_ME` placeholders). The agent reads the guide and uses any credentials it finds.
-- Auto-discovery: routes, roles, login page, admin path, Payload CMS collections, API routes, env vars — fed to the agent so it knows *what* to browse without you spelling it out.
-- Falls back to a diff-only review when the preview URL is unreachable.
+### `release`
 
-`kody chat` reads `.kody/sessions/<id>.jsonl`, runs one agent turn, appends
-the reply, and writes `chat.message` + `chat.done` events to
-`.kody/events/<id>.jsonl` (plus optional HTTP push to a dashboard ingest URL).
-Inputs can come from flags or env (`SESSION_ID`, `INIT_MESSAGE`, `MODEL`,
-`DASHBOARD_URL`) — the yaml template passes the latter.
+- `--mode prepare` — bumps `package.json`, updates `CHANGELOG.md`, opens a `release/vX.Y.Z` PR. `--bump patch|minor|major` (default `patch`).
+- `--mode finalize` — tags, pushes, runs `prepublishOnly` + `npm publish`, creates a GH release. Runs **automatically** when a `release/vX.Y.Z` PR is merged (via `pull_request: [closed]` in the consumer workflow); manual trigger still works.
 
 ## Profiles
 
-A profile is declarative JSON + an adjacent `prompt.md`. See any directory under `src/executables/` for examples. Adding a new command = new directory + profile + prompt + registering any new scripts under `src/scripts/`. No executor, entry, or dispatch changes.
+A profile is declarative JSON + an adjacent `prompt.md`. See any directory under [src/executables/](src/executables/) for examples. Adding a new command = new directory + profile + prompt + any `.sh` scripts + registering any new shared TS utilities under [src/scripts/](src/scripts/). No executor, entry, or dispatch changes.
+
+See [AGENTS.md](AGENTS.md) for the full architectural contract.

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.18",
+  version: "0.3.20",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -680,8 +680,26 @@ function autoDispatch(opts) {
   if (eventName === "schedule") {
     return { executable: "mission-scheduler", cliArgs: {}, target: 0 };
   }
+  if (eventName === "pull_request") {
+    const merged = event.pull_request?.merged === true;
+    const headRef = String(event.pull_request?.head?.ref ?? "");
+    const prNumber = Number(event.pull_request?.number ?? 0);
+    if (merged && /^release\/v\d+\.\d+\.\d+/.test(headRef) && prNumber > 0) {
+      return {
+        executable: "release",
+        cliArgs: { mode: "finalize", issue: prNumber },
+        target: prNumber
+      };
+    }
+    return null;
+  }
   if (eventName !== "issue_comment") return null;
-  const body = String(event.comment?.body ?? "").toLowerCase();
+  const rawBody = String(event.comment?.body ?? "");
+  const authorLogin = String(event.comment?.user?.login ?? "");
+  const authorType = String(event.comment?.user?.type ?? "");
+  if (!rawBody.toLowerCase().includes("@kody")) return null;
+  if (authorLogin === "kody-bot" || authorType === "Bot") return null;
+  const body = rawBody.toLowerCase();
   const targetNum = Number(event.issue?.number ?? 0);
   const isPr = !!event.issue?.pull_request;
   if (!targetNum) return null;
@@ -6105,6 +6123,11 @@ async function runCi(argv) {
   } catch {
   }
   const autoFallback = !args.issueNumber ? autoDispatch({ config: earlyConfig }) : null;
+  if (!args.issueNumber && !autoFallback && process.env.GITHUB_EVENT_NAME) {
+    process.stdout.write(`\u2192 kody: no action for event ${process.env.GITHUB_EVENT_NAME} \u2014 exiting cleanly
+`);
+    return 0;
+  }
   if (!args.issueNumber && !autoFallback) {
   } else {
     args.errors = args.errors.filter((e) => !e.includes("--issue"));
@@ -6367,7 +6390,11 @@ Exit codes:
 `;
 function parseArgs(argv) {
   const result = { command: "help", errors: [] };
-  if (argv.length === 0) return result;
+  if (argv.length === 0) {
+    if (process.env.SESSION_ID) return { ...result, command: "chat", chatArgv: [] };
+    if (process.env.GITHUB_EVENT_NAME) return { ...result, command: "ci", ciArgv: [] };
+    return result;
+  }
   const cmd = argv[0];
   if (cmd === "help" || cmd === "--help" || cmd === "-h") return { ...result, command: "help" };
   if (cmd === "version" || cmd === "--version" || cmd === "-v") return { ...result, command: "version" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",

package/templates/kody.yml

@@ -1,13 +1,9 @@
 # Drop this file at .github/workflows/kody.yml in your repo.
 #
-# Two triggers, two modes:
-#   - issue_comment / workflow_dispatch with issue_number → `kody ci`
-#     (the @kody issue/PR automation flow)
-#   - workflow_dispatch with sessionId                    → `kody chat`
-#     (dashboard-driven Gemini chat session)
-#
-# All orchestration lives in the kody npm package; future capabilities ship
-# via `npm publish`, not by editing this file.
+# Triggers forward every relevant event to `kody`; the engine decides what
+# (if anything) to do. The job runs `npx kody` — no shell branching, no
+# routing logic in YAML. All orchestration lives in the kody npm package;
+# future capabilities ship via `npm publish`, not by editing this file.
 #
 # Required repo secrets: at least one model provider key (e.g. MINIMAX_API_KEY,
 # ANTHROPIC_API_KEY). kody reads any *_API_KEY secret automatically via
@@ -49,15 +45,12 @@ on:
         default: ""
   issue_comment:
     types: [created]
+  pull_request:
+    types: [closed]
 
 jobs:
   run:
-    if: >-
-      ${{ github.event_name == 'workflow_dispatch' ||
-          (github.event_name == 'issue_comment' &&
-            contains(github.event.comment.body, '@kody') &&
-            github.event.comment.user.login != 'kody-bot' &&
-            github.event.comment.user.type != 'Bot') }}
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.merged == true }}
     runs-on: ubuntu-latest
     timeout-minutes: 360
     concurrency:
@@ -71,6 +64,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ github.event.pull_request.base.ref || github.ref }}
           token: ${{ secrets.KODY_TOKEN || github.token }}
 
       - uses: actions/setup-node@v4
@@ -92,9 +86,4 @@ jobs:
           INIT_MESSAGE:  ${{ inputs.message }}
           MODEL:         ${{ inputs.model }}
           DASHBOARD_URL: ${{ inputs.dashboardUrl }}
-        run: |
-          if [ -n "$SESSION_ID" ]; then
-            npx -y -p @kody-ade/kody-engine@latest kody chat
-          else
-            npx -y -p @kody-ade/kody-engine@latest kody ci
-          fi
+        run: npx -y -p @kody-ade/kody-engine@latest kody