@kodus/cli 0.4.4 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kodus/cli",
-    "version": "0.4.4",
+    "version": "0.4.7",
     "description": "Kodus CLI - AI-powered code review from your terminal",
     "type": "module",
     "bin": {
@@ -24,11 +24,13 @@
         "test": "vitest run",
         "test:watch": "vitest",
         "test:integration": "yarn build && vitest run --config vitest.integration.config.ts",
+        "test:installer": "sh tests/install_business_rules_validation_test.sh",
         "lint": "eslint src --ext .ts",
         "lint:fix": "eslint src --ext .ts --fix",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "check": "yarn format:check && yarn lint",
+        "skills:sync": "node scripts/sync-skills-aliases.mjs",
         "skills:validate": "node scripts/validate-skills.mjs",
         "skills:prompt": "node scripts/skills-to-prompt.mjs --format=xml",
         "skills:prompt:json": "node scripts/skills-to-prompt.mjs --format=json",
@@ -51,13 +53,13 @@
         "clipboardy": "^5.3.1",
         "commander": "^14.0.3",
         "execa": "^9.6.1",
-        "figlet": "^1.10.0",
+        "figlet": "^1.11.0",
         "gradient-string": "^3.0.0",
         "latest-version": "^9.0.0",
         "node-machine-id": "^1.1.12",
         "open": "^11.0.0",
         "ora": "^9.3.0",
-        "simple-git": "^3.32.3",
+        "simple-git": "^3.33.0",
         "update-notifier": "^7.3.1",
         "yaml": "^2.8.2"
     },
@@ -65,12 +67,12 @@
         "@eslint/js": "^10.0.1",
         "@types/figlet": "^1.7.0",
         "@types/gradient-string": "^1.1.6",
-        "@types/node": "^25.3.3",
+        "@types/node": "^25.4.0",
         "@types/update-notifier": "^6.0.8",
-        "@typescript-eslint/eslint-plugin": "^8.56.1",
-        "@typescript-eslint/parser": "^8.56.1",
-        "eslint": "^10.0.2",
-        "prettier": "^3.6.2",
+        "@typescript-eslint/eslint-plugin": "^8.57.0",
+        "@typescript-eslint/parser": "^8.57.0",
+        "eslint": "^10.0.3",
+        "prettier": "^3.8.1",
         "typescript": "^5.9.3",
         "vitest": "^4.0.18"
     },

package/skills/README.md

@@ -8,8 +8,8 @@ This directory contains the agent skills shipped with the Kodus CLI repository.
     - Run local Kodus code review for workspace changes with the installed CLI.
 - `kodus-review-dev`
     - Run the local Kodus CLI build against a dev/localhost API using `scripts/run-local-cli.sh` (explicit dev request only).
-- `business-rules-validation`
-    - Run business rules validation from local diff scope with `kodus pr business-validation`.
+- `kodus-business-rules-validation`
+    - Canonical skill name for business rules validation in installers and multi-agent integrations.
 - `kodus-pr-suggestions-resolver`
     - Fetch PR suggestions and apply fixes with judgment.
 
@@ -20,10 +20,12 @@ This directory contains the agent skills shipped with the Kodus CLI repository.
     - If the request is delivery action (commit/push/merge) and no fresh review ran, ask to run Kodus review first.
 - User explicitly mentions local/dev CLI execution (`node dist/index.js`, `localhost:3001`, `KODUS_API_URL`, dev API/QA API)
     - Use `kodus-review-dev` instead of `kodus-review`.
-- User mentions `business validation`, `acceptance criteria`, `local diff vs task`, `kodus pr business-validation`
-    - Use `business-rules-validation`.
+- User mentions `business validation`, `acceptance criteria`, `local diff vs task`, `implementation vs task`, `kodus pr business-validation`
+    - Use `kodus-business-rules-validation`.
 - User asks to apply Kodus PR suggestions
     - Use `kodus-pr-suggestions-resolver`.
+- User asks to validate local implementation against a task, acceptance criteria, or business rules
+    - Use `kodus-business-rules-validation`.
 
 ## Notes
 
