@xevy/skills 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.claude-plugin/plugin.json +23 -0
  2. package/README.md +133 -0
  3. package/bin/cli.mjs +387 -0
  4. package/bin/version.mjs +120 -0
  5. package/bin/xevy-creds.mjs +81 -0
  6. package/bin/xevy-link-repo.mjs +47 -0
  7. package/bin/xevy-sync-env.mjs +102 -0
  8. package/package.json +33 -0
  9. package/skills/analyze/SKILL.md +26 -0
  10. package/skills/analyze-here/SKILL.md +30 -0
  11. package/skills/create-document/SKILL.md +32 -0
  12. package/skills/create-report/SKILL.md +169 -0
  13. package/skills/create-report/examples.md +134 -0
  14. package/skills/create-xevy-task/SKILL.md +68 -0
  15. package/skills/deploy/SKILL.md +25 -0
  16. package/skills/execute/SKILL.md +29 -0
  17. package/skills/execute-here/SKILL.md +35 -0
  18. package/skills/fix/SKILL.md +26 -0
  19. package/skills/fix-here/SKILL.md +23 -0
  20. package/skills/generate-image/SKILL.md +31 -0
  21. package/skills/investigate/SKILL.md +218 -0
  22. package/skills/investigate/examples.md +170 -0
  23. package/skills/manage-documents/SKILL.md +39 -0
  24. package/skills/mark-ready/SKILL.md +29 -0
  25. package/skills/merge/SKILL.md +24 -0
  26. package/skills/merge-here/SKILL.md +22 -0
  27. package/skills/move-to-qa/SKILL.md +21 -0
  28. package/skills/move-to-qa-here/SKILL.md +21 -0
  29. package/skills/plan/SKILL.md +24 -0
  30. package/skills/plan-here/SKILL.md +26 -0
  31. package/skills/xevy-design/SKILL.md +103 -0
  32. package/skills/xevy-design/reference/craft.md +69 -0
  33. package/skills/xevy-design/reference/critique.md +33 -0
  34. package/skills/xevy-design/reference/polish.md +25 -0
  35. package/skills/xevy-design/reference/setup.md +82 -0
  36. package/skills/xevy-design/reference/shape.md +40 -0
  37. package/skills/xevy-setup/SKILL.md +56 -0
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: create-xevy-task
3
+ description: Capture the current Claude Code session's AI work into a reviewable Xevy task — document the user's goal + requirements and everything the AI changed (files, branch, PR, preview), create the task, attach PR/branch metadata, and move it to for_review or for_qa so a human developer or QA can pick it up. Also creates an ordinary new task when there is nothing to capture. Use /xevy:create-xevy-task.
4
+ argument-hint: "[title or description] [--review|--qa]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__list_tasks mcp__xevy__get_project_workbreakdown mcp__xevy__create_task mcp__xevy__update_task mcp__xevy__update_task_status mcp__xevy__create_task_note mcp__xevy__get_deploy_status mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision"
7
+ ---
8
+
9
+ # /xevy:create-xevy-task — capture AI work into a reviewable task
10
+
11
+ Turn what just happened in this session into an Xevy task a **human developer or QA** can pick up. This is the bridge for "the AI did the work — now get a professional to review/test it." It also creates an ordinary new task when there's nothing to capture.
12
+
13
+ ## 1. Decide the mode
14
+ - **Evaluate the session.** Did the AI make code changes this session? Check git: `git status --short`, `git branch --show-current`, and `git log --oneline` for new commits. Read back the conversation for the user's goal, requirements, and any "must NOT" constraints.
15
+ - **Avoid duplicates.** Is this work already tracked by an Xevy task (a session task lock, a task code referenced in the conversation, `.xevy/project.json` context, or a match from `list_tasks`/`find_task`)? If yes, STOP and ask whether to **update that task** (description + status + notes) instead of creating a duplicate.
16
+ - Pick a mode:
17
+ - **Capture mode** (default when the AI changed code this session) → sections 2–5.
18
+ - **Ordinary mode** (no AI work to capture, or `$ARGUMENTS` clearly describes a brand-new unrelated task) → section 6.
19
+
20
+ ## 2. Gather evidence (capture mode) — never fabricate
21
+ Collect concrete details; if something isn't available, omit it and say so. Do NOT invent PR links, branches, or test results.
22
+ - **Branch:** `git branch --show-current`.
23
+ - **Changes:** `git status --short`; `git diff --stat <base>...HEAD` and `git log --oneline <base>..HEAD` (base = the repo's main/develop/master). Note key files by path.
24
+ - **PR / compare link:** `gh pr view --json url,number,title 2>/dev/null`; if no PR, build a compare URL from `git remote get-url origin` + the branch.
25
+ - **Preview / main URL:** from the conversation, or `get_deploy_status` if a deploy was triggered.
26
+ - **Tests / checks:** what was actually run this session and the result (type-check, lint, tests). Quote real output, don't assume green.
27
+
28
+ ## 3. Resolve project + category/epic
29
+ - Resolve the project from `.xevy/project.json` (or ask). `create_task` requires `categoryId` and `epicId` — use `get_project_workbreakdown` to pick the best-fit category + epic; ask the user only if it's genuinely ambiguous.
30
+
31
+ ## 4. Create the task
32
+ Call `create_task` with:
33
+ - **title:** concise, outcome-focused (what the change delivers).
34
+ - **description (markdown):**
35
+ - `## Goal` — plain-language, from the user's request.
36
+ - `## Requirements` — explicit + implicit, including any "must NOT" constraints.
37
+ - `## Changes made by the AI` — a clear summary grouped by area, with key files (`path`), so a reviewer knows where to look.
38
+ - `## How to review` — what a developer should verify and any risk areas.
39
+ - `## Technical details` — branch, PR/compare link, commit list, preview/main URL, and tests run + results (with real status). Note baseline vs final health if known.
40
+ - **metadata:** set `aiPullRequest.branch` (and `url`/`compareUrl` when available) so the deploy tools and web UI link up to the branch.
41
+
42
+ Check `list_tasks`/`find_task` once more before creating to avoid a duplicate.
43
+
44
+ ## 4b. Raise open questions (when ambiguous)
45
+ After the task exists, if scope, approach, category/epic placement, or trade-offs are **genuinely ambiguous** — don't bury them in the description or guess:
46
+ - Call `mcp__xevy__create_decision` with preset choices + explanations (optional follow-up per choice).
47
+ - If the user is present, you may ask via **AskUserQuestion** first, then persist with `create_decision` + `answer_decision`.
48
+ - Open questions gate `/xevy:mark-ready`, analyze, plan, and execute until answered — keep them few and high-signal.
49
+ - In **capture mode**, only raise decisions for real ambiguities in requirements or review routing — not for documented AI work.
50
+ - In **ordinary mode**, this is the primary way to capture unresolved intake ambiguities.
51
+
52
+ ## 5. Attach reviewer/QA guidance + set status
53
+ - **Who picks it up next?** If `$ARGUMENTS` has `--review` or `--qa`, use that; otherwise ask: a **developer** (code review → `for_review`) or **QA** (testing → `for_qa`)?
54
+ - **For developer review:** add a `Technical Review Instructions` note (`create_task_note`) — what changed and where, how to run it locally, and the risk areas to scrutinise.
55
+ - **For QA:** add a `QA Re-Testing Guide` note — non-technical and UI-verifiable: (1) preconditions, (2) step-by-step reproduction with expected vs actual, (3) validation checks, (4) evidence to capture, (5) final verdict.
56
+ - Set the status with `update_task_status` to `for_review` or `for_qa`. NEVER jump to `done` — a human owns that gate.
57
+
58
+ ## 6. Ordinary mode
59
+ No AI work to capture (or a fresh, unrelated task): create the task from `$ARGUMENTS`/the request. Capture the user's story, problem, expectation, and desired outcome in plain language — do NOT fabricate technical detail or a PR. Raise any genuine ambiguities with `create_decision` (section 4b). Leave status at `draft` — use `/xevy:mark-ready` to promote once open questions are answered. Do NOT set `ready` while any decision is still open. Skip the review/QA routing.
60
+
61
+ ## 7. Report
62
+ Give the task **code + the `url` returned by the create/update tool** (always show this link so the user can open and review it), its **status**, any **open decisions** (call `list_task_decisions` if you raised questions), and a one-line summary of what was captured (PR link, branch, preview URL). Tell the user a developer/QA can now pick it up directly from Xevy (capture mode) or that they should answer open questions / run `/xevy:mark-ready` before analyze (ordinary mode).
63
+
64
+ ## Rules
65
+ - Evidence before claims — gather PR/branch/changes/tests from git and the session; never invent them.
66
+ - One task per piece of work — update an existing task instead of duplicating.
67
+ - Open questions belong on decisions (`create_decision`), not buried as assumptions in the description.
68
+ - This skill captures and routes for human review; it does NOT push, merge, or deploy.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: deploy
3
+ description: Deploy a per-task preview or the project's main environment via Xevy (Coolify). Usage:/xevy:deploy [preview|main] [task]. Bare invocation targets the in-context task's preview, else main.
4
+ argument-hint: "[preview|main] [task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Bash mcp__xevy__deploy_preview mcp__xevy__deploy_main mcp__xevy__get_deploy_status mcp__xevy__find_task"
7
+ ---
8
+
9
+ # /xevy:deploy — deploy a preview or main
10
+
11
+ Trigger a Coolify deploy through the Xevy MCP. `$ARGUMENTS` may start with `preview` or `main`; the rest is a task hint.
12
+
13
+ ## Resolve target
14
+ - First word `preview` → per-task preview. `main` → project main. If unspecified (smart default): if a task is in context (`.xevy` session, an open task, or a task hint) → **preview**; otherwise → **main**. If genuinely ambiguous, ask the user.
15
+
16
+ ## Preview
17
+ - Resolve the task (`mcp__xevy__find_task` by code). A pushed feature branch must exist for it (recorded as the task's pull request) — if not, tell the user to run `/xevy:execute` first; `deploy_preview` returns `NO_BRANCH` otherwise.
18
+ - Call `mcp__xevy__deploy_preview({ taskId, branch })` with the task's pushed branch. Report the returned status + URL.
19
+
20
+ ## Main
21
+ - Call `mcp__xevy__deploy_main` for the current project. It deploys the project's REMOTE default branch and never pushes git branches; warn that unmerged local work won't appear until landed via PR. Report the main URL.
22
+
23
+ ## Report progress
24
+ - Deploys are async (queued → building → live). Use `mcp__xevy__get_deploy_status` to report current state. Tell the user the URL may take a few minutes to become reachable.
25
+ - If the server reports previews are disabled, say so and stop. Never push protected branches (master/main/develop/staging) to make a deploy reflect local changes.
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: execute
3
+ description: Execute a task in the cloud — run the Xevy server agent's 'execute' action (implements, pushes a branch, opens a PR), then review the diff/PR, run tests, correct issues, and deploy a preview. Use /xevy:execute-here to implement locally.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Edit Bash Agent mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_subtasks mcp__xevy__list_sprints mcp__xevy__assign_task_to_sprint mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions mcp__xevy__deploy_preview mcp__xevy__get_deploy_status"
7
+ ---
8
+
9
+ # /xevy:execute — execute in the cloud (then review + deploy)
10
+
11
+ Cloud is the default engine: the Xevy server agent implements the task, pushes a feature branch, and opens a PR. **You then review the result, correct issues, and deploy a preview.** To implement locally, use `/xevy:execute-here`.
12
+
13
+ ## 1. Resolve + gates
14
+ - Resolve the task (`$ARGUMENTS` / context). Confirm planning artifacts exist (`list_subtasks`); if none and the task is non-trivial, suggest `/xevy:plan` first.
15
+ - Sprint gate: if an active sprint exists (`list_sprints` status=active) and the task isn't on it, ensure it has `## Analysis` + `storyPoints` > 0, then `assign_task_to_sprint` — else stop and ask the user to analyze/estimate first.
16
+
17
+ ## 2. Run the cloud action
18
+ - `mcp__xevy__start_ai_action({ taskId, action: "execute", stream: true })` — **always pass `stream: true`**. The call blocks and streams live per-step progress; report it as it arrives. Do **NOT** use fire-and-forget or `sleep`/manual poll loops — streaming is the default and is reliable. Only if this streamed call returns *before* a terminal status (genuine disconnect — the run keeps going server-side) resume with `get_ai_execution`. On failure, surface the output; offer retry or `/xevy:execute-here`.
19
+ - On success the server has pushed the feature branch and opened a PR (recorded on the task).
20
+
21
+ ## 3. Review & correct (MANDATORY — you are the reviewer)
22
+ Do NOT finish until the change is verified and correct:
23
+ - `git fetch origin` and check out / diff the task's feature branch (read the branch from `find_task` → pull request metadata). Inspect the full diff against the task requirements and plan (trace each requirement to code).
24
+ - Run the project's checks (type-check, lint, tests). Read failures; if anything is broken, incomplete, or violates a "must NOT" constraint, **fix it**: edit the files, then commit + push to the **feature branch** (never a protected branch). You may dispatch the **reviewer** subagent for an independent pass.
25
+ - **Frontend/UI changes:** before editing any UI (pages, components, app shell, forms, styling), follow the `/xevy:xevy-design` skill so the change matches the project design system (`./.xevy/design.md`).
26
+ - Re-run checks until green. Refresh the PR. Summarise PASS/PARTIAL/FAIL with file:line evidence and what you corrected.
27
+
28
+ ## 4. Deploy a preview
29
+ - After review passes, `mcp__xevy__deploy_preview({ taskId, branch })` with the feature branch; report the URL (poll `get_deploy_status`). Preview failure is non-blocking — note it and continue.
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: execute-here
3
+ description: Execute a task locally in this Claude Code session — worktree, implement against the plan, run tests, commit, push, open a PR, deploy a preview, then review/correct. Cloud equivalent is /xevy:execute.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Edit Write Bash Agent mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__update_task_status mcp__xevy__list_specs mcp__xevy__list_subtasks mcp__xevy__update_subtask mcp__xevy__list_sprints mcp__xevy__assign_task_to_sprint mcp__xevy__deploy_preview mcp__xevy__get_deploy_status mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision"
7
+ ---
8
+
9
+ # /xevy:execute-here — implement locally (then review + deploy)
10
+
11
+ You are the engine: implement the task in this session, following the Xevy worktree + git protocol.
12
+
13
+ ## 1. Resolve + gates
14
+ - Resolve the task (`$ARGUMENTS` / context). Read its `## Analysis`, plan spec, and subtasks. If none and non-trivial, suggest `/xevy:plan-here` or ask whether to plan-and-execute or execute directly.
15
+ - **Decisions gate (BEFORE implementing):** call `mcp__xevy__list_task_decisions`. If any decision is **open**, resolve it first — open decisions block execution. Present each via **AskUserQuestion**, record with `mcp__xevy__answer_decision`, and fold the answer into the work (if a relevant subtask is already done, the answer may warrant a new subtask). Never guess or bypass.
16
+ - Sprint gate: same as cloud — if an active sprint exists and the task isn't on it, require `## Analysis` + `storyPoints` > 0 then `assign_task_to_sprint`, else stop and ask.
17
+
18
+ ## 2. Worktree protocol
19
+ - Record the current branch + dir. Derive a canonical branch `xevy/<TASK-ID>-<slug>` (task id = task code, or first 8 chars of task UUID; reuse if one already exists for this task — never create a second branch per task).
20
+ - Create/attach a git worktree in a sibling dir and `cd` into it; if resuming, first merge the latest source branch (e.g. `git merge origin/main`). Do ALL work in the worktree.
21
+ - NEVER commit/push on a protected branch (master/main/develop/staging) — only on `xevy/*` task branches.
22
+
23
+ ## 3. Implement
24
+ - Move the task to `in_progress` (`update_task_status`) when implementation begins — mirrors the cloud `execute`, which flips to `in_progress` at start (and to `for_review` on success).
25
+ - Work the subtasks in order with Read/Grep/Edit/Write (dispatch builder/frontend subagents via `Agent` with the worktree cwd when useful). Keep changes surgical, match existing style. Update subtask status via MCP as you go.
26
+ - **Frontend/UI changes:** before editing any UI (pages, components, app shell, forms, styling), follow the `/xevy:xevy-design` skill so the change matches the project design system (`./.xevy/design.md`).
27
+ - If you hit a genuine ambiguity a human must resolve mid-implementation, raise it with `mcp__xevy__create_decision` (preset choices) rather than guessing — or, if the user is present, ask via **AskUserQuestion** and persist with `create_decision` + `answer_decision`. Open decisions block further AI steps until answered.
28
+ - Validate after each step (type-check → lint → targeted tests).
29
+
30
+ ## 4. Review & correct (MANDATORY)
31
+ - Run the full project checks. Trace every requirement to code; check "must NOT" constraints. Dispatch the **reviewer** subagent for an independent PASS/PARTIAL/FAIL with file:line evidence. Fix everything it flags; re-run until green.
32
+
33
+ ## 5. Push, PR, deploy
34
+ - Commit + push the task branch. Open/refresh the PR and ALWAYS give the user the PR/compare link. Do NOT merge automatically.
35
+ - Record the branch on the task (`update_task` metadata `aiPullRequest.branch`) so deploys resolve it, then `mcp__xevy__deploy_preview({ taskId, branch })`; report the URL. Move status to `for_review` (`update_task_status`).
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: fix
3
+ description: Apply a fix/rework to a task in the cloud — run the Xevy server agent's 'fix' action (reworks, pushes, refreshes the PR), then review the diff, run tests, correct issues, and redeploy the preview. Use /xevy:fix-here to fix locally.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Edit Bash Agent mcp__xevy__find_task mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions mcp__xevy__deploy_preview mcp__xevy__get_deploy_status"
7
+ ---
8
+
9
+ # /xevy:fix — fix in the cloud (then review + redeploy)
10
+
11
+ Cloud is the default engine: the server agent reworks the task and refreshes the PR; **you then review and correct.** To fix locally, use `/xevy:fix-here`.
12
+
13
+ ## 1. Resolve
14
+ Resolve the task (`$ARGUMENTS` / context). It should already have a feature branch from a prior execute.
15
+
16
+ ## 2. Run the cloud action
17
+ - `mcp__xevy__start_ai_action({ taskId, action: "fix", stream: true })` — **always pass `stream: true`**. The call blocks and streams live per-step progress; report it as it arrives. Do **NOT** use fire-and-forget or `sleep`/manual poll loops — streaming is the default and is reliable. Only if this streamed call returns *before* a terminal status (genuine disconnect — the run keeps going server-side) resume with `get_ai_execution`. On failure surface output and offer retry or `/xevy:fix-here`.
18
+
19
+ ## 3. Review & correct (MANDATORY)
20
+ - `git fetch origin` and diff the task's feature branch. Verify the fix actually resolves the reported issue and introduces no regressions; trace to the failing requirement / QA finding.
21
+ - Run type-check/lint/tests. If still broken or incomplete, **fix it** — edit, commit, push to the feature branch (never protected). Dispatch the **reviewer** subagent for an independent pass. Re-run until green.
22
+ - **Frontend/UI changes:** before editing any UI (pages, components, app shell, forms, styling), follow the `/xevy:xevy-design` skill so the change matches the project design system (`./.xevy/design.md`).
23
+ - Report PASS/PARTIAL/FAIL with evidence and what you corrected.
24
+
25
+ ## 4. Redeploy preview
26
+ - `mcp__xevy__deploy_preview({ taskId, branch })`; report the URL (poll `get_deploy_status`). Non-blocking.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: fix-here
3
+ description: Apply a fix/rework to a task locally in this Claude Code session — reuse the task worktree, rework, run tests, push, refresh the PR, redeploy preview, then review. Cloud equivalent is /xevy:fix.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Edit Write Bash Agent mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_subtasks mcp__xevy__update_subtask mcp__xevy__deploy_preview mcp__xevy__get_deploy_status"
7
+ ---
8
+
9
+ # /xevy:fix-here — fix locally (then review + redeploy)
10
+
11
+ ## 1. Resolve + locate worktree
12
+ Resolve the task (`$ARGUMENTS` / context). Find the EXISTING worktree/branch for it (`git worktree list`, match by task code). The worktree MUST already exist — do not create a new branch; if none, stop and ask. Merge the latest source branch into the feature branch first to avoid divergence.
13
+
14
+ ## 2. Rework
15
+ Make the requested fix in the worktree (Read/Grep/Edit/Write, or builder subagent with the worktree cwd). Keep it surgical; root-cause the issue rather than patching symptoms. Update subtasks via MCP.
16
+
17
+ ## 3. Review & correct (MANDATORY)
18
+ Run the full project checks. Verify the fix resolves the issue with no regressions; check "must NOT" constraints. Dispatch the **reviewer** subagent (PASS/PARTIAL/FAIL + file:line). Fix anything flagged; re-run until green.
19
+
20
+ **Frontend/UI changes:** before editing any UI (pages, components, app shell, forms, styling), follow the `/xevy:xevy-design` skill so the change matches the project design system (`./.xevy/design.md`).
21
+
22
+ ## 4. Push, PR, deploy
23
+ Commit + push the feature branch; refresh the PR and give the user the link. Do NOT merge automatically. Then `mcp__xevy__deploy_preview({ taskId, branch })`; report the URL. Ask whether to merge back via `/xevy:merge` — don't merge on your own.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: generate-image
3
+ description: Generate an image from a text prompt and store it in the current Xevy project. Use when the user asks to "generate an image of X", "make a logo/mockup/illustration", or otherwise create a visual asset. The image is generated via OpenRouter, stored as a project attachment, and a usable URL is returned; it also appears in the project Gallery.
4
+ argument-hint: "[prompt describing the image] [--model <id>] [--task <task-code>]"
5
+ allowed-tools: "mcp__xevy__generate_image mcp__xevy__find_task mcp__xevy__get_current_user"
6
+ ---
7
+
8
+ # /xevy:generate-image — generate an image into the project
9
+
10
+ Turn a text prompt into a stored image asset in the current Xevy project. The result is saved as a project attachment (`source=generated`) and returned as a URL, and it shows up in the project **Gallery** alongside uploaded media and generated videos.
11
+
12
+ ## 1. Resolve context
13
+ - Resolve `workspaceIdentifier` + `projectIdentifier` from `.xevy/project.json` when available; otherwise ask the user (or use `list_workspaces` / `list_projects`).
14
+ - Generation requires **write access** to the project. If the user is a guest/read-only member the tool returns 403 — relay that plainly.
15
+
16
+ ## 2. Build the prompt
17
+ - Use the user's description as the `prompt`. Keep it faithful to what they asked; don't silently restyle.
18
+ - Optional inputs:
19
+ - `model` — an OpenRouter image model id. Omit to use the project default (`google/gemini-3-pro-image-preview`).
20
+ - `size` — a size hint like `1024x1024` (recorded with the asset).
21
+ - `fileName` — a friendly file name.
22
+ - `taskId` — when the image relates to a specific task, pass its UUID so the Gallery can link the asset back to that task. If the user references a task **code** (e.g. VI02-10), resolve it to a UUID with `find_task` first.
23
+
24
+ ## 3. Generate
25
+ - Call `generate_image` with `{ workspaceIdentifier, projectIdentifier, prompt, model?, size?, fileName?, taskId? }`.
26
+ - It returns `{ attachmentId, url, fileName, mimeType, sizeBytes, prompt, model }`.
27
+
28
+ ## 4. Report back
29
+ - Give the user the returned **URL** (clickable) and the file name, and mention the image is now in the project Gallery.
30
+ - Generation is a paid provider call — generate once per request; don't loop or retry on success.
31
+ - Never print API keys or environment values. If generation fails, surface the error message from the tool (provider/storage boundary) without inventing a cause.
@@ -0,0 +1,218 @@
1
+ ---
2
+ name: investigate
3
+ description: >-
4
+ Investigate bugs, issues, and questions. Prefer the project's Xevy
5
+ connectors — query a SQL connector (read-only) for the environment you're
6
+ investigating, or run a read op on a service connector (Shopify store data,
7
+ Ahrefs, DataForSEO, SemRush, …) — before writing any script; fall back to
8
+ small targeted ephemeral scripts that read credentials from .env (or
9
+ staging.env / prod.env) without exposing secrets. Use /xevy:investigate
10
+ when debugging or diagnosing before fixing, or to verify third-party
11
+ integrations, APIs, store/DB state, or environment-specific behavior.
12
+ argument-hint: "[issue or question]"
13
+ disable-model-invocation: true
14
+ allowed-tools: "Read Grep Bash Write Delete mcp__xevy__connector_list mcp__xevy__connector_sql_schema mcp__xevy__connector_query mcp__xevy__connector_search mcp__xevy__connector_describe mcp__xevy__connector_execute mcp__xevy__connector_test"
15
+ ---
16
+
17
+ # /xevy:investigate — diagnose before fixing
18
+
19
+ **Investigate first. Do not fix blindly.** Gather evidence with a small, disposable script, report findings, then let the user decide whether to fix (e.g. via `/xevy:fix-here`).
20
+
21
+ ## When to use
22
+
23
+ - Bug reports, flaky behavior, "why does X fail?"
24
+ - Third-party integration checks (GitHub, SMTP, Coolify, AI providers, etc.)
25
+ - Environment-specific issues (staging vs production vs local)
26
+ - Questions answerable by hitting a live API, DB query, or config check
27
+
28
+ **Do not** jump to code changes until investigation completes and you have a clear root-cause hypothesis.
29
+
30
+ ## Use the project's connectors FIRST
31
+
32
+ Before writing any script, check whether the project already has a **connector** for what you need. Connectors are the safest, fastest way to investigate: they run through Xevy's isolated gateway, credentials never touch a local file or the chat (only the gateway can decrypt them), SQL is **read-only enforced**, and there's no script to write, run, or delete.
33
+
34
+ ### Pick the connector that matches the environment you're investigating
35
+
36
+ 1. **List the SQL connectors:** `connector_list` with `serviceName: "sql"`.
37
+ 2. **Match the environment.** Connectors are named per environment (e.g. `Production Database`, `Staging DB`, `Analytics (read replica)`). Choose the one for the environment in the report/question. **If it's ambiguous which connector maps to the target environment, stop and ask the user** — never guess and query the wrong database (especially production).
38
+ 3. If the project has **no** SQL connector for that environment, either ask the user to add one in **Settings → Connectors**, or fall back to the ephemeral-script path below.
39
+
40
+ ### Investigate a database via its connector
41
+
42
+ - **Discover structure:** `connector_sql_schema` → schemas, tables, columns. Use it to author accurate queries.
43
+ - **Query:** `connector_query` with a single read-only `SELECT`/`WITH`. Writes are rejected by the gateway; results are row-capped. Returns `{ columns, rows, rowCount, truncated }`.
44
+ - Report row counts, existence checks, and non-sensitive sample columns only — same discipline as scripts (no PII / secrets in chat).
45
+
46
+ This replaces the `DATABASE_URL` ephemeral-script pattern whenever a SQL connector exists for the environment — no env file, no secret handling, no cleanup.
47
+
48
+ ### Investigate a store / service via its connector (Shopify, Ahrefs, DataForSEO, SemRush, …)
49
+
50
+ For non-SQL service connectors, run a **read** operation through the gateway instead of hitting the third-party API with a raw key:
51
+
52
+ 1. **Confirm it's configured:** `connector_list` (optionally `serviceName: "shopify"`) — shows service, `status`, and the credential's last 4 only.
53
+ 2. **Find the operation by intent:** `connector_search` (e.g. `"shopify orders overview"`, `"backlinks for a domain"`) → `{ service_name, operation, description }`.
54
+ 3. **Check params + cost:** `connector_describe` with the `serviceName` + `operation`.
55
+ 4. **Run it:** `connector_execute` with `serviceName`, `operation`, and `params`. Large results come back as a summary + `resultRef` (fetch with `connector_fetch_result`); use `limit` to keep responses small.
56
+
57
+ **Shopify data connector — useful read ops for investigation:** `shop_info` (store profile / plan / currency — the quickest "is the connection alive?" check), `products_list`, `product_detail`, `orders_list`, `orders_summary`, `customers_summary`, `inventory_levels`, `fulfillments`. These prove store state without any local script or token handling. Example: to verify the Shopify connection works, `connector_execute serviceName:"shopify" operation:"shop_info"` and report the returned store name + domain.
58
+
59
+ > **Investigation stays read-only.** Shopify **write** ops (`product_update`, `content_update`, …) are approval-guarded — a plain `connector_execute` returns a **dry-run preview** and never mutates. During investigation, never pass `approve:true`; a fix (if any) is a separate, user-approved step.
60
+
61
+ **Only fall back to an ephemeral script + env file** (below) when there is no connector for the target environment/service, or the check isn't a DB query / connector operation (SMTP handshake, internal HTTP route, config-flag presence, etc.).
62
+
63
+ ## Environment files
64
+
65
+ | File | Use |
66
+ |------|-----|
67
+ | `.env` | Local / dev (default) |
68
+ | `staging.env` | Staging — user must create; never commit |
69
+ | `prod.env` | Production — user must create; never commit |
70
+
71
+ **Before staging/prod investigation:** ask the user to create the appropriate file with the needed vars (copy from `.env.example` or their secret store). Remind them:
72
+
73
+ > Keep `staging.env` and `prod.env` safe. They are gitignored — do not commit or paste values into chat.
74
+
75
+ Pick the file with `ENV_FILE` (default `.env`). Never read, log, echo, or return secret values.
76
+
77
+ ## Workflow
78
+
79
+ ```
80
+ 1. Scope → What to test, which env vars, success/failure signals
81
+ 2. Script → Write one small targeted script (see rules below)
82
+ 3. Run → Execute; capture sanitized output only
83
+ 4. Report → Findings + root-cause hypothesis (no fix yet unless asked)
84
+ 5. Cleanup → Delete the script (and any temp artifacts)
85
+ ```
86
+
87
+ ### 1. Scope
88
+
89
+ - State the question in one sentence.
90
+ - List env vars the script will use (names only, e.g. `GITHUB_CLIENT_ID`, `DATABASE_URL`).
91
+ - If vars are missing from the chosen env file, stop and ask the user to add them — do not guess credentials.
92
+
93
+ ### 2. Script rules
94
+
95
+ Write **one** ephemeral script per investigation:
96
+
97
+ - **Location:** `scripts/_investigate/` — never a permanent test file.
98
+ - **Naming:** `_investigate-<topic>-<timestamp>.ts` or `.mjs` (leading `_` signals disposable).
99
+ - **Load env:** use `dotenv` with an explicit path — do not rely on shell `export`:
100
+
101
+ ```typescript
102
+ import { config } from "dotenv";
103
+ import { resolve } from "node:path";
104
+
105
+ const envFile = process.env.ENV_FILE ?? ".env";
106
+ config({ path: resolve(process.cwd(), envFile) });
107
+ ```
108
+
109
+ For staging/prod: `ENV_FILE=staging.env npx tsx scripts/_investigate/...`
110
+
111
+ - **Secrets:** read from `process.env`; never hardcode, print, or interpolate into logs.
112
+ - **Safe output only:** status codes, boolean pass/fail, counts, redacted IDs, error *types* — not tokens, passwords, or connection strings.
113
+ - **Redact helper** (use when echoing API responses):
114
+
115
+ ```typescript
116
+ function redact(obj: unknown): unknown {
117
+ if (typeof obj !== "object" || obj === null) return obj;
118
+ const sensitive = /token|secret|password|key|authorization|cookie/i;
119
+ return Object.fromEntries(
120
+ Object.entries(obj as Record<string, unknown>).map(([k, v]) =>
121
+ sensitive.test(k) ? [k, "[REDACTED]"] : [k, v]
122
+ )
123
+ );
124
+ }
125
+ ```
126
+
127
+ - **Keep it small:** one concern per script (one API call, one DB query, one auth flow check).
128
+ - **Timeout:** fail fast (e.g. 10–30s) rather than hang.
129
+
130
+ ### 3. Run
131
+
132
+ ```bash
133
+ # local (default)
134
+ npx tsx scripts/_investigate/_investigate-github-oauth-20260626.ts
135
+
136
+ # staging
137
+ ENV_FILE=staging.env npx tsx scripts/_investigate/_investigate-github-oauth-20260626.ts
138
+
139
+ # production — confirm with user first
140
+ ENV_FILE=prod.env npx tsx scripts/_investigate/_investigate-github-oauth-20260626.ts
141
+ ```
142
+
143
+ If output might contain secrets, pipe through redaction before sharing with the user.
144
+
145
+ ### 4. Report
146
+
147
+ Use this template:
148
+
149
+ ```markdown
150
+ ## Investigation: [one-line question]
151
+
152
+ **Environment:** local | staging | production
153
+ **Source:** SQL connector `<name>` | service connector `<name>` | env file `.env` | `staging.env` | `prod.env`
154
+ **Script:** `scripts/_investigate/...` (deleted after run) — omit when a connector was used
155
+
156
+ ### Findings
157
+ - [observable fact with evidence]
158
+ - [observable fact with evidence]
159
+
160
+ ### Root-cause hypothesis
161
+ [Most likely cause, or "inconclusive — needs X"]
162
+
163
+ ### Recommended next step
164
+ [Fix approach, or further investigation — do not implement unless asked]
165
+ ```
166
+
167
+ Verdict: **CONFIRMED** | **LIKELY** | **INCONCLUSIVE** | **RULED OUT**
168
+
169
+ ### 5. Cleanup (mandatory)
170
+
171
+ After reporting:
172
+
173
+ 1. Delete the investigation script.
174
+ 2. Delete any temp files it created (`/tmp`, `scripts/_investigate/` if empty).
175
+ 3. Do not leave `_investigate-*` files in the repo.
176
+
177
+ ## Investigation patterns
178
+
179
+ ### Third-party API (e.g. GitHub)
180
+
181
+ - Verify required env vars are **set** (boolean), not their values.
182
+ - Make the smallest API call that answers the question (e.g. `GET /user` for token validity).
183
+ - Report HTTP status, rate-limit headers, and redacted error body.
184
+
185
+ ### Database
186
+
187
+ - **Preferred — SQL connector:** if the project has a SQL connector for the environment, use `connector_sql_schema` (structure) + `connector_query` (read-only query). No local script, no secrets. Match the connector to the environment (prod vs staging) — ask if unsure.
188
+ - **Fallback — no connector:** use `DATABASE_URL` from the chosen env file; run a read-only query via an ephemeral script.
189
+ - Either way, report row counts, existence checks, sample non-sensitive columns only.
190
+
191
+ ### Store / e-commerce data (Shopify)
192
+
193
+ - **Preferred — Shopify connector:** if the project has an active `shopify` connector, investigate through it. `shop_info` is the fastest liveness check (returns store name, domain, plan, currency); use `products_list` / `orders_summary` / `inventory_levels` for catalogue, sales, and stock questions. Discover the right op with `connector_search`, confirm params with `connector_describe`, run with `connector_execute` (`limit` to cap rows). No token handling, no script.
194
+ - **Read-only:** do not `approve` write ops while investigating — a plain call is a safe dry-run preview.
195
+ - **Fallback — no connector:** only then hit the Admin API with a token from the chosen env file via an ephemeral script; report status + redacted shape, never the token.
196
+
197
+ ### Internal HTTP route
198
+
199
+ - Call `BASE_URL` + endpoint with appropriate auth from env.
200
+ - Compare response to expected shape; do not dump full payloads if they may contain PII.
201
+
202
+ ### Config / feature flag
203
+
204
+ - Check env var presence and non-empty; validate format (URL, UUID) without printing the value.
205
+
206
+ ## Hard rules
207
+
208
+ 1. **Connectors first** — if a SQL/service connector exists for the environment, use it (`connector_query` / `connector_sql_schema` for SQL; `connector_search` → `connector_describe` → `connector_execute` for a service like Shopify) instead of a script; only fall back to a script when none exists.
209
+ 2. **Right environment** — match the connector to the environment being investigated; if it's ambiguous which connector is prod vs staging, ask before querying.
210
+ 3. **No blind fixes** — investigate → report → wait for approval to fix.
211
+ 4. **No secrets in chat** — not in scripts, logs, commits, or responses (connectors keep credentials in the gateway; never print row data that may contain PII).
212
+ 5. **No committing** investigation scripts or env files.
213
+ 6. **Prod caution / read-only investigation** — confirm with the user before `prod.env` or any write/mutate operation. SQL connectors are read-only-enforced (`connector_query` cannot mutate); service-connector writes (e.g. Shopify `product_update`) are approval-guarded — during investigation never pass `approve:true`, keep to read ops and dry-run previews.
214
+ 7. **Delete scripts** after every investigation run.
215
+
216
+ ## Examples
217
+
218
+ See [examples.md](examples.md) for script templates (GitHub token check, DB connectivity, SMTP handshake).
@@ -0,0 +1,170 @@
1
+ # Investigation examples
2
+
3
+ Prefer a **connector** (no script) when the project has one; otherwise use the
4
+ ephemeral **script** templates — copy, adapt, run once, delete.
5
+
6
+ ## Database via SQL connector (PREFERRED — no script)
7
+
8
+ Use the Xevy SQL tools directly; nothing is written to disk, credentials stay
9
+ in the gateway, and queries are read-only-enforced.
10
+
11
+ ```text
12
+ 1. Find the connector for the environment you're investigating:
13
+ connector_list { workspaceIdentifier, projectIdentifier, serviceName: "sql" }
14
+ → pick the one whose name matches the target env (e.g. "Production Database").
15
+ If ambiguous which is prod vs staging, ASK the user before querying.
16
+
17
+ 2. Learn the structure (optional but recommended):
18
+ connector_sql_schema { workspaceIdentifier, projectIdentifier, connectorId }
19
+ → { schemas: [{ name, tables: [{ name, columns: [{ name, dataType }] }] }] }
20
+
21
+ 3. Run a read-only query (writes are rejected; results are row-capped):
22
+ connector_query {
23
+ workspaceIdentifier, projectIdentifier, connectorId,
24
+ sql: "SELECT count(*) AS failed FROM jobs WHERE status = 'failed'
25
+ AND created_at > now() - interval '1 day'",
26
+ maxRows: 1000
27
+ }
28
+ → { columns: ["failed"], rows: [[7]], rowCount: 1, truncated: false }
29
+ ```
30
+
31
+ Report the counts/facts only — never dump rows that may contain PII.
32
+
33
+ ## GitHub OAuth credentials check
34
+
35
+ ```typescript
36
+ // scripts/_investigate/_investigate-github-oauth.ts
37
+ import { config } from "dotenv";
38
+ import { resolve } from "node:path";
39
+
40
+ const envFile = process.env.ENV_FILE ?? ".env";
41
+ config({ path: resolve(process.cwd(), envFile) });
42
+
43
+ const clientId = process.env.GITHUB_CLIENT_ID;
44
+ const clientSecret = process.env.GITHUB_CLIENT_SECRET;
45
+
46
+ console.log("GITHUB_CLIENT_ID set:", Boolean(clientId));
47
+ console.log("GITHUB_CLIENT_SECRET set:", Boolean(clientSecret));
48
+
49
+ if (!clientId || !clientSecret) {
50
+ console.log("RESULT: missing credentials");
51
+ process.exit(1);
52
+ }
53
+
54
+ // Minimal app-level check — no token exchange, no secrets logged
55
+ const res = await fetch(
56
+ `https://api.github.com/applications/${clientId}/token`,
57
+ {
58
+ method: "POST",
59
+ headers: {
60
+ Accept: "application/vnd.github+json",
61
+ Authorization:
62
+ "Basic " +
63
+ Buffer.from(`${clientId}:${clientSecret}`).toString("base64"),
64
+ },
65
+ body: JSON.stringify({ access_token: "probe-invalid" }),
66
+ signal: AbortSignal.timeout(15_000),
67
+ }
68
+ );
69
+
70
+ console.log("GitHub API status:", res.status);
71
+ console.log(
72
+ "RESULT:",
73
+ res.status === 401 || res.status === 404
74
+ ? "credentials rejected (check values)"
75
+ : res.status === 422
76
+ ? "credentials accepted (invalid token expected)"
77
+ : `unexpected status ${res.status}`
78
+ );
79
+ ```
80
+
81
+ ## Database connectivity (FALLBACK — only when no SQL connector exists)
82
+
83
+ ```typescript
84
+ // scripts/_investigate/_investigate-db.ts
85
+ import { config } from "dotenv";
86
+ import { resolve } from "node:path";
87
+ import pg from "pg";
88
+
89
+ const envFile = process.env.ENV_FILE ?? ".env";
90
+ config({ path: resolve(process.cwd(), envFile) });
91
+
92
+ const url = process.env.DATABASE_URL;
93
+ console.log("DATABASE_URL set:", Boolean(url));
94
+ if (!url) process.exit(1);
95
+
96
+ const client = new pg.Client({ connectionString: url });
97
+ try {
98
+ await client.connect();
99
+ const { rows } = await client.query("SELECT current_database(), now()");
100
+ console.log("Connected to database:", rows[0]?.current_database);
101
+ console.log("Server time:", rows[0]?.now);
102
+ console.log("RESULT: ok");
103
+ } catch (err) {
104
+ console.log("RESULT: failed");
105
+ console.log("Error:", err instanceof Error ? err.message : String(err));
106
+ process.exit(1);
107
+ } finally {
108
+ await client.end();
109
+ }
110
+ ```
111
+
112
+ ## SMTP handshake (no send)
113
+
114
+ ```typescript
115
+ // scripts/_investigate/_investigate-smtp.ts
116
+ import { config } from "dotenv";
117
+ import { resolve } from "node:path";
118
+ import nodemailer from "nodemailer";
119
+
120
+ const envFile = process.env.ENV_FILE ?? ".env";
121
+ config({ path: resolve(process.cwd(), envFile) });
122
+
123
+ const host = process.env.SMTP_HOST;
124
+ const port = Number(process.env.SMTP_PORT ?? 587);
125
+ const user = process.env.SMTP_USER;
126
+
127
+ console.log("SMTP_HOST set:", Boolean(host));
128
+ console.log("SMTP_USER set:", Boolean(user));
129
+ console.log("SMTP_PORT:", port);
130
+
131
+ if (!host) process.exit(1);
132
+
133
+ const transport = nodemailer.createTransport({
134
+ host,
135
+ port,
136
+ secure: port === 465,
137
+ auth: user ? { user, pass: process.env.SMTP_PASSWORD } : undefined,
138
+ });
139
+
140
+ try {
141
+ await transport.verify();
142
+ console.log("RESULT: SMTP verify ok");
143
+ } catch (err) {
144
+ console.log("RESULT: SMTP verify failed");
145
+ console.log("Error:", err instanceof Error ? err.message : String(err));
146
+ process.exit(1);
147
+ }
148
+ ```
149
+
150
+ ## Internal API health
151
+
152
+ ```typescript
153
+ // scripts/_investigate/_investigate-health.ts
154
+ import { config } from "dotenv";
155
+ import { resolve } from "node:path";
156
+
157
+ const envFile = process.env.ENV_FILE ?? ".env";
158
+ config({ path: resolve(process.cwd(), envFile) });
159
+
160
+ const base = process.env.BASE_URL ?? `http://127.0.0.1:${process.env.PORT ?? 3000}`;
161
+ console.log("Target:", base.replace(/\/\/.*@/, "//[REDACTED]@")); // strip creds from URL if any
162
+
163
+ const res = await fetch(`${base}/api/health`, {
164
+ signal: AbortSignal.timeout(10_000),
165
+ });
166
+ const body = await res.json().catch(() => null);
167
+ console.log("Status:", res.status);
168
+ console.log("Body:", body);
169
+ console.log("RESULT:", res.ok ? "ok" : "unhealthy");
170
+ ```