@kody-ade/kody-engine 0.3.19 → 0.3.21

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.19",
+  version: "0.3.21",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -2671,6 +2671,12 @@ function truncate2(s, maxBytes) {
   if (s.length <= maxBytes) return s;
   return `${s.slice(0, maxBytes)}\u2026 (+${s.length - maxBytes} chars)`;
 }
+function parsePrNumber(url) {
+  const m = url.match(/\/pull\/(\d+)(?:[/?#]|$)/);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
 function getPr(prNumber, cwd) {
   const output = gh2(["pr", "view", String(prNumber), "--json", "number,title,body,headRefName,baseRefName,state"], {
     cwd
@@ -3138,15 +3144,16 @@ var finishFlow = async (ctx, _profile, _agentResult, args) => {
   if (!issueNumber) return;
   const label = typeof args?.label === "string" ? args.label : void 0;
   if (label && label.startsWith(KODY_NAMESPACE)) {
-    setKodyLabel(
-      issueNumber,
-      {
-        label,
-        color: typeof args?.color === "string" ? args.color : void 0,
-        description: typeof args?.description === "string" ? args.description : void 0
-      },
-      ctx.cwd
-    );
+    const spec = {
+      label,
+      color: typeof args?.color === "string" ? args.color : void 0,
+      description: typeof args?.description === "string" ? args.description : void 0
+    };
+    setKodyLabel(issueNumber, spec, ctx.cwd);
+    const prNumber = state?.core.prUrl ? parsePrNumber(state.core.prUrl) : null;
+    if (prNumber && prNumber !== issueNumber) {
+      setKodyLabel(prNumber, spec, ctx.cwd);
+    }
   }
   const icon = STATUS_ICON[reason] ?? "\u2139\uFE0F";
   const prSuffix = state?.core.prUrl ? `
@@ -4044,7 +4051,7 @@ var mirrorStateToPr = async (ctx) => {
   if (!issueNumber || issueTarget !== "issue") return;
   const prUrl = ctx.output.prUrl ?? ctx.data.prResult?.url;
   if (!prUrl) return;
-  const prNumber = parsePrNumber(prUrl);
+  const prNumber = parsePrNumber2(prUrl);
   if (!prNumber) return;
   let state;
   try {
@@ -4062,7 +4069,7 @@ var mirrorStateToPr = async (ctx) => {
     );
   }
 };
-function parsePrNumber(prUrl) {
+function parsePrNumber2(prUrl) {
   const m = prUrl.match(/\/pull\/(\d+)(?:[/?#]|$)/);
   if (!m) return null;
   const n = parseInt(m[1], 10);
@@ -5210,7 +5217,7 @@ var startFlow = async (ctx, profile, _agentResult, args) => {
   postKodyComment(target, issueNumber, state, entry, ctx.cwd);
 };
 function postKodyComment(target, issueNumber, state, next, cwd) {
-  const targetNumber = target === "pr" && state?.core.prUrl ? parsePr2(state.core.prUrl) ?? issueNumber : issueNumber;
+  const targetNumber = target === "pr" && state?.core.prUrl ? parsePrNumber(state.core.prUrl) ?? issueNumber : issueNumber;
   const sub = target === "pr" && state?.core.prUrl ? "pr" : "issue";
   const body = `@kody ${next}`;
   try {
@@ -5226,12 +5233,6 @@ function postKodyComment(target, issueNumber, state, next, cwd) {
     );
   }
 }
-function parsePr2(url) {
-  const m = url.match(/\/pull\/(\d+)(?:[/?#]|$)/);
-  if (!m) return null;
-  const n = parseInt(m[1], 10);
-  return Number.isFinite(n) ? n : null;
-}
 
 // src/scripts/syncFlow.ts
 import { execFileSync as execFileSync19 } from "child_process";

package/package.json

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