@xevy/skills 0.1.51 → 0.1.53

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.
@@ -2,7 +2,7 @@
2
2
  "name": "xevy",
3
3
  "displayName": "Xevy",
4
4
  "description": "Native /xevy:* SDLC workflow commands driven through the Xevy MCP server. Analyze, plan, execute, fix, and move-to-qa run locally by default and accept --cloud for the server Web Agent. Merge stays local; merge-pull-request evaluates and lands the remote PR.",
5
- "version": "0.1.51",
5
+ "version": "0.1.53",
6
6
  "author": {
7
7
  "name": "Xevy"
8
8
  },
package/README.md CHANGED
@@ -112,8 +112,7 @@ with `codex mcp add`.
112
112
  | `generate-image` | Generate an image and save it in the project Gallery |
113
113
  | `seo-research` | Run and explain decision-led SEO reports and supporting research |
114
114
  | `xevy-setup` | Link repo, `.xevy/project.json`, deploy defaults, env sync |
115
- | `analyze [task] [--cloud]` | Task analysis (local by default) |
116
- | `plan [task] [--cloud]` | Planning + review (local by default) |
115
+ | `plan [task] [--cloud]` | Reconnaissance, numbered technical steps, and linked visualization for approval |
117
116
  | `execute [task] [--cloud]` | Build, verify, and open a PR (local by default) |
118
117
  | `fix [task] [--cloud]` | Rework after review (local by default) |
119
118
  | `merge [task]` | Merge a task branch locally for review; leaves remotes and pull requests unchanged |
@@ -123,7 +122,7 @@ with `codex mcp add`.
123
122
  | `investigate` | Diagnose with ephemeral scripts (.env; no secrets) |
124
123
  | `create-xevy-task` | Capture session work into a task |
125
124
 
126
- The analyze, plan, execute, fix, and move-to-qa skills run in the current coding-agent session by default. Add the exact `--cloud` flag before or after the task code to delegate one of those workflows to Xevy's server agent, for example `execute VI22-01 --cloud`. Merge stays local; `merge-pull-request` evaluates and lands an open pull request.
125
+ The plan, execute, fix, and move-to-qa skills run in the current coding-agent session by default. Add the exact `--cloud` flag before or after the task code to delegate one of those workflows to Xevy's server agent, for example `execute VI22-01 --cloud`. Merge stays local; `merge-pull-request` evaluates and lands an open pull request.
127
126
 
128
127
  ## Computer and verified guides
129
128
 
@@ -137,7 +136,7 @@ Use generate-guide to make docs/guides/customer-form/manual.md with screenshots
137
136
 
138
137
  Computer works across desktop and browser apps and projects. Windows uses the signed-in desktop; macOS 14+ requires native Screen Recording and Accessibility consent. The guide workflow stays in the active engine, respects blocks and human take-over, and identifies incomplete verification or publication. Execute/fix use it for UI journeys when an authorized test environment is available.
139
138
 
140
- The package version is `0.1.41`. Run `npx @xevy/skills update -y` after that version is published.
139
+ The package version is `0.1.53`. Run `npx @xevy/skills update -y` after that version is published.
141
140
 
142
141
  ## Security
143
142
 
package/bin/cli.mjs CHANGED
@@ -30,6 +30,7 @@ const pkgRoot = path.resolve(here, "..");
30
30
  const DEFAULT_BASE = "https://xevy.ai";
31
31
  const DEFAULT_AGENTS = ["cursor", "claude-code", "codex"];