@@ -31,12 +33,17 @@ This directory contains the agent skills shipped with the Kodus CLI repository.
 - Some skills include helper scripts in `skills/<skill-name>/scripts/`.
 - Packaging these files in the npm artifact makes them available to external installers and local integration tooling.
 - Shipping the files here does not, by itself, install them into Claude Code, Cursor, Codex, or other agents. That installation step still depends on the integration tooling you use.
-- `kodus update` upgrades the CLI package only. Skill sync/deployment should be done via the installer tooling (for example `curl -fsSL https://review-skill.com/install | bash`).
+- `kodus skills install` installs bundled skills in detected local agent roots.
+- `kodus skills resync` re-syncs bundled skills in detected local agent directories.
+- `kodus skills uninstall` removes bundled managed skills from detected local agent directories.
+- For full multi-agent bootstrap/setup, use the platform installer tooling (`install.sh` for macOS/Linux, `install.ps1` for Windows PowerShell).
 
 ## For Integrators
 
 - Validate skill structure and metadata:
     - `npm run skills:validate`
+- Sync legacy alias folders from canonical skills:
+    - `npm run skills:sync`
 - Generate prompt metadata as XML (`<available_skills>`):
     - `npm run skills:prompt`
 - Generate prompt metadata as JSON:

package/skills/kodus-business-rules-validation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: kodus-business-rules-validation
+description: Use when the user wants Kodus to validate local diff changes against task requirements, acceptance criteria, or business rules via `kodus pr business-validation`, especially for implementation-vs-task or merge readiness checks.
+license: MIT
+compatibility: Requires Kodus CLI auth plus Kodus task-management integration (Jira/Linear/Notion/ClickUp) for useful task context retrieval.
+metadata:
+    author: Kodus
+    version: '1.0'
+---
+
+# Kodus Business Rules Validation
+
+## Goal
+
+Run Kodus business-rules validation from the current repository diff only.
+
+## Required Inputs
+
+- One local diff scope:
+    - default working tree diff
+    - or `--staged`
+    - or `--branch <name>`
+    - or `--commit <sha>`
+    - or `[files...]`
+- Optional task reference:
+    - `--task-url <url>` or `--task-id <id>`
+    - Do not pass both.
+
+## When to Use
+
+- The user asks for business-validation, business validation, business rules validation, or acceptance-criteria validation
+- The user wants to check local implementation vs task requirements
+- The user mentions local business validation or `kodus pr business-validation`
+
+Do not use this skill as a substitute for `kodus review`. Local review and business-rules validation are different flows.
+
+## Workflow
+
+1. Choose the local scope.
+
+- Default working tree diff when no scope flag is provided.
+- Use only one of `--staged`, `--branch`, `--commit`, or `[files...]`.
+
+2. Build and run the command.
+
+Examples:
+
+```bash
+kodus pr business-validation
+kodus pr business-validation --staged --task-id KC-1441
+kodus pr business-validation --branch main --task-id KC-1441
+kodus pr business-validation --commit HEAD~1 --task-id KC-1441
+kodus pr business-validation src/service.ts src/use-case.ts --task-id KC-1441
+```
+
+3. Interpret the result.
+
+- `Mode: local diff` means validation over the provided local diff scope.
+- If output says missing MCP/task context, report that directly and request integration/context setup.
+
+## Notes
+
+- `kodus review` does not trigger this flow.
+- Prefer `--task-id` or `--task-url` when the task is not obvious from local context.
+- `KC-1441`-style keys are valid.

package/skills/kodus-pr-suggestions-resolver/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kodus-pr-suggestions-resolver
-description: Use when asked to fetch `kodus pr suggestions` for a PR URL/number/repo-id, analyze each suggestion against PR intent, implement reasonable fixes, run build/tests when available, and report what was done or skipped. Not for generic local `kodus review`.
+description: Use when the user wants to fetch, triage, or implement Kodus suggestions for an existing remote pull request via `kodus pr suggestions`, `--pr-url`, or `--pr-number`.
 ---
 
 # Kodus PR Suggestions Resolver
@@ -14,8 +14,8 @@ Fetch PR suggestions via Kodus CLI, triage each suggestion against the PR goal,
 ### 1) Collect the PR target
 
 - If the user did not provide a target, ask for one of:
