@kody-ade/kody-engine 0.2.46 → 0.2.48

package/dist/executables/orchestrator-plan-build-review/profile.json

@@ -0,0 +1,76 @@
+{
+  "name": "orchestrator-plan-build-review",
+  "describe": "Deterministic orchestrator for the plan → build → review (→ fix on concerns/fail) flow. No agent — the postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to drive the flow on."
+    },
+    {
+      "name": "flow",
+      "flag": "--flow",
+      "type": "string",
+      "required": false,
+      "describe": "Flow name (cosmetic — recorded in state.flow.name)."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      { "script": "loadIssueContext" },
+      { "script": "loadTaskState" },
+      { "script": "skipAgent" }
+    ],
+    "postflight": [
+      { "script": "startFlow", "with": { "entry": "plan", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome": null } },
+
+      { "script": "dispatch", "with": { "next": "run", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "PLAN_COMPLETED" } },
+
+      { "script": "dispatch", "with": { "next": "review", "target": "pr" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "RUN_COMPLETED" } },
+
+      { "script": "finishFlow", "with": { "reason": "review-passed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_PASS" } },
+
+      { "script": "dispatch", "with": { "next": "fix", "target": "pr" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["REVIEW_CONCERNS", "REVIEW_FAIL"] } },
+
+      { "script": "finishFlow", "with": { "reason": "review-failed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_FAILED" } },
+
+      { "script": "finishFlow", "with": { "reason": "fix-applied" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "FIX_COMPLETED" } },
+
+      { "script": "finishFlow", "with": { "reason": "aborted" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["PLAN_FAILED", "RUN_FAILED", "FIX_FAILED", "AGENT_NOT_RUN"] } },
+
+      { "script": "persistFlowState" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "FLOW_STARTED",
+      "FLOW_COMPLETED",
+      "FLOW_ABORTED"
+    ]
+  }
+}

package/dist/executables/orchestrator-plan-build-review/prompt.md

@@ -0,0 +1,7 @@
+<!--
+This file exists only because the executor's profile loader expects a
+prompt.md sibling. The orchestrator-plan-build-review executable runs
+with maxTurns: 0 and a `skipAgent` preflight, so this prompt is never
+actually delivered to Claude. The transition logic lives entirely in
+profile.json's postflight entries.
+-->

package/dist/executables/ui-review/profile.json

@@ -0,0 +1,75 @@
+{
+  "name": "ui-review",
+  "describe": "UI/UX review of an open PR: browses the running preview with Playwright, compares behavior to diff intent, posts one structured review comment. Read-only on the repo (no commits); writes a throwaway Playwright spec under .kody2/.",
+  "kind": "oneshot",
+  "inputs": [
+    {
+      "name": "pr",
+      "flag": "--pr",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub PR number to review."
+    },
+    {
+      "name": "previewUrl",
+      "flag": "--preview-url",
+      "type": "string",
+      "required": false,
+      "describe": "Base URL the agent should browse. Falls back to $PREVIEW_URL, then http://localhost:3000."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash",
+      "Write",
+      "Edit"
+    ],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "npx --no-install playwright --version",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "npx --no-install playwright --version",
+      "usage": "Use `npx playwright test <file>` to run a Playwright spec. Write ad-hoc specs under `.kody2/ui-review/*.spec.ts`. If `npx playwright test` errors with `Cannot find package '@playwright/test'`, install it once with `npm install -D @playwright/test` (or the repo's package-manager equivalent) before retrying — the `playwright` browser binaries are already set up by preflight, but the per-repo test framework may not be. Prefer `page.goto(process.env.UI_REVIEW_BASE_URL)` — the base URL is injected as `UI_REVIEW_BASE_URL` at run time. Capture screenshots with `await page.screenshot({ path: '.kody2/ui-review/<name>.png' })` and reference those paths in your final review.",
+      "allowedUses": [
+        "test",
+        "--version"
+      ]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      { "script": "reviewFlow" },
+      { "script": "loadTaskState" },
+      { "script": "loadConventions" },
+      { "script": "discoverQaContext" },
+      { "script": "loadQaGuide" },
+      { "script": "resolvePreviewUrl" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "postReviewResult" },
+      { "script": "saveTaskState" }
+    ]
+  }
+}

package/dist/executables/ui-review/prompt.md