32
32
  const RETIRED_SKILLS = [
33
+ "analyze",
33
34
  "analyze-here",
34
35
  "bot",
35
36
  "bot-agent",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/skills",
3
- "version": "0.1.51",
3
+ "version": "0.1.53",
4
4
  "description": "Install Xevy agent skills and secure per-agent MCP transports for Cursor, Claude Code, Codex, and other coding agents.",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -23,7 +23,7 @@ For browser work, use tab-scoped browser actions when the companion advertises t
23
23
 
24
24
  Call `browser.connect` with the selected `browserId` and `profileId` to attach to an existing local debugging endpoint. A running browser with a usable endpoint should remain open. If there is no endpoint, explain that starting debugging requires closing and reopening the selected browser/profile. Send `restart: true` only when that restart is authorized; never terminate another profile to obtain a port. The companion owns the loopback debugging connection. Do not connect directly to a debug port from the agent host or expose it across the network.
25
25
 
26
- Create a task-owned tab with `browser.newTab {url}` before parallel browser work, then use `browser.tabs`, `browser.navigate`, `browser.snapshot`, `browser.inspect`, `browser.click`, `browser.scroll`, `browser.type`, and `browser.key` as needed. `browser.snapshot {tabId,fullPage:true}` captures a bounded full page; `browser.inspect {tabId,selector?,limit?}` returns page title, URL, and bounded element metadata without running an arbitrary script. `browser.closeTab {tabId}` closes a tab owned by your session. A second agent cannot change a tab another agent owns; use a separate tab. Read every command result and take a fresh snapshot after input, since successful input dispatch alone does not prove the page changed. Browser coordinates belong to the selected tab viewport; they are distinct from desktop screen coordinates. Prefer `browser.snapshot` for evidence because it captures the tab without unrelated desktop windows. `browser.disconnect` releases this session's browser connection; it closes a managed browser only when no other session uses it. Follow the tool's current schema and capability list, since older companion versions may offer desktop actions only.
26
+ Create a task-owned tab with `browser.newTab {url}` before parallel browser work, then use `browser.tabs`, `browser.navigate`, `browser.snapshot`, `browser.inspect`, `browser.click`, `browser.scroll`, `browser.type`, and `browser.key` as needed. `browser.snapshot {tabId,fullPage:true}` captures a bounded full page; `browser.inspect {tabId,selector?,limit?}` returns page title, URL, and bounded element metadata without running an arbitrary script. `browser.closeTab {tabId}` closes a tab owned by your session. A second agent cannot change a tab another agent owns; use a separate tab. Read every terminal command result and request a fresh snapshot after input. Use its saved reference and server evaluation to verify the changed page. Successful input dispatch establishes execution; verify the application outcome separately. Browser coordinates belong to the selected tab viewport; they are distinct from desktop screen coordinates. Prefer `browser.snapshot` for evidence because it captures the tab without unrelated desktop windows. `browser.disconnect` releases this session's browser connection; it closes a managed browser only when no other session uses it. Follow the tool's current schema and capability list, since older companion versions may offer desktop actions only.
27
27
 
28
28
  ## Observe, act, verify
29
29
 
@@ -33,7 +33,7 @@ For file transfer, use absolute paths and chunks of at most 192 KiB. Download wi
33
33
 
34
34
  ### Recover an expired command result
35
35
 
36
- Poll `computer_command` to terminal status promptly and retain the needed result locally within the authorized task. Bulk results, including screenshots, shell output and file bytes, expire after 60 seconds. A terminal command may return `resultExpired: true` and an optional content-free `command.receipt`; an expired result leaves the recorded command status intact.
36
+ Poll `computer_command` to terminal status promptly. Successful Browser/Desktop snapshots are saved privately and evaluated server-side before the tool returns their immutable `image` handle and `analysisStatus`. Retain the command ID, `image.reference`, attachment/version/hash, and verified `localFilePath` when returned. Temporary capture bytes expire after 60 seconds, while a saved capture can be reused under current session authority. Shell output and file bytes remain ephemeral bulk results. A terminal command may return `resultExpired: true` and an optional content-free `command.receipt`; an expired result leaves the recorded command status intact.
37
37
 
38
38
  A receipt is scoped to its creating session and current generation. Successful `file.uploadStart` receipts carry `{transferId,nextOffset,maxChunkBytes}`; `file.uploadChunk` receipts carry `{transferId,nextOffset,bytesWritten}`; `file.uploadCommit` carries `{committed:true}`; `file.uploadCancel` carries `{transferId,cancelled:true}`. Match the command ID, action, session ID and generation before using one. Resume an upload from its acknowledged `nextOffset` with the saved local bytes and checksum. A receipt reports acknowledged progress at that command; inspect later command results before choosing an offset when later chunks were queued. A commit receipt establishes that commit executed; inspect `file.stat` and download/check the destination when its content matters.
39
39
 
@@ -44,7 +44,7 @@ When the result expires, use the safe receipt to reconcile owned work. Never rep
44
44
  ### Verify desktop actions
45
45
 
46
46
  1. Request `desktop.monitors` and `desktop.windows` through `computer_action`, then read their `computer_command` results. Select the actual target window and monitor.
47
- 2. Request `desktop.snapshot` and inspect the image returned by `computer_command`. Identify controls from the current image. Coordinates use physical pixels in the monitor's global desktop coordinate space.
47
+ 2. Request `desktop.snapshot`, then read the saved image handle and server analysis from `computer_command`. Ask a specific question through `instructions`. For small controls, repeat `computer_command` with the same command ID and a normalized `region: {x,y,width,height}` to evaluate a focused crop of the saved original. Prefer current window/control metadata where available. Map evaluated bounds to the original screenshot and monitor origin; desktop actions use physical pixels in global desktop coordinates.
48
48
  3. Queue bounded actions with the current generation: focus, launch a supported application, click, drag, scroll, type, or press a key. Use observations to choose the next dependent action.
49
49
  4. Read each command until a terminal result, then take a fresh screenshot and check the expected app result. For a transaction, verify its final state, such as the saved file, submitted record, or visible deletion confirmation. Native input success establishes that the action executed; business success requires observed application evidence.
50
50
  5. A timeout or lost acknowledgement leaves the result uncertain. Inspect command status and the desktop before retrying a write. Resume from the observed state; avoid repeating a submit, payment, send, or delete whose outcome is unresolved.
@@ -52,7 +52,11 @@ When the result expires, use the safe receipt to reconcile owned work. Never rep
52
52
 
53
53
  Use the actual tool argument names and response envelope. Queue `const {command} = await computer_action({computerId, sessionId, generation, action: 'desktop.snapshot', payload: {}, operationId, summary: 'Verify the test record'})`, then read `await computer_command({computerId, commandId: command.id})`. The action response is `{command: {...}}`; take the ID from its nested `command`, while MCP clients parse the response's JSON text content. Read each action's current payload schema before constructing inputs.
54
54
 
55
- Screenshot command responses include an image block and JSON text with the command envelope, including its ID, session ID, generation, action, status, and result metadata. Inspect both: the image establishes the visible outcome and the envelope associates it with the command being verified. Image bytes are omitted from the JSON text. For an authorized guide, save the selected terminal capture immediately with `computer_save_capture` using its command reference and actual schema. Retain the returned private attachment ID and capture metadata. This explicitly persists the original bytes; an image block alone provides no file to read. For HTML publication, refer to the saved ID as `xevy-capture:ATTACHMENT_UUID` in an image source and call `computer_create_guide`; it validates ownership and embeds the bytes server-side without sending image base64 through the model. Shell and file responses remain JSON command results; decode file chunks locally and verify their checksums. A tool transport response alone proves neither a completed command nor a completed app transaction.
55
+ Screenshot command responses carry the command envelope, private `capture` metadata, immutable `image` handle, and `analysisStatus`. Read `analysis` when the status is `ready`; `failed` or `pending` keeps the original image reference available for a retry. Supply task-specific `instructions`, use a focused normalized `region` for details, or `analyze: false` when saving evidence without evaluation. The server uses a bounded analysis copy or crop and preserves the original image bytes. `analysisDimensions` records original dimensions, crop offsets, and scale; evaluated target bounds use the original coordinate space. Use a viewport capture for browser clicks, since full-page image coordinates span the document.
56
+
57
+ Keep image bytes outside the main agent context. A returned local path identifies a verified file in the registered `artifact_workspace`; consume it with local helpers when composing artifacts. `computer_save_capture` reuses the saved original and returns stable capture metadata. An expired temporary result requires a fresh snapshot only when the original has never been saved or current authority no longer permits reuse. Repeated successful saves and evaluations use the same capture, so an analysis failure provides no reason to recapture or regenerate.
58
+
59
+ For HTML publication, use `<img src="xevy-image:ATTACHMENT_UUID@VERSION">` with the returned reference and call `computer_create_guide`. The tool also accepts original `xevy-capture:ATTACHMENT_UUID` references. It verifies current ownership, session, project, generation and permissions before embedding exact original bytes. A mixed guide may include authorized uploaded/generated `xevy-image:` sources from the same project; Computer sources retain their session checks. Shell and file responses remain JSON command results; decode file chunks locally and verify checksums. A successful tool request establishes transport; terminal status and relevant evidence establish the operation result.
56
60
 
57
61
  Only after reading terminal operation commands and the relevant final evidence, record the verified result with:
58
62
 
@@ -81,8 +85,8 @@ Enabled action/application block rules govern every action. Report the matching
81
85
 
82
86
  Use an authorized account and safe test fixtures. Keep credentials in the existing authenticated session or approved credential mechanism. User authorization governs external writes: a walkthrough or test uses the agreed test environment and records. Unexpected production changes, customer messages, financial transactions, or destructive writes require their own authorization.
83
87
 
84
- Keep passwords, tokens, typed values, screenshots, raw keys, pointer trails, and personal data out of operation summaries and diagnostic logs. Screen frames and command results remain bounded in memory and expire; inspect them while available. The companion's durable audit outbox has a 100 MiB cap and pauses at capacity. Report `audit_full` and let supported recovery drain it; preserve pending audit evidence. Activity retains the latest 2,000 segments per Computer. Logical activity limits include all retained segments for selected operations; older segments expire at that boundary.
88
+ Keep passwords, tokens, typed values, screenshots, raw keys, pointer trails, and personal data out of operation summaries and diagnostic logs. Temporary screen transport and bulk command results remain bounded in memory and expire. Retain saved image references and use their server analysis under current authority. The companion's durable audit outbox has a 100 MiB cap and pauses at capacity. Report `audit_full` and let supported recovery drain it; preserve pending audit evidence. Activity retains the latest 2,000 segments per Computer. Logical activity limits include all retained segments for selected operations; older segments expire at that boundary.
85
89
 
86
- For an explicitly requested guide, save only the necessary authentic screenshots from safe fixtures through the capture-save tool or into the registered temporary / verified gitignored artifact workspace, then package them as authorized by [generate-guide](../generate-guide/SKILL.md). Treat every other screen capture as ephemeral. Arrange the screen and use safe fixtures so captures contain no sensitive material. Never redact or mask screenshots. If safe capture is unavailable, omit the capture and report the capture blocker; keep publication private.
90
+ Snapshots used for authorized observation are saved privately. For an explicitly requested guide, select only the necessary authentic screenshots from safe fixtures and package their original references as authorized by [generate-guide](../generate-guide/SKILL.md). Arrange the screen and use safe fixtures so captures contain no sensitive material. Never redact or mask screenshots. If safe capture is unavailable, omit the capture and report the capture blocker; keep publication private.
87
91
 
88
92
  The autonomous server extension inherits its task and can control only associated sessions and results. When pairing, rule administration, screenshot export, or publication tools are unavailable, report the exact handoff needed. Use the current engine and available tools; Computer usage never delegates a local run to the cloud.
@@ -94,7 +94,7 @@ The built-in helper deliberately keeps the Artifact in an opaque sandbox. Absolu
94
94
 
95
95
  - Make the main information or interaction immediately clear.
96
96
  - Use semantic HTML, visible keyboard focus, labelled controls, sufficient contrast, responsive layout, and `prefers-reduced-motion` where motion is present.
97
- - Use system fonts, inline SVG, CSS, and data URLs only. Do not reference CDNs, remote fonts, images, APIs, iframes, server-submitting forms, or any script or stylesheet other than the optional built-in Xevy report theme above.
97
+ - Use system fonts, inline SVG, CSS, saved `xevy-image:ATTACHMENT_UUID@VERSION` references in image sources, and locally composed data URLs. Do not reference CDNs, remote fonts, images, APIs, iframes, server-submitting forms, or any script or stylesheet other than the optional built-in Xevy report theme above.
98
98
  - Keep state local. Do not assume cookies, same-origin access, parent-page DOM access, or unrestricted storage. The manifest-selected built-in script may use only its documented one-way print `postMessage`; custom Artifact code must not inspect or control the parent.
99
99
  - Escape user-supplied values inserted into markup or JavaScript.
100
100
  - Include real content. Do not leave placeholder controls, lorem ipsum, TODOs, or buttons that do nothing.
@@ -121,7 +121,7 @@ Return strict JSON, not JavaScript or a fenced code block. Use a stable top-leve
121
121
 
122
122
  ### PDF
123
123
 
124
- Store real PDF bytes only. Use `sourceUrl` for an existing public PDF or `dataBase64` when the environment has already produced a valid PDF binary. Never place PDF-looking text in `textContent`; Xevy validates the `%PDF-` signature.
124
+ Store real PDF bytes only. Use `sourceUrl` for an existing public PDF, or `filePath` / direct upload for a locally generated PDF. Stream its bytes with a local helper. Never place PDF-looking text in `textContent`; Xevy validates the `%PDF-` signature.
125
125
 
126
126
  ### Excalidraw
127
127
 
@@ -133,13 +133,15 @@ Before saving, verify that the selected format parses, the requested content is
133
133
 
134
134
  Choose a concise kebab-case filename with the exact extension from the format table and a one-sentence description. With filesystem access, call `artifact_workspace` when available and save the draft in its registered session-owned temporary directory. A project-local fallback must pass `git check-ignore` for each generated file before writing. Generated artifact HTML, PDFs, screenshot files and verification records stay outside tracked repository paths and commits. An explicit request to maintain repository documentation has its own destination. Continue within existing task authorization; artifact creation adds no routine approval prompt.
135
135
 
136
- For an HTML guide with saved Computer screenshots, use the returned private capture attachment IDs as `<img src="xevy-capture:ATTACHMENT_UUID" alt="Step result">` references and call `computer_create_guide` with its current schema. It validates referenced captures against the authenticated session/project and embeds the bytes server-side. The resulting guide is private and self-contained; verify its stored version, images and exact viewer URL. An unsupported or expired capture requires fresh evidence; the visible tool image cannot be decoded by copying it from chat.
136
+ For an HTML guide with saved Computer screenshots, use `<img src="xevy-image:ATTACHMENT_UUID@VERSION" alt="Step result">` references and call `computer_create_guide`. Original `xevy-capture:ATTACHMENT_UUID` references also work. The tool checks current session/project authority and embeds exact original bytes. Mixed guides may include authorized project-uploaded/generated references while Computer images retain their session checks. Verify the stored version, images and exact viewer URL.
137
+
138
+ For other project images, retain the immutable handle returned by upload/generation or `analyze_attachment`, and embed its `image.reference` in HTML image sources. `create_attachment` and direct-upload completion resolve authorized original versions server-side. Analysis runs against a separate resized copy or focused crop; artifacts use the full original. Retry failed/pending evaluation against the saved version. Public artifacts require publicly shared image sources; private Computer images stay in the fenced Computer guide path. Use returned local paths with local composition helpers for other formats, preserving originals and keeping bytes outside main-agent context.
137
139
 
138
140
  For other project Artifacts, prefer file transfer so the file bytes stay outside model context and MCP JSON arguments:
139
141
 
140
- 1. When `create_attachment` exposes `filePath`, call it with a regular file inside the registered temporary workspace or the tool’s permitted project path, exact `mimeType`, matching `fileName`, `description`, optional resolved `taskId`, and `public: false` unless the user explicitly requested a public/shareable Artifact. This streams files up to 100 MB.
141
- 2. Through MCP, call `prepare_attachment_upload` with the exact filename, MIME type, byte size, description, optional task UUID, and visibility. PUT the local file bytes to the returned `uploadUrl` using the exact `uploadMethod` and `requiredHeaders`, then call `complete_attachment_upload` with the returned `attachmentId`. Completion validates the byte count, signature, and Artifact security state before the viewer URL becomes readable.
142
- 3. Use `create_attachment` with `textContent`, `sourceUrl`, or `dataBase64` when direct local file transfer is unavailable. Keep inline content for small files; use `sourceUrl` for an existing public binary.
142
+ 1. When `create_attachment` exposes `filePath`, call it with a regular file inside the registered temporary workspace or the tool’s permitted project path, exact `mimeType`, matching `fileName`, `description`, optional resolved `taskId`, and `public: false` unless the user explicitly requested a public/shareable Artifact. This streams accepted files up to 100 MB; images are limited to 25 MB.
143
+ 2. Through MCP, call `prepare_attachment_upload` with the exact filename, MIME type, byte size, description, optional task UUID, and visibility. PUT the local file bytes to the returned `uploadUrl` using the exact `uploadMethod` and `requiredHeaders`, then call `complete_attachment_upload` with the returned `attachmentId`. Completion validates the uploaded byte count, expands authorized HTML image references, and checks the final signature, embedded size and Artifact security state before the viewer URL becomes readable.
144
+ 3. Use `create_attachment` with `textContent` for a small text-backed artifact or `sourceUrl` for an existing public binary when local transfer is unavailable. Export built-in image output to a local file with the host helper before uploading; keep binary/base64 bytes outside main-agent arguments.
143
145
 
144
146
  Text-backed Artifacts remain limited to 10 MB after decoding for safe parsing and preview. Direct upload supports PDFs and other accepted files up to 100 MB. Never split one Artifact across calls or place a large file in base64 tool arguments.
145
147
 
@@ -12,7 +12,7 @@ Turn what just happened in this session into an Xevy task a **human developer or
12
12
 
13
13
  ## 1. Decide the mode
14
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.
15
+ - **Avoid duplicates.** Is this work already tracked by an Xevy task (explicit session task/worktree context, 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
16
  - Pick a mode:
17
17
  - **Capture mode** (default when the AI changed code this session) → sections 2–5.
18
18
  - **Ordinary mode** (no AI work to capture, or `$ARGUMENTS` clearly describes a brand-new unrelated task) → section 6.
@@ -47,7 +47,7 @@ Check `list_tasks`/`find_task` once more before creating to avoid a duplicate.
47
47
  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:
48
48
  - Call `mcp__xevy__create_decision` with preset choices + explanations (optional follow-up per choice).
49
49
  - If the user is present, use the host's user-question mechanism first, then persist the answer with `create_decision` + `answer_decision`.
50
- - Open questions gate `/xevy:mark-ready`, analyze, plan, and execute until answered — keep them few and high-signal.
50
+ - Open questions gate `/xevy:mark-ready`, plan and execute until answered — keep them few and high-signal.
51
51
  - In **capture mode**, only raise decisions for real ambiguities in requirements or review routing — not for documented AI work.
52
52
  - In **ordinary mode**, this is the primary way to capture unresolved intake ambiguities.
53
53
 
@@ -62,7 +62,7 @@ After the task exists, if scope, approach, category/epic placement, or trade-off
62
62
  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.
63
63
 
64
64
  ## 7. Report
65
- 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 and analyze/plan while draft (ordinary mode). After planning, AI Agent-owned Process Owner stages advance automatically; human-owned stages wait for the user to run `/xevy:mark-ready`.
65
+ 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 and plan while draft (ordinary mode). After planning, AI Agent-owned Process Owner stages advance automatically; human-owned stages wait for the user to run `/xevy:mark-ready`.
66
66
 
67
67
  ## Rules
68
68
  - Call order: `create_task` first, then any taskId-dependent call with its returned `task.id`; never retry a `Task not found` note call.
@@ -3,7 +3,7 @@ name: execute
3
3
  description: Execute code changes locally by default — use the task worktree, implement, push, and open a PR for separate verification and review. Pass --cloud to delegate implementation to the Xevy server agent, then review and correct its result.
4
4
  argument-hint: "[task] [--cloud]"
5
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__create_spec mcp__xevy__update_spec mcp__xevy__create_subtask mcp__xevy__list_subtasks mcp__xevy__update_subtask mcp__xevy__list_task_notes mcp__xevy__create_task_note mcp__xevy__update_task_note mcp__xevy__list_sprints mcp__xevy__assign_task_to_sprint mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions set_session_task_lock"
6
+ allowed-tools: "Read Grep Edit Write Bash Agent mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__update_task_status mcp__xevy__get_task_plan mcp__xevy__list_specs mcp__xevy__create_spec mcp__xevy__update_spec mcp__xevy__list_subtasks mcp__xevy__update_subtask mcp__xevy__list_task_notes mcp__xevy__create_task_note mcp__xevy__update_task_note mcp__xevy__list_sprints mcp__xevy__assign_task_to_sprint mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
7
  ---
8
8
 
9
9
  # /xevy:execute — execute locally or in the cloud
@@ -20,32 +20,33 @@ Local implementation is the default. Pass the exact standalone `--cloud` flag to
20
20
 
21
21
  ## 1. Resolve and apply common gates
22
22
 
23
- - Resolve the remaining task argument or the in-context task. Read its `## Analysis`, plan spec, and subtasks. If planning artifacts are absent, inspect the code and prepare a concrete plan/checklist within the approved requirements before implementing. If scope or authorization prevents preparing it, record the missing prerequisite as blocked and continue independent authorized work.
24
- - Sprint gate: if an active sprint exists and the task is not on it, require `## Analysis` and `storyPoints` greater than zero, then call `assign_task_to_sprint`. If those prerequisites are missing, record the sprint prerequisite as blocked; preserve sprint and authorization gates without opening a question dialog.
23
+ - Resolve the task and read its current numbered Plan and linked visualization. Read the current Plan with `get_task_plan`. Show a short plan before substantial changes and wait for the user’s go-ahead. Continue approved work without asking again. Preserve original requirements and legacy history. An Analysis section and generated subtasks are never prerequisites.
24
+ - Sprint gate: if an active sprint exists and the task is not on it, require the Plan and `storyPoints` greater than zero, then call `assign_task_to_sprint`. Record missing sprint prerequisites as blocked and preserve authorization gates.
25
25
 
26
26
  ### Code-only checklist and resume fallback
27
27
 
28
- Classify the actual work described in each existing subtask and any resume note before following its next action; keywords and stage labels alone do not determine eligibility. Mark legacy purely investigative, validation, verification, QA, review, or procedural spec-lock items `skipped` with an explanation through `update_subtask`. Preparation belongs to Analyze/Plan; post-execution checks belong to separate **QA Notes** or **Technical Review Instructions**. Select the next pending code subtask when a stale resume target is workflow-only.
28
+ Classify the actual work described in each existing subtask and any resume note before following its next action; keywords and stage labels alone do not determine eligibility. Mark legacy purely investigative, validation, verification, QA, review, or procedural spec-lock items `skipped` with an explanation through `update_subtask`. Preparation belongs to Plan; post-execution checks belong to separate **QA Notes** or **Technical Review Instructions**. Select the next pending code subtask when a stale resume target is workflow-only.
29
29
 
30
- For mixed items, implement the concrete code portion and defer its workflow checks to those notes. Input-validation implementation and adding/editing test files remain code work. Procedural checklist requirements do not block Execute; existing unanswered Analyze/Plan decisions, missing authorization, and conflicting technical contracts remain blockers. If inline planning is authorized, finish investigation and feasibility checks before recording code-only implementation steps. If no code changes remain, report that truthfully; never create empty commits or claim skipped work produced implementation.
30
+ For mixed items, implement the concrete code portion and defer its workflow checks to those notes. Input-validation implementation and adding/editing test files remain code work. Procedural checklist requirements do not block Execute; existing unanswered Plan decisions, missing authorization, and conflicting technical contracts remain blockers. If inline planning is authorized, finish investigation and feasibility checks before recording code-only implementation steps. If no code changes remain, report that truthfully; never create empty commits or claim skipped work produced implementation.
31
31
 
32
32
  ## 2A. Local workflow (default)
33
33
 
34
34
  ### Decisions gate
35
35
 
36
- Call `mcp__xevy__list_task_decisions` before implementing. Existing unanswered Analyze/Plan and intake decisions, missing authorization, and scope or contract conflicts remain gates; record affected work as blocked and continue independent authorized work. For new material implementation choices, inspect the code and record `create_decision` with `raisedAtStage: "execute"`, exactly one `recommended: true` choice per question (including follow-ups), and evidence/rationale in explanations. The recommended path is answered by AI; continue without asking the user or re-running Analyze.
36
+ Call `mcp__xevy__list_task_decisions` before implementing. Existing unanswered Plan and intake decisions, missing authorization, and scope or contract conflicts remain gates; record affected work as blocked and continue independent authorized work. For new material implementation choices, inspect the code and record `create_decision` with `raisedAtStage: "execute"`, exactly one `recommended: true` choice per question (including follow-ups), and evidence/rationale in explanations. The recommended path is answered by AI; continue without asking the user or re-running Plan.
37
37
 
38
38
  ### Worktree protocol
39
39
 
40
40
  - Record the current branch and directory. Derive a canonical branch `xevy/<TASK-ID>-<slug>` using the task code or the first eight characters of its UUID. Reuse an existing task branch; never create a second branch for the same task.
41
41
  - Create or attach a git worktree in a sibling directory and change into it. When resuming, first merge the latest source branch (for example `git merge origin/main`). Do all work in the task worktree.
42
- - In Pi, call `set_session_task_lock(taskCode, taskId, taskTitle, worktreePath, branch)` immediately after attaching the worktree, using the absolute `git rev-parse --show-toplevel` path. If the tool is unavailable, continue while keeping the worktree rules.
42
+ - Verify the absolute worktree path with `git rev-parse --show-toplevel` and its branch with `git branch --show-current` before editing. Keep the task code, UUID, title, absolute worktree path, and branch in the session context. On resume or after changing directories, verify and refresh that context before continuing.
43
+ - Pass the absolute worktree path as `cwd` to every worker, together with the task code, UUID, title, branch, and assigned file scope. Each worker verifies its working directory and branch before editing.
43
44
  - Never commit or push on a protected branch (`master`, `main`, `develop`, `staging`); use only the `xevy/*` task branch.
44
45
 
45
46
  ### Implement
46
47
 
47
48
  - Move the task to `in_progress` with `update_task_status` when implementation begins. This mirrors cloud execution, which moves to `in_progress` at start and `for_review` on success.
48
- - Work through the remaining code subtasks in order, committing coherent code milestones without requiring per-subtask checks or sign-off. When useful and supported, dispatch builder/frontend subagents with the worktree as their working directory. Keep changes surgical, match existing style, and update subtask status through MCP.
49
+ - Work through the approved numbered steps in order, committing coherent code milestones without requiring per-subtask checks or sign-off. When useful and supported, dispatch builder/frontend subagents with the worktree as their working directory. Keep changes surgical, match existing style, and update existing legacy subtask status through MCP only when applicable; never generate subtasks from the Plan.
49
50
  - Before editing UI pages, components, app shell, forms, or styling, follow `/xevy:xevy-design` and the project's `./.xevy/design.md`.
50
51
  - Apply the Decisions gate policy to material choices discovered during implementation.
51
52
  - Record deferred verification, QA, and review in separate handoff notes. A code subtask is complete when its implementation is committed; workflow check completion is outside its checklist.
@@ -30,11 +30,11 @@ Call `mcp__xevy__list_task_decisions` before implementing. Existing unanswered A
30
30
 
31
31
  ### Locate the worktree
32
32
 
33
- Find the existing task worktree and branch with `git worktree list`, matching by task code. The worktree must already exist; do not create a new branch. If none exists, report the missing worktree as blocked. Merge the latest source branch into the feature branch first to avoid divergence.
33
+ Find the existing task worktree and branch with `git worktree list`, matching by task code. The worktree must already exist; do not create a new branch. If none exists, report the missing worktree as blocked. Verify the absolute worktree path with `git rev-parse --show-toplevel` and its branch with `git branch --show-current` before editing. Keep the task code, UUID, title, absolute worktree path, and branch in the session context; verify and refresh them on resume or after changing directories. Merge the latest source branch into the feature branch first to avoid divergence.
34
34
 
35
35
  ### Rework
36
36
 
37
- Make the requested code fix in the worktree with the host's read/search/edit tools, or use a builder subagent with that worktree as its working directory. Keep the change surgical and correct the root cause rather than symptoms. Commit coherent code milestones and update code subtasks through MCP; a committed implementation completes the code item without requiring verification, QA, or review completion.
37
+ Make the requested code fix in the worktree with the host's read/search/edit tools, or use a builder subagent with the verified absolute worktree path as `cwd`. Pass every worker the task code, UUID, title, branch, and assigned file scope; each worker verifies its working directory and branch before editing. Keep the change surgical and correct the root cause rather than symptoms. Commit coherent code milestones and update code subtasks through MCP; a committed implementation completes the code item without requiring verification, QA, or review completion.
38
38
 
39
39
  Before editing UI pages, components, app shell, forms, or styling, follow `/xevy:xevy-design` and the project's `./.xevy/design.md`.
40
40
 
@@ -18,7 +18,9 @@ Use the host's available browser observation tools for web journeys, or [compute
18
18
 
19
19
  Run the journey in the real app. Number the user actions in the order a user performs them. Each step states its starting condition, concrete action, and observable expected result. Capture the relevant controls and result from the actual application using safe fixtures. Include setup requirements, role/access requirements, and recovery guidance only where the user needs them.
20
20
 
21
- Persist each selected screenshot while its command result is still available. After observing the terminal snapshot, use `computer_save_capture` with its owned command reference and the current tool schema. Retain the returned attachment ID, MIME type, dimensions and capture time; an image block in chat supplies observation, while the capture-save tool supplies the reusable file. The save operation is idempotent for the same owned capture. If it is unavailable, use an actual file returned by the host capture tool; report a blocker only when neither path provides bytes.
21
+ Poll each snapshot with `computer_command` promptly. Successful Computer snapshots return a saved private original and a separate server evaluation. Retain the command ID, immutable `image.reference` (`xevy-image:ATTACHMENT_UUID@VERSION`), attachment ID, version, SHA256, dimensions and capture time. Retain the verified local path when the runtime returns one. `computer_save_capture` reuses that original; repeated successful saves return its stable metadata. For a host capture tool, save its actual local output with `create_attachment({filePath, ...})` or direct upload, then use `analyze_attachment` for the separate API evaluation.
22
+
23
+ Ask the evaluation a specific question about the step's visible controls and expected result. A normalized `region: {x,y,width,height}` requests a focused crop for small labels or controls while the original remains unchanged. Interpret bounds using `analysisDimensions` and the original coordinate space; use a viewport snapshot for browser clicks. An analysis status of `failed` or `pending` preserves the saved reference. Retry evaluation against that reference and record the step as uncertain until evidence establishes its result. Keep raw image bytes outside the main agent context; local helpers consume saved paths when composing files.
22
24
 
23
25
  Maintain a separate verification ledger with step ID, environment/build, fixture, expected and observed result, command/test references, screenshot path and capture time, and PASS/FAIL/BLOCKED. A native click or successful API call alone does not establish that the user's journey worked. Verify visible app state and meaningful persistence or downstream effects, using authorized read-only checks where useful.
24
26
 
@@ -28,7 +30,7 @@ Screenshots must show the step they support on the tested build. Generated illus
28
30
 
29
31
  Test every numbered step from its documented starting state. Exercise the intended outcome and relevant downstream journeys, such as reopening a saved record or using the next feature that consumes it. Record any error, block, uncertain write, or mismatch. On command timeout, inspect the app and command result before retrying; avoid duplicate writes.
30
32
 
31
- For Computer commands, poll terminal results while their 60-second bulk content is available. If `resultExpired` appears, follow [computer](../computer/SKILL.md) to reconcile an optional content-free `command.receipt`. Upload receipts retain transfer IDs, progress offsets or terminal flags within bounded memory; they provide no screenshot, file-content or application proof. An unavailable receipt after restart, expiry, eviction or a control change leaves recovery dependent on fresh evidence and owned cleanup. Keep the step uncertain until its effect is verified; preserve its operation ID and avoid replaying upload start or commit to recover an acknowledgement.
33
+ For Computer commands, poll terminal results while their temporary 60-second transport is available so snapshot originals can be saved automatically. Saved captures remain reusable under current session authority; their server evaluation can be retried independently. If `resultExpired` appears, follow [computer](../computer/SKILL.md) to reconcile an optional content-free `command.receipt`. Upload receipts retain transfer IDs, progress offsets or terminal flags within bounded memory; they provide no screenshot, file-content or application proof. An unavailable receipt after restart, expiry, eviction or a control change leaves recovery dependent on fresh evidence and owned cleanup. Keep the step uncertain until its effect is verified; preserve its operation ID and avoid replaying upload start or commit to recover an acknowledgement.
32
34
 
33
35
  When a failure belongs to the repository and repair is already authorized, use the isolated task branch/worktree and current engine. Reuse the task branch; keep unrelated work intact. Make a focused root-cause fix, run relevant repository checks, and refresh the existing test environment through its authorized local mechanism. The guide workflow grants no additional deploy or merge authority. For fixes outside approved scope, record the blocker and required decision while continuing independent verification.
34
36
 
@@ -42,7 +44,9 @@ Keep the copy-ready guide focused on the user's task: prerequisites, numbered ac
42
44
 
43
45
  Stage the guide, screenshots and verification ledger in the session-owned temporary directory returned by `artifact_workspace` when available. A project-local staging fallback must pass `git check-ignore` for every generated path before writing. Keep generated HTML, PDFs and screenshots out of tracked paths and commits; a request for an artifact uses private Drive as the final destination. Honour an explicit request for repository documentation separately. Use HTML by default and honour an explicit requested format or filename.
44
46
 
45
- For Computer screenshots, build ordinary HTML with `<img src="xevy-capture:ATTACHMENT_UUID" alt="Observable step result">` using each returned capture attachment ID, then call `computer_create_guide` with the current tool schema. The server validates ownership/project and embeds the actual private image bytes. Submit the small HTML template, keep CSS inline, and let the tool produce the self-contained file; do not reconstruct image bytes from a displayed image block or place screenshot base64 in model arguments. When real local screenshot files are available, embed those bytes with a local helper and upload the resulting file. For Markdown, use supported embedded images or project-local relative screenshot files; ensure the published viewer actually resolves them. For PDF, generate real PDF bytes from the finished guide and inspect the rendered pages. Follow [create-artifact](../create-artifact/SKILL.md) for format validation, file limits, viewer security, and supported upload paths.
47
+ For Computer screenshots, build ordinary HTML with `<img src="xevy-image:ATTACHMENT_UUID@VERSION" alt="Observable step result">` using each returned immutable reference, then call `computer_create_guide`. It embeds exact original bytes after checking current Computer authority and project access. Original `xevy-capture:ATTACHMENT_UUID` references also work. The same guide can include authorized uploaded/generated image references from the project. Submit the small HTML template with inline CSS; image bytes stay outside model arguments.
48
+
49
+ For other saved images, HTML `create_attachment` and direct-upload completion expand `xevy-image:` references server-side with authorized version checks. Use an actual local file and a local helper for Markdown/PDF composition; stream the finished file with `filePath` or prepare/PUT/complete. Ensure the published viewer resolves every Markdown image. For PDF, generate real PDF bytes from the finished guide and inspect the rendered pages through the available file evaluation/viewer path. Follow [create-artifact](../create-artifact/SKILL.md) for validation, final embedded size limits, viewer security and upload paths.
46
50
 
47
51
  Store only the selected safe screenshots needed for the requested guide. Keep credentials, customer data, typed secrets, screen bytes, raw keys, and pointer trails out of logs. Arrange the screen and use safe fixtures to keep sensitive material out of captures. Never redact or mask screenshots. If a safe capture is unavailable, omit it and report a capture blocker; keep publication private. Computer frames/results stay in bounded memory; the companion audit cap is 100 MiB. Keep stable operation IDs for logical transactions, verify business outcomes separately, and clean up only owned sessions using captured generations.
48
52
 
@@ -36,10 +36,12 @@ Use Xevy for Gallery storage regardless of which feature generates the image. Do
36
36
  - Pass the user's image description and any supported reference images directly to that feature.
37
37
  - After generation, call Xevy's `create_attachment` to save the output in the Gallery:
38
38
  - Prefer `sourceUrl` when the built-in feature returns a public `http(s)` image URL.
39
- - Pass a returned data URL directly as `dataBase64`. For a local file, encode its bytes as base64 and pass `dataBase64`; do not pass a local path as `sourceUrl`.
39
+ - For a local output, use `create_attachment` with `filePath` from the registered `artifact_workspace` or another permitted local path. Through MCP, use prepare/PUT/complete so a local helper streams the file bytes. A local path belongs in `filePath`; `sourceUrl` accepts public HTTP(S) URLs.
40
+ - If the host returns only a displayed image or data URL, use its native export/download helper to materialize a local file before transfer. When no byte-preserving export is available, report the Gallery save blocker. Keep image bytes outside main-agent text and tool arguments.
40
41
  - Pass `mimeType`, a friendly `fileName`, the prompt as `description`, optional `taskId`, and `public: true`.
41
- - Provide exactly one of `sourceUrl` or `dataBase64`; inline data must be no larger than 25 MB.
42
- - Report the URL and file name returned by `create_attachment`, and state that the image is available in the project Gallery.
42
+ - Select one transfer source. Images are limited to 25 MB; keep the original output unchanged.
43
+ - Retain the returned `image.reference`, version/hash and verified local path when available. Call `analyze_attachment` with the saved attachment/version and a concise question about whether the visible result matches the prompt. Use a focused `region` when details need inspection.
44
+ - Report the confirmed Gallery URL and file name. Ground statements about visible content in successful API analysis. A failed evaluation leaves the stored original available for a retry.
43
45
  - If attachment creation fails, report that the image was generated but not saved to the Gallery. Do not claim the request completed successfully.
44
46
 
45
47
  ## 5. Xevy path (explicit or fallback)
@@ -50,6 +52,7 @@ Use Xevy for Gallery storage regardless of which feature generates the image. Do
50
52
  - `prompt`
51
53
  - optional `model`, `size`, and `fileName`; `size` accepts `512`, `1K`, `2K`, `4K`, or explicit pixels such as `1024x1024`
52
54
  - optional resolved `taskId`
53
- 2. Report the returned clickable URL and file name, and state that the image is available in the project Gallery.
55
+ 2. Read the returned immutable image handle and `analysisStatus`. Xevy saves the original and evaluates a bounded copy against the prompt through its vision API. Use successful analysis to describe the visible result.
56
+ 3. Report the confirmed Gallery URL and file name. If evaluation fails or remains pending, retry `analyze_attachment` against the saved version; keep the successful generation and its reference.
54
57
 
55
- `generate_image` stores the result in the Gallery and returns `{ attachmentId, url, fileName, mimeType, sizeBytes, prompt, model }`. Xevy generation is a paid provider call: generate once per request and do not retry after success. Never print API keys or environment values. On failure, surface the tool's error without inventing a cause.
58
+ `generate_image` returns Gallery metadata plus `image: {attachmentId, versionNumber, sha256, mimeType, sizeBytes, reference, viewUrl}`, `analysisStatus`, and `analysis` when evaluation succeeds. Runtime tools may also return a verified `localFilePath`. Embed its exact original reference in HTML as `<img src="xevy-image:ATTACHMENT_UUID@VERSION">`; the server resolves the bytes during authorized artifact creation. Xevy generation is a paid provider call: generate once per request and do not retry after success. Never print API keys or environment values. On failure, surface the tool's error without inventing a cause.
@@ -19,11 +19,11 @@ Read the resolved task's status. `mark-ready` only promotes a task that is in **
19
19
  ## 3. Answer open questions (MANDATORY gate)
20
20
  - Call `mcp__xevy__list_task_decisions` for the task.
21
21
  - For **every** decision that is still OPEN, present the question and its preset choices to the user, then record their answer with `mcp__xevy__answer_decision` (pass the chosen `answerChoiceId` and/or `answerText`). Never fabricate an answer or skip an open question.
22
- - Answering may trigger a server-side analyze re-run — that is expected and does **not** change the task status.
22
+ - Answering may trigger a server-side Plan refresh — that is expected and does **not** change the task status.
23
23
  - Do not proceed while any decision is still open.
24
24
 
25
25
  ## 4. Mark ready
26
26
  Once **no** open decisions remain, call `mcp__xevy__update_task_status({ taskId, status: "ready" })`.
27
27
 
28
28
  ## 5. Report
29
- Report the task code/title, its new status (`ready`), and the task URL. Don't push the user into `/xevy:plan` or `/xevy:analyze` — let them choose the next step at their own pace.
29
+ Report the task code/title, its new status (`ready`), and the task URL. Don't push the user into `/xevy:plan` — let them choose the next step at their own pace.
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: plan
3
- description: Plan a task locally by default — finish investigation and plan validation, then record concrete code changes as ordered subtasks. Pass --cloud to delegate planning to the Xevy server agent, then review and correct its result.
3
+ description: Plan a task locally by default — inspect the code and write a short numbered technical plan with a linked visualization for human approval. Pass --cloud to delegate planning to the Xevy server agent, then review and correct its result.
4
4
  argument-hint: "[task] [--cloud]"
5
5
  disable-model-invocation: true
6
- allowed-tools: "Read Grep Bash Agent mcp__xevy__find_task mcp__xevy__create_spec mcp__xevy__update_spec mcp__xevy__list_specs mcp__xevy__get_spec mcp__xevy__create_subtask mcp__xevy__update_subtask mcp__xevy__list_subtasks mcp__xevy__list_task_notes mcp__xevy__create_task_note mcp__xevy__update_task_note mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision mcp__xevy__get_process_owners mcp__xevy__update_task_status mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
6
+ allowed-tools: "Read Grep Bash Agent mcp__xevy__find_task mcp__xevy__create_spec mcp__xevy__update_spec mcp__xevy__list_specs mcp__xevy__get_spec mcp__xevy__create_attachment mcp__xevy__create_attachment_version mcp__xevy__get_task_plan mcp__xevy__update_task mcp__xevy__list_task_notes mcp__xevy__create_task_note mcp__xevy__update_task_note mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision mcp__xevy__get_process_owners mcp__xevy__update_task_status mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
7
  ---
8
8
 
9
- # /xevy:plan — plan locally or in the cloud
9
+ # /xevy:plan — inspect and visualize
10
10
 
11
11
  Local planning is the default. Pass the exact standalone `--cloud` flag to delegate planning to the Xevy server agent.
12
12
 
@@ -18,53 +18,44 @@ Local planning is the default. Pass the exact standalone `--cloud` flag to deleg
18
18
  - If the Local workflow cannot be completed, stop and report exactly what is blocking it, then let the user decide whether to rerun with `--cloud`. Never switch engines mid-run and never run both.
19
19
  - With `--cloud`, follow the **Cloud workflow** and do not duplicate the work locally beyond the review-and-correct step it defines.
20
20
 
21
- ## 1. Resolve the task
21
+ ## 1. Resolve the task and investigate
22
22
 
23
- Resolve the remaining task argument or the in-context task. It should already have a `## Analysis` section. If it does not, suggest `/xevy:analyze` and stop.
23
+ Resolve the task argument or the in-context task. Read the original requirements, existing Plan, relevant code, similar patterns, and open decisions. Plan owns reconnaissance and feasibility checks; an Analysis section is never a prerequisite. Preserve original requirements and legacy task history.
24
24
 
25
- ## 2A. Local workflow (default)
25
+ Resolve routine technical choices from the code. Collect meaningful human questions together, persist them with `create_decision` at `raisedAtStage: "plan"`, and record human answers with `answerSource: "human"`. Open decisions block the affected work. Use a scout or independent plan reviewer when supported and authorized.
26
26
 
27
- ### Decisions gate and recon
27
+ ## 2A. Local workflow (default)
28
28
 
29
- Call `mcp__xevy__list_task_decisions`. If any decision is **open**, review the questions together through the host's user-question mechanism, record each human answer with `mcp__xevy__answer_decision`, and reflect it in the plan. Open decisions block AI work, so never guess or bypass them.
29
+ ### Write the concrete Plan
30
30
 
31
- When the host supports subagents, dispatch a **scout** for codebase recon covering relevant files, callers/callees, similar patterns, and baseline health. Otherwise perform the same recon in this session. Complete investigation, feasibility checks, and validation of the proposed approach during Analyze/Plan preparation. Preserve genuine authorization requirements and resolve conflicting technical contracts before implementation.
31
+ Write the canonical `## Plan` section in the task description. Synchronize an existing spec with kind `plan` when present; separate contract specs are optional when the changes need them. Use approximately five or six numbered steps; each Xevy step follows **Title — concise technical details**. Name the relevant files, functions or components, the change, and resulting behavior in one or two short sentences. Keep the plan proportionate to the task; use fewer steps for small changes.
32
32
 
33
- ### Write the plan
33
+ Example stored in Xevy:
34
34
 
35
- - Create a plan spec with `mcp__xevy__create_spec` using kind `plan`. Numbered implementation steps contain only concrete code changes: target files, changes, and expected behavior. Include a trace matrix: requirement → files → code change → expected behavior.
36
- - Create ordered subtasks with `mcp__xevy__create_subtask`, one per discrete code change, using fullstack or frontend stages. Group work into reviewable end-to-end pieces; keep frontend and backend work for one capability together.
37
- - Adding input-validation code and adding/editing test files are code work. Investigation, validation, running verification, QA, review, and procedural spec-lock work are outside the numbered implementation plan and subtask checklist.
38
- - Create or update separate task notes titled **QA Notes** and **Technical Review Instructions** for post-execution checks. Keep these checks out of subtask descriptions and dependencies.
35
+ 1. Remove Analyze — Remove the action from task controls, runner schemas, prompts, and packaged skills; retain historical executions and decisions.
36
+ 2. Simplify Plan — Write numbered technical steps to the task description; remove automatic subtask generation.
39
37
 
40
- ### Plan-review
38
+ Plan creates zero subtasks. Preserve existing subtasks and treat them as legacy guidance. Do not convert numbered steps into subtasks, a trace-matrix document, or a required checklist. Keep verification details in separate **QA Notes** or **Technical Review Instructions** when needed. Estimate `storyPoints` during Plan when the project uses sprint estimates.
41
39
 
42
- When the host supports subagents, dispatch a **plan-reviewer** to cross-check every matrix item against requirements, find orphans and gaps, and validate cross-flow risks and “must NOT” constraints during planning. Otherwise perform a separate self-review pass. Fold code changes into the spec and subtasks, and verification instructions into the separate handoff notes. Finish plan validation before finalizing the implementation checklist; do not create a review or sign-off subtask.
40
+ ### Link the visualization
43
41
 
44
- Scope each review to the approved requirements and inspected commit. In the first review pass, check the complete scope and report all findings together. Record requirement coverage, evidence references, and each finding's severity, location, expected behavior, and verification. In the second review pass, verify the fixes and regressions affected by those findings, reusing evidence that remains valid for the current commit and scope. A further pass requires a recorded reason: failed fix, new regression, missing evidence, or changed approved scope. Keep unresolved findings and unverified coverage visible, and report PARTIAL/FAIL until the required evidence supports approval.
42
+ Follow [create-artifact](../create-artifact/SKILL.md) to save a private project Artifact associated with the task UUID. Use self-contained HTML by default. Show the proposed UI, before/after behavior, or a clear flow of the changes; connect it to the numbered plan. Update an existing task visualization through a new attachment version when appropriate. Link the returned stable Artifact URL from the task's `## Plan` section and any existing matching plan spec. Never invent an Artifact URL. If publication is unavailable, report the exact gap and leave the plan awaiting completion.
45
43
 
46
- Finish inspecting the code and similar patterns, then collect all remaining meaningful human questions together before implementation. Persist each through `mcp__xevy__create_decision` with `raisedAtStage: "plan"`, preset choices, exactly one `recommended: true` choice per question, evidence/rationale in explanations, and necessary branching follow-ups. Resolve routine choices from the code. When the user is present, collect answers together and record each with `answer_decision` and `answerSource: "human"`.
44
+ ### Review and present the Plan
47
45
 
48
- ### Final check
46
+ Check every requirement against the inspected code, numbered steps, and visualization; correct gaps before presenting it. Do not create review/sign-off subtasks. Do not start Execute or change task status as a side effect of planning.
49
47
 
50
- Confirm the final plan is complete and feasible against the actual code and fix every remaining gap. Call `mcp__xevy__list_task_decisions` again and surface any decision that remains open. Do not change task status as a side effect of local planning. Draft is preparation-only; the user explicitly submits it to Ready. When planning is configured Refine work for a Ready task, completion moves it to Planned through the server-owned Process Owner flow. Do not start execution.
48
+ Read the current Plan with `get_task_plan`. In chat show only the short numbered titles, the task link, and visualization link. Keep the technical details in Xevy. For the example above, chat shows:
51
49
 
52
- Report a PASS/PARTIAL verdict, the matrix summary, open decisions, resulting status, and task URL.
50
+ 1. Remove Analyze.
51
+ 2. Simplify Plan.
53
52
 
54
- ## 2B. Cloud workflow (`--cloud`)
53
+ Show a short plan before substantial changes and wait for the user’s go-ahead. Continue approved work without asking again.
55
54
 
56
- ### Run the server action
55
+ Explain unresolved decisions or missing visualization separately and keep affected work blocked. Draft remains preparation until explicitly submitted to Ready.
57
56
 
58
- - Call `mcp__xevy__start_ai_action({ taskId, action: "plan", stream: true })`; always pass `stream: true`. Report live progress as it arrives. Do not use fire-and-forget or sleep/manual polling loops.
59
- - Only if the streamed call returns before a terminal status because of a genuine disconnect, resume with `mcp__xevy__get_ai_execution` (use `list_ai_executions` if needed).
60
- - On failure, surface the output and offer to retry or rerun `/xevy:plan` without `--cloud`.
61
-
62
- ### Review and correct
57
+ ## 2B. Cloud workflow (`--cloud`)
63
58
 
64
- - Read the produced plan spec (`list_specs` → `get_spec`) and subtasks (`list_subtasks`).
65
- - Build a trace matrix from every task/Analysis requirement to a subtask or plan step. Flag orphaned requirements and unjustified steps. Inspect the code with Read/Grep to confirm referenced files and approaches are real and feasible.
66
- - Check cross-flow risks such as guards, context rehydration, effects, and async side effects during planning. Put post-execution verification of “must NOT” constraints in separate QA Notes or Technical Review Instructions.
67
- - Correct the produced plan so numbered steps and subtasks contain only concrete code changes with expected behavior; remove workflow-only plan steps and move their checks to separate handoff notes. Retain input-validation implementation and test-file changes. Fix gaps by editing the spec or adding/reordering code subtasks through MCP. Apply the review passes above: consolidate the complete first-pass findings, then verify corrections and affected flows in the second pass. Record the reason for any further pass; retain unresolved matrix gaps and missing evidence in the verdict.
68
- - Do not change task status or start execution yourself. The server applies Process Owner automation after a successful run.
59
+ Call `start_ai_action({ taskId, action: "plan", stream: true })` and report live progress. If a genuine disconnect ends the stream early, resume through `get_ai_execution` or `list_ai_executions`. On failure, report the captured output and offer a retry in the selected engine.
69
60
 
70
- Report a PASS/PARTIAL verdict, gaps closed, resulting task status, and task URL.
61
+ Read the canonical task description Plan and any existing plan spec. Inspect referenced code and validate the numbered steps, concise technical details, requirement coverage, real linked task Artifact, and zero generated subtasks. Correct gaps in the task Plan, any existing matching spec, or Artifact; leave legacy subtasks intact. Apply the same short-title chat presentation and guidance as local planning. The server owns status automation.
@@ -54,4 +54,4 @@ Cursor, and other remote MCP clients use OAuth.
54
54
  - Read `get_project_workbreakdown`. Only when the project has no categories, create 3–6 user/product-area categories (never technical-layer categories such as Frontend or API) and 1–3 starter epics per category for already-present capabilities. If categories exist, skip this step. Never create tasks.
55
55
 
56
56
  ## 7. Report
57
- Summarise: workspace/project, repo link, deploy build pack + ports, count of env keys added (names only), and the next Xevy skills they can run (`analyze`, `execute`, `deploy`; slash-command names may be available in some clients). Do not print secrets.
57
+ Summarise: workspace/project, repo link, deploy build pack + ports, count of env keys added (names only), and the next Xevy skills they can run (`plan`, `execute`, `deploy`; slash-command names may be available in some clients). Do not print secrets.
@@ -1,68 +0,0 @@
1
- ---
2
- name: analyze
3
- description: Analyze a task locally in the current coding-agent session by default — inspect the codebase, write the Analysis section and story points, then self-review. Pass --cloud to delegate analysis to the Xevy server agent, then review and correct its result.
4
- argument-hint: "[task] [--cloud]"
5
- disable-model-invocation: true
6
- allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_specs mcp__xevy__list_subtasks mcp__xevy__list_task_notes mcp__xevy__create_task_note mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
- ---
8
-
9
- # /xevy:analyze — analyze locally or in the cloud
10
-
11
- Local analysis is the default. Pass the exact standalone `--cloud` flag to delegate the analysis to the Xevy server agent.
12
-
13
- ## 0. Choose the engine
14
-
15
- - Parse `$ARGUMENTS` for the exact standalone `--cloud` token and remove that token before resolving the task. Do not treat similar text such as `--cloudy`, `cloud`, or `--cloud=true` as the flag.
16
- - Without `--cloud`, follow the **Local workflow** and do not call `start_ai_action`. The missing flag is an explicit instruction to stay local: for the whole run, `mcp__xevy__start_ai_action`, `mcp__xevy__get_ai_execution`, and `mcp__xevy__list_ai_executions` are forbidden, and so is any other way of handing the work to the Xevy server agent.
17
- - Never infer the cloud engine from context. Task status, an earlier cloud run, an open pull request, an existing execution record, an idle local worktree, urgency, or a local step that turns out to be slow or hard are **not** consent. Only the literal flag selects the Cloud workflow.
18
- - If the Local workflow cannot be completed, stop and report exactly what is blocking it, then let the user decide whether to rerun with `--cloud`. Never switch engines mid-run and never run both.
19
- - With `--cloud`, follow the **Cloud workflow** and do not duplicate the work locally beyond the review-and-correct step it defines.
20
-
21
- ## 1. Resolve the task
22
-
23
- Resolve the remaining task argument or the in-context task (`mcp__xevy__find_task` / `find_task`). If ambiguous, ask which task. Read existing specs, subtasks, and notes.
24
-
25
- ## 2A. Local workflow (default)
26
-
27
- ### Decisions gate
28
-
29
- Call `mcp__xevy__list_task_decisions`. If any decision is **open**, review the questions together using their preset choices and explanations, record each human answer with `mcp__xevy__answer_decision`, and fold the answers into the analysis. Never guess or bypass an open decision.
30
-
31
- ### Inspect the codebase
32
-
33
- Read the relevant files, including callers, callees, and similar patterns. Identify whether the task involves UI changes; if so, study existing UI patterns and record a `UI/UX Flow` note with `mcp__xevy__create_task_note`. Base decisions on established patterns and ask only about genuine ambiguity.
34
-
35
- Complete investigation, feasibility checks, and validation of the proposed approach during Analyze/Plan preparation. Record findings and actual unresolved questions here. Later numbered plans and subtasks contain concrete code changes; post-execution verification, QA, and review belong to separate handoff notes and workflow.
36
-
37
- ### Write the Analysis
38
-
39
- Use `mcp__xevy__update_task` to append a `## Analysis` section without replacing the user's original request:
40
-
41
- - **Overview:** plain-language summary, before/after behaviour, user impact, and key decisions.
42
- - **Technical Implementation:** affected files/modules, API/data/UI changes, assumptions, risks, and verification approach.
43
- - Estimate `storyPoints` (1 trivial · 2 small · 3 medium · 5 large · 8 XL · 13 epic) and set it.
44
- - Finish inspecting the code and similar patterns, then gather all meaningful human questions together before implementation. Persist each through `mcp__xevy__create_decision` with `raisedAtStage: "analyze"`, preset choices, exactly one `recommended: true` choice per question, evidence/rationale in explanations, and necessary branching follow-ups. Resolve routine choices from the code. If the user is present, collect answers together through the host's user-question mechanism and record each with `answer_decision` and `answerSource: "human"`.
45
-
46
- ### Review and correct
47
-
48
- Re-read the Analysis against the actual code. Confirm every claim is accurate, affected files exist, and risks and acceptance criteria are concrete. Fix every gap or inaccuracy before finishing. Call `mcp__xevy__list_task_decisions` again and surface any decision that remains open.
49
-
50
- Report a PASS/PARTIAL verdict, what you corrected, any open decisions, and the task URL. Do not push the user to the next phase.
51
-
52
- ## 2B. Cloud workflow (`--cloud`)
53
-
54
- ### Run the server action
55
-
56
- - Call `mcp__xevy__start_ai_action({ taskId, action: "analyze", stream: true })`; always pass `stream: true`. The call blocks and streams live per-step progress, so report progress as it arrives. Do not use fire-and-forget or sleep/manual polling loops.
57
- - Only if the streamed call returns before a terminal status because of a genuine client disconnect, resume with `mcp__xevy__get_ai_execution` until `succeeded | failed | cancelled` (use `list_ai_executions` to find the newest run if needed).
58
- - If it fails, read the captured output, report the error, and offer to retry or rerun `/xevy:analyze` without `--cloud`.
59
-
60
- ### Review and correct
61
-
62
- Act as the reviewer of the cloud result:
63
-
64
- - Re-read the task, specs, subtasks, and the Analysis section the agent wrote.
65
- - Confirm it covers the plain-language overview, before/after behaviour, user impact, affected files, API/data/UI changes, assumptions, risks, verification, and a `storyPoints` estimate. Inspect referenced code with Read/Grep rather than trusting the write-up.
66
- - Repair missing, inaccurate, or contradictory material with `mcp__xevy__update_task`; append or repair the Analysis and never delete the user's original request. Set `storyPoints` if absent.
67
-
68
- Report a PASS/PARTIAL verdict, what you corrected, and the task URL. Do not push the user to the next phase.