-  - `--pr-url <url>`
-  - `--pr-number <number>` with `--repo-id <id>`
+    - `--pr-url <url>`
+    - `--pr-number <number>` with `--repo-id <id>`
 - If multiple are provided, prefer `--pr-url`.
 
 ### 2) Run Kodus suggestions
@@ -36,9 +36,9 @@ kodus pr suggestions --pr-number <number> --repo-id <id>
 
 - Extract or confirm the PR goal from the user or PR context.
 - For each suggestion:
-  - Verify it does not conflict with the PR objective.
-  - Prefer small, low-risk changes that improve the PR without changing scope.
-  - Skip suggestions that are irrelevant, risky, or scope-expanding; note why.
+    - Verify it does not conflict with the PR objective.
+    - Prefer small, low-risk changes that improve the PR without changing scope.
+    - Skip suggestions that are irrelevant, risky, or scope-expanding; note why.
 
 ### 4) Apply fixes one by one
 

package/skills/kodus-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kodus-review
-description: Use when asked to review code with Kodus, run `kodus review`, use `--prompt-only`, or act on Kodus review results. Run the Kodus CLI review flow and apply fixes based on CLI output. Not for local dev CLI flow, PR suggestions, or business validation.
+description: Use when the user wants Kodus to review local changes, run `kodus review` or `--prompt-only`, fix Kodus review findings, or check commit, push, or merge readiness.
 ---
 
 # Kodus Review