@@ -0,0 +1,103 @@
+You are Kody, a senior UI/UX reviewer. Review PR #{{pr.number}} by reading the diff AND browsing the running app with Playwright. Post ONE structured review comment. Do NOT edit any tracked source files. Do NOT run any `git` or `gh` commands.
+
+You MAY write throwaway Playwright specs and screenshots under `.kody2/ui-review/` — that directory is ignored by the repo.
+
+# PR #{{pr.number}}: {{pr.title}}
+
+Base: {{pr.baseRefName}} ← Head: {{pr.headRefName}}
+
+{{pr.body}}
+
+# Preview URL
+
+`{{previewUrl}}` (resolved from: {{previewUrlSource}})
+
+Before you do anything else, run:
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" --max-time 10 {{previewUrl}}
+```
+
+If the response is not 2xx or 3xx, the preview is unreachable. In that case, SKIP browsing, note the failure in your review under "Browsing", and base your verdict on the diff alone.
+
+# QA context (auto-discovered from the repo)
+
+```
+{{qaContext}}
+```
+
+# QA guide (committed in the repo — authoritative over the auto-discovery above)
+
+{{qaGuide}}
+
+# Diff
+
+```diff
+{{prDiff}}
+```
+
+{{conventionsBlock}}
+
+{{toolsUsage}}
+
+# What to do
+
+1. **Identify UI-affecting changes.** Read the diff. Which pages / components / forms / styles did this PR change? Which user-visible behavior should be verified in the browser? If the diff has no UI surface (pure backend, pure config, pure tests), say so and produce a diff-only review — do not spin up Playwright for nothing.
+
+2. **Plan the browse session.** For each UI-affecting change, pick 1–3 routes from the QA context that exercise it. If the change requires an authenticated role, grab credentials from the QA guide above. If no credentials are available for a role the change depends on, note that as a gap and browse only public pages.
+
+3. **Write a Playwright spec.** Create exactly one file at `.kody2/ui-review/browse.spec.ts`. Use `process.env.UI_REVIEW_BASE_URL` as the base URL. For each route you plan to check, write a test that:
+   - navigates there,
+   - performs the minimum interaction to exercise the change (click, submit, fill),
+   - takes a screenshot at `.kody2/ui-review/<slug>.png`,
+   - asserts at least one piece of visible content so the test fails loudly on a blank / error page.
+
+   Include a `playwright.config.ts` at `.kody2/ui-review/playwright.config.ts` only if you need custom config; otherwise rely on defaults (headless chromium).
+
+4. **Run it.** Invoke:
+
+   ```bash
+   UI_REVIEW_BASE_URL={{previewUrl}} npx playwright test .kody2/ui-review/browse.spec.ts --reporter=line
+   ```
+
+   Capture both stdout and exit code. If Playwright is not installed, the executor will have tried to install it in preflight — if it still fails, report the install error and fall back to a diff-only review.
+
+5. **Inspect screenshots.** Use the Read tool on each `.png` under `.kody2/ui-review/` so the visual state is in your context. Note anything that looks broken, empty, misaligned, or inconsistent with the diff's intent.
+
+6. **Write the review.** Your FINAL MESSAGE must be the markdown review comment — no preamble, no DONE / COMMIT_MSG markers. The entire final message is posted verbatim to the PR.
+
+# Required output format
+
+```
+## Verdict: PASS | CONCERNS | FAIL
+
+_UI review by kody2 — browsed {{previewUrl}}_
+
+### Summary
+<2-3 sentences: what this PR changes in the UI, and whether the running app matches that intent>
+
+### What I browsed
+- `<route>` — <what was checked, with screenshot path>
+- ... (omit this section entirely if the diff had no UI surface)
+
+### UI findings
+- <bullet — cite file:line for code issues; cite route + screenshot for visual issues; say "None." if truly none>
+
+### Code findings
+- <bullets from reading the diff — correctness, a11y, performance, component structure; say "None." if none>
+
+### Gaps
+- <anything you could NOT verify (missing creds, unreachable page, preview down) and why — say "None." if you verified everything relevant>
+
+### Bottom line
+<one sentence>
+```
+
+# Rules
+
+- No commits. No `git` / `gh` invocations. No edits to files outside `.kody2/ui-review/`.
+- Verdict **FAIL** only for clear visual regressions, broken flows, or correctness/accessibility issues that block merge.
+- Verdict **CONCERNS** for clarity/polish/edge-case gaps that shouldn't block.
+- Verdict **PASS** when the PR's UI changes work as intended and nothing obvious is broken.
+- If the preview URL is unreachable, PASS/FAIL should be based on the diff alone, and the "Gaps" section must call that out.
+- Be specific: every finding gets a route + screenshot reference, or a file:line reference. No generic advice.

package/package.json

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

package/dist/executables/orchestrator/profile.json

@@ -1,67 +0,0 @@
-{
-  "name": "orchestrator",
-  "describe": "Drive a chain of kody2 executables by posting @kody2 subcommand comments and polling the task-state comment. Atomic \u2014 one orchestrator run fires one flow.",
-  "inputs": [
-    {
-      "name": "issue",
-      "flag": "--issue",
-      "type": "int",
-      "required": true,
-      "describe": "GitHub issue number to drive."
-    },
-    {
-      "name": "flow",
-      "flag": "--flow",
-      "type": "string",
-      "required": false,
-      "describe": "Named flow to run (e.g. 'plan-then-build'). Defaults to plan-then-build."
-    }
-  ],
-  "claudeCode": {
-    "model": "inherit",
-    "permissionMode": "default",
-    "maxTurns": null,
-    "systemPromptAppend": null,
-    "tools": [
-      "Bash",
-      "Read"
-    ],
-    "hooks": [],
-    "skills": [],
-    "commands": [],
-    "subagents": [],
-    "plugins": [],
-    "mcpServers": []
-  },
-  "cliTools": [],
-  "scripts": {
-    "preflight": [
-      {
-        "script": "loadIssueContext"
-      },
-      {
-        "script": "loadTaskState"
-      },
-      {
-        "script": "composePrompt"
-      }
-    ],
-    "postflight": [
-      {
-        "script": "parseAgentResult"
-      },
-      {
-        "script": "writeRunSummary"
-      },
-      {
-        "script": "saveTaskState"
-      }
-    ]
-  },
-  "output": {
-    "actionTypes": [
-      "ORCHESTRATION_COMPLETED",
-      "ORCHESTRATION_FAILED"
-    ]
-  }
-}

package/dist/executables/orchestrator/prompt.md

@@ -1,56 +0,0 @@
-You are the **kody2 orchestrator** for issue #{{issue.number}} on {{repoOwner}}/{{repoName}}.
-
-Your job: drive a 2-step flow **plan → build** by posting `@kody2 <subcommand>` comments on the issue and watching the state-comment for completion signals. You do NOT edit files. You do NOT run git. You use `gh` (via Bash) only to post comments and read the state-comment.
-
----
-
-# Issue #{{issue.number}}: {{issue.title}}
-
-{{issue.body}}
-
-# Required flow (plan-then-build)
-
-1. **Kick off plan.** Post an issue comment with EXACTLY this body:
-   ```
-   @kody2 plan
-   ```
-   Use: `gh issue comment {{issue.number}} --body "@kody2 plan"` (in the cwd).
-2. **Wait for plan to complete.** Poll the issue's state-comment every ~30s. The state-comment is the one whose body starts with `<!-- kody2:state:v1:begin -->`. Fetch it with:
-   ```
-   gh api repos/{{repoOwner}}/{{repoName}}/issues/{{issue.number}}/comments --paginate --jq '.[] | select(.body | contains("kody2:state:v1:begin")) | .body'
-   ```
-   Parse the JSON block inside the sentinels. Look for `core.lastOutcome.type == "PLAN_COMPLETED"`.
-   If `core.lastOutcome.type == "PLAN_FAILED"` OR if 10 minutes pass without completion → abort with:
-   ```
-   FAILED: plan did not complete (<reason from state or "timeout">)
-   ```
-3. **Kick off build.** Post:
-   ```
-   @kody2 build
-   ```
-   Same `gh issue comment` command.
-4. **Wait for build to complete.** Same poll technique. Look for `core.lastOutcome.type == "RUN_COMPLETED"` (build's success marker) or `RUN_FAILED`. If `RUN_FAILED` or 30 minutes pass → abort with `FAILED: build did not complete (...)`.
-5. **Emit final summary.**
-
-# Required final output
-
-On success:
-
-```
-DONE
-COMMIT_MSG: chore(orchestrator): plan-then-build for #{{issue.number}}
-PR_SUMMARY:
-- Posted `@kody2 plan` and observed PLAN_COMPLETED.
-- Posted `@kody2 build` and observed RUN_COMPLETED.
-- Final PR: <prUrl from state>
-```
-
-On failure, a single line: `FAILED: <concrete reason>`.
-
-# Rules
-
-- NEVER edit files. Read-only flow.
-- NEVER run git. Only `gh` via Bash for comment posting and state polling.
-- Between polls, sleep ~30 seconds. Do NOT poll faster than once every 30 seconds.
-- Hard cap: 40 turns total across the whole flow. If you're approaching the cap, fail early with `FAILED: turn budget exhausted`.
-- If you post an `@kody2` comment and the state-comment does NOT update within the poll window, the child executable likely didn't run — check the GitHub Actions runs tab URL via `gh run list --limit 5 --json conclusion,status,url` to diagnose, then fail with a concrete reason.