@@ -9,32 +9,45 @@ description: Use when asked to review code with Kodus, run `kodus review`, use `
 
 Use the Kodus CLI to review changes and resolve issues. Prefer machine-friendly output via `--prompt-only`, then apply fixes in code.
 
+If the request is to validate local changes against business rules, task requirements, or acceptance criteria, use `kodus-business-rules-validation` instead. `kodus review` does not trigger local business validation.
+
+## Trigger Hints
+
+- Treat mentions of `review`, `commit`, `push`, `open PR`, `merge`, `quality gate`, or `ready to ship` as triggers for this skill.
+- For commit/push/merge requests, proactively ask to run Kodus review first when a fresh review has not run yet in the current task.
+
 ## Workflow
 
-1) Ensure Kodus CLI is available.
+1. Ensure Kodus CLI is available.
+
 - Run `kodus --help` to confirm.
 - If missing, ask the user to install the CLI and stop.
 
-2) Ensure authentication if required.
-- If `kodus review` fails with auth, run `kodus auth login` (interactive) and retry.
+2. Ensure authentication if required.
+
+- If `kodus review` fails with auth, ask the human to authenticate with `kodus auth login` in their terminal, then retry after they confirm.
 - For team keys, use `kodus auth team-key --key <key>` when provided by the user.
 
-3) Run review using prompt-only output.
+3. Run review using prompt-only output.
+
 - Default: `kodus review --prompt-only`.
 - If user specifies files: `kodus review --prompt-only <files...>`.
 - If user asks for staged/commit/branch: add `--staged`, `--commit <sha>`, or `--branch <name>`.
 - If user wants fast: add `--fast`.
 
-4) Parse results and apply fixes.
+4. Parse results and apply fixes.
+
 - Use the output to locate files and lines.
 - Make minimal, targeted changes to address each issue.
 - If an issue is not actionable or is a false positive, explain why and skip.
 
-5) Re-run review if needed.
+5. Re-run review if needed.
+
 - After fixes, rerun `kodus review --prompt-only` to confirm issues are resolved.
 
 ## Notes
 
 - Prefer `--prompt-only` for predictable parsing.
 - Avoid `--interactive` unless the user explicitly asks.
+- Redirect PR-vs-task validation requests to `kodus-business-rules-validation`.
 - Use `review --help` to undertstand review possibilities

package/skills/kodus-review-dev/SKILL.md

@@ -1,41 +1,55 @@
 ---
 name: kodus-review-dev
-description: Use when the user explicitly asks for local/dev API CLI flow (localhost, QA API, or local `node dist/index.js`) while reviewing code. Run the dev review flow and apply fixes based on CLI output. Not the default review skill.
+description: Use when the user wants Kodus to review local changes through a local CLI build or non-production API such as `node dist/index.js`, localhost, or QA, including local `--prompt-only` flows.
 ---
 
 # Kodus Review (Dev)
 
 ## Goal
 
-Use the local Kodus CLI dev flow to review changes and resolve issues. Prefer machine-friendly output via `--prompt-only`, then apply fixes in code.
+Use the local Kodus CLI build in this repository to review changes and resolve issues. Prefer machine-friendly output via `--prompt-only`, then apply fixes in code.
+
+If the request is to validate local changes against business rules, task requirements, or acceptance criteria, use `kodus-business-rules-validation` instead. The local review command does not trigger local business validation.
+
+## Trigger Hints
+
+- Treat mentions of `review`, `commit`, `push`, `open PR`, `merge`, `quality gate`, or `ready to ship` as triggers for this skill.
+- For commit/push/merge requests, proactively ask to run local Kodus review first when a fresh review has not run yet in the current task.
 
 ## Workflow
 
-1) Ensure local dev command is available.
+1. Ensure local dev command is available.
+
 - Prefer the helper script (do not rely on aliases).
 - Use: `skills/kodus-review-dev/scripts/run-local-cli.sh --help`.
 - If missing or failing, ask the user to confirm the local path and env values, then stop.
 
-2) Ensure authentication if required.
-- If the review fails with auth, run the same command with `auth login` (interactive) and retry.
+2. Ensure authentication if required.
+
+- If the review fails with auth, ask the human to authenticate with `kodus auth login` in their terminal, then retry after they confirm.
 - For team keys, use `auth team-key --key <key>` with the same helper script when provided by the user.
 
-3) Run review using prompt-only output.
+3. Run review using prompt-only output.
+
 - Default: `skills/kodus-review-dev/scripts/run-local-cli.sh review --prompt-only`.
 - If user specifies files: append `<files...>`.
 - If user asks for staged/commit/branch: add `--staged`, `--commit <sha>`, or `--branch <name>`.
 - If user wants fast: add `--fast`.
 
-4) Parse results and apply fixes.
+4. Parse results and apply fixes.
+
 - Use the output to locate files and lines.
 - Make minimal, targeted changes to address each issue.
 - If an issue is not actionable or is a false positive, explain why and skip.
 
-5) Re-run review if needed.
+5. Re-run review if needed.
+
 - After fixes, rerun `skills/kodus-review-dev/scripts/run-local-cli.sh review --prompt-only` to confirm issues are resolved.
 
 ## Notes
 
 - Prefer `--prompt-only` for predictable parsing.
 - Avoid `--interactive` unless the user explicitly asks.
+- Redirect PR-vs-task validation requests to `kodus-business-rules-validation`.
+- The helper script respects `KODUS_API_URL`, `KODUS_VERBOSE`, and `KODUS_CLI_ENTRYPOINT`.
 - Do not use `--fix` unless the user explicitly asks.

package/skills/business-rules-validation/SKILL.md

@@ -1,43 +0,0 @@
----
-name: business-rules-validation
-description: Use when asked for business validation, acceptance-criteria validation, PR-vs-task checks, or merge readiness with task compliance. Run `kodus pr business-validation` against local diff scope and optional task context.
----
-
-# Business Rules Validation
-
-## Goal
-
-Run Kodus business-rules validation from local repository diff scope and optional task reference.
-
-## Workflow
-
-1) Ensure Kodus CLI is available.
-- Run `kodus --help` to confirm.
-- If missing, ask the user to install the CLI and stop.
-
-2) Ensure authentication if required.
-- If command fails with auth, run `kodus auth login` (interactive) and retry.
-- For team keys, use `kodus auth team-key --key <key>` when provided by the user.
-
-3) Choose local diff scope.
-- Default (no scope flags): working tree diff.
-- Optional explicit scope: `--staged`, `--branch <name>`, `--commit <sha>`, or `[files...]`.
-- Use only one scope per command.
-
-4) Run business validation.
-- Examples:
-```bash
-kodus pr business-validation --staged --task-id KC-1441
-kodus pr business-validation --branch main --task-id KC-1441
-kodus pr business-validation src/service.ts src/use-case.ts --task-id KC-1441
-```
-
-5) Interpret and apply.
-- Parse output and identify mismatches against requirements.
-- Apply focused changes.
-- Re-run the same command until output is acceptable.
-
-## Notes
-
-- Use `--task-id` or `--task-url` when available.
-- `kodus review` and business validation are different flows.