@xevy/skills 0.1.41 → 0.1.45

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.39",
5
+ "version": "0.1.45",
6
6
  "author": {
7
7
  "name": "Xevy"
8
8
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/skills",
3
- "version": "0.1.41",
3
+ "version": "0.1.45",
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": [
@@ -32,6 +32,8 @@ Call `mcp__xevy__list_task_decisions`. If any decision is **open**, resolve it b
32
32
 
33
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
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
+
35
37
  ### Write the Analysis
36
38
 
37
39
  Use `mcp__xevy__update_task` to append a `## Analysis` section without replacing the user's original request:
@@ -5,15 +5,15 @@ description: Operate connected Windows or macOS applications through Xevy Comput
5
5
 
6
6
  # Computer
7
7
 
8
- Use the connected desktop for the user's application task. Resolve the target Computer, app, environment, and intended result from the request and current context. Read the actual available tool schemas; MCP and public tools expose owner management while the autonomous server tools expose a task-scoped subset.
8
+ Use the connected desktop for the user's application task. Resolve the target Computer, app, environment, and intended result from the request and current context. Read the actual available tool schemas; MCP and public tools expose owner management while the autonomous server tools expose a task-scoped subset. When supported by the companion, shell and file actions run on that Computer through the same audited MCP session.
9
9
 
10
10
  ## Establish control
11
11
 
12
12
  Use `computer_list` and `computer_get` to find the requested device. Pairing uses `computer_pair` and Xevy Connect. Windows controls the signed-in user's desktop. macOS 14+ requires native Screen Recording and Accessibility consent; report missing consent as a blocker.
13
13
 
14
- Start an exclusive `agent` session with `computer_start`, associating the current project/task when relevant. Capture the session ID and generation. A recently heartbeating paused device can accept a fresh controller; input waits for the companion to resume. Explicit local pause requires the user to resume Xevy Connect. Offline, revoked, expired, or unavailable devices require recovery before input. Report the observed state and fixed `pauseReason` when available.
14
+ Start an `agent` session with `computer_start`, associating the current project/task when relevant. Agent sessions can coexist on one Computer; each keeps its own session ID and shares the device generation until a human takes over or the device pauses. Capture your session ID and generation. A recently heartbeating paused device can accept a fresh controller; input waits for the companion to resume. Explicit local pause requires the user to resume Xevy Connect. Offline, revoked, expired, or unavailable devices require recovery before input. Report the observed state and fixed `pauseReason` when available.
15
15
 
16
- Inspect an existing controller before changing it. Human take-over advances the generation and owns control. Continue only when control is explicitly returned; refresh session metadata before further input. Send the captured generation with pause/resume/stop, including cleanup, so an old agent cannot stop a new controller. Stop only the session this run owns. For owned cleanup, call `computer_control({computerId, sessionId, generation, transition: 'stop'})` with the captured generation. On the public surface, start with `computer_start({computerId, mode: 'agent', projectId, taskId})` using relevant context; the internal server surface takes only `computerId` and inherits its task, so follow the active tool schema.
16
+ Inspect existing sessions before changing control. Human take-over advances the generation and stops agent sessions. Continue only when control is explicitly returned; refresh session metadata before further input. Send the captured generation with pause/resume/stop, including cleanup, so an old agent cannot stop a new controller. Stop only the session this run owns; stopping one agent session leaves other agents connected. For owned cleanup, call `computer_control({computerId, sessionId, generation, transition: 'stop'})` with the captured generation. On the public surface, start with `computer_start({computerId, mode: 'agent', projectId, taskId})` using relevant context; the internal server surface takes only `computerId` and inherits its task, so follow the active tool schema.
17
17
 
18
18
  ## Browser control
19
19
 
@@ -21,16 +21,20 @@ For browser work, use tab-scoped browser actions when the companion advertises t
21
21
 
22
22
  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.
23
23
 
24
- Use `browser.tabs` to select the actual tab, then `browser.navigate`, `browser.snapshot`, `browser.click`, `browser.type`, and `browser.key` as needed. Read every command result. 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. Do not call `desktop.snapshot` as a substitute when a tab-scoped capture is available or a full-monitor capture is blocked. `browser.disconnect` releases the companion's browser connection; it closes a browser only when the companion owns that launch. Follow the tool's current schema and capability list, since older companion versions may offer desktop actions only.
24
+ 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.
25
25
 
26
26
  ## Observe, act, verify
27
27
 
28
+ For shell work, queue `shell.run {executable,args?,cwd?,timeoutMs?}`. Pass an executable and an argument array; each invocation has a 30-second timeout and bounded stdout/stderr. Read the terminal command result and verify the effect of any write before repeating it. Shell commands may change many files or external records, so keep one focused invocation per operation and describe the intended effect in the operation completion. Block rules can target `shell.run`, executable names, and the working directory. A file-path rule governs structured `file.*` actions; block `shell.run` when shell access to that path must also be prevented. Command arguments and output stay out of durable audit summaries.
29
+
30
+ For file transfer, use absolute paths and chunks of at most 192 KiB. Download with `file.stat {path}` followed by `file.readChunk {path,offset,length}` until `eof`; verify each chunk's SHA-256 and the assembled file locally. Upload by calculating the full file's SHA-256, then call `file.uploadStart {path,size,sha256,replace?}`, send ordered `file.uploadChunk {transferId,offset,dataBase64}` actions, and finish with `file.uploadCommit {transferId}`. Use `file.uploadCancel` if abandoning a transfer. The companion stages at most 100 MiB across transfers and removes stale uploads after one hour. Transfer IDs belong to the creating agent session. Path block rules apply to reads and uploads, including chunk and commit steps. Treat the transferred bytes and shell output as ephemeral results; keep them out of operation summaries.
31
+
28
32
  1. Request `desktop.monitors` and `desktop.windows` through `computer_action`, then read their `computer_command` results. Select the actual target window and monitor.
29
33
  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.
30
34
  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.
31
35
  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.
32
36
  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.
33
- 6. After all operation commands finish and a final desktop or browser-tab screenshot is observed, call `computer_complete_operation` using the same `operationId`, current generation, and `completed`, `submitted`, `deleted`, or `failed`. Summarize the app result actually verified. Stop owned control when finished.
37
+ 6. After the final screenshot, queue `desktop.release {}` when you used native desktop input and wait for its terminal result. This releases the desktop focus lease so another agent can act. Browser tabs remain independent during the lease. Then call `computer_complete_operation` using the same `operationId`, current generation, and `completed`, `submitted`, `deleted`, or `failed`. Summarize the app result actually verified. Stop owned control when finished.
34
38
 
35
39
  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.
36
40
 
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: execute
3
- description: Execute a task locally in the current coding-agent session by default — use the task worktree, implement the plan, verify, push, and open a PR. Pass --cloud to delegate implementation to the Xevy server agent, then review and correct its result.
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__list_subtasks mcp__xevy__update_subtask 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__list_specs 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"
7
7
  ---
8
8
 
9
9
  # /xevy:execute — execute locally or in the cloud
@@ -23,6 +23,12 @@ Local implementation is the default. Pass the exact standalone `--cloud` flag to
23
23
  - Resolve the remaining task argument or the in-context task. Read its `## Analysis`, plan spec, and subtasks. If planning artifacts are absent and the task is non-trivial, suggest `/xevy:plan` or ask whether to plan-and-execute or execute directly.
24
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`; otherwise stop and ask the user to analyze and estimate first.
25
25
 
26
+ ### Code-only checklist and resume fallback
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.
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; genuine open product 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
+
26
32
  ## 2A. Local workflow (default)
27
33
 
28
34
  ### Decisions gate
@@ -39,19 +45,23 @@ Call `mcp__xevy__list_task_decisions` before implementing. If any decision is **
39
45
  ### Implement
40
46
 
41
47
  - 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.
42
- - Work through subtasks in order. 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.
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.
43
49
  - Before editing UI pages, components, app shell, forms, or styling, follow `/xevy:xevy-design` and the project's `./.xevy/design.md`.
44
50
  - If a genuine human decision appears mid-implementation, record it with `mcp__xevy__create_decision` using preset choices rather than guessing. If the user is present, persist their answer with `create_decision` + `answer_decision`.
45
- - Validate after each step: type-check, lint, then targeted tests.
51
+ - 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.
46
52
 
47
- ### Review, push, and hand off
53
+ ### Publish implementation
48
54
 
49
- - Run the full project checks. Trace every requirement to code and verify every “must NOT” constraint. When supported, dispatch a **reviewer** for an independent PASS/PARTIAL/FAIL with file:line evidence; otherwise do a separate review pass. Fix all findings and re-run checks until green.
50
- - After final checks and review corrections, run [generate-guide](../generate-guide/SKILL.md) for a UI/user journey when an authorized test environment is available. Test affected and downstream journeys, fix authorized issues, and recapture screenshots on the final build. Keep technical verification separate from user steps. Later fixes invalidate affected proof/captures and require refreshed verification before handoff. Stay in the active engine; report missing capture/publication tools or access as a handoff. This hook grants no deploy, merge, or additional mutation authority.
51
55
  - Commit and push the task branch. Open or refresh the PR and always give the user its PR or compare link. Do not merge automatically.
52
56
  - Record the branch on the task in `aiPullRequest.branch`, then move the task to `for_review` with `update_task_status`.
53
57
  - Do not deploy Preview automatically. Preview is an explicit user action via `/xevy:deploy preview`.
54
58
 
59
+ ### Separate verification, QA, and review
60
+
61
+ After publishing implementation, perform or hand off the separate post-execution checks. Trace requirements to code and inspect “must NOT” constraints. Run available project checks, or use a reviewer when supported. Report PASS/PARTIAL/FAIL with evidence, including failed or unavailable checks; retain actual approval gates. Commit and push any resulting authorized code corrections and refresh the PR. Check availability once and hand off missing dependencies or access with the exact limitation; do not turn these checks into implementation subtasks or delay publishing committed code for procedural sign-off.
62
+
63
+ For an authorized UI/user journey, run [generate-guide](../generate-guide/SKILL.md) during this separate verification workflow. Test affected and downstream journeys, fix authorized issues, and recapture affected proof after later corrections. Keep technical verification separate from user steps. Stay in the selected engine and report missing capture/publication tools or access as a handoff. This hook grants no deploy, merge, or additional mutation authority.
64
+
55
65
  ## 2B. Cloud workflow (`--cloud`)
56
66
 
57
67
  ### Run the server action
@@ -63,10 +73,11 @@ Call `mcp__xevy__list_task_decisions` before implementing. If any decision is **
63
73
 
64
74
  ### Review and correct
65
75
 
76
+ - This is the separate post-execution verification/review workflow; the server action has already implemented and published code. Apply the actual-work fallback to legacy checklist items and keep workflow checks in separate notes.
66
77
  - Fetch origin and inspect the task's feature branch using the pull-request metadata from `find_task`. Trace every requirement in the task and plan to the full diff.
67
78
  - Run the project's type-check, lint, and tests. Fix anything broken, incomplete, or contrary to a “must NOT” constraint; commit and push corrections to the feature branch, never a protected branch. When useful, dispatch a **reviewer** for an independent pass.
68
79
  - Before correcting UI code, follow `/xevy:xevy-design` and the project's `./.xevy/design.md`.
69
- - Re-run checks until green and refresh the PR. Report PASS/PARTIAL/FAIL with file:line evidence and corrections made.
80
+ - Check available verification for corrections and refresh the PR. Report PASS/PARTIAL/FAIL with file:line evidence, corrections made, and any failed or unavailable checks. Hand off missing dependencies or access without treating procedural checks as implementation blockers.
70
81
  - After final corrections and green checks, run [generate-guide](../generate-guide/SKILL.md) for an available authorized UI test journey within this active review session. Reverify and recapture the final build after any later correction. Preserve the selected engine and existing authorization; report capture/publication handoff when the tool subset cannot complete it.
71
82
  - Do not deploy Preview automatically. Preview is an explicit user action via `/xevy:deploy preview`.
72
83
 
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: fix
3
- description: Apply a task fix locally in the current coding-agent session by default — reuse its worktree, rework, verify, push, and refresh the PR. Pass --cloud to delegate the fix to the Xevy server agent, then review and correct its result.
3
+ description: Apply code fixes locally by default — reuse the task worktree, rework, push, and refresh the PR for separate verification and review. Pass --cloud to delegate the fix 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__list_subtasks mcp__xevy__update_subtask mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
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__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__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
7
  ---
8
8
 
9
9
  # /xevy:fix — fix locally or in the cloud
@@ -22,6 +22,10 @@ Local rework is the default. Pass the exact standalone `--cloud` flag to delegat
22
22
 
23
23
  Resolve the remaining task argument or the in-context task. It should already have a feature branch from a previous execute.
24
24
 
25
+ Read existing subtasks and any resume note before rework. Classify actual work, not keywords or stage alone. Mark legacy pure investigation, validation, verification, QA, review, or procedural spec-lock items `skipped` with a reason. Implement the code portion of mixed items and defer workflow checks to separate **QA Notes** and **Technical Review Instructions**. A stale workflow-only resume target selects the next pending code subtask. Input-validation implementation and adding/editing test files remain code work.
26
+
27
+ Check task decisions before implementing; preserve genuine open product decisions, required authorization, and conflicting technical contracts. Resolve actual open decisions through the host's user-question mechanism and record authorized answers with `answer_decision`; procedural checklist requirements alone do not block Fix. If no code change is required, report that truthfully without empty commits or fabricated implementation success.
28
+
25
29
  ## 2A. Local workflow (default)
26
30
 
27
31
  ### Locate the worktree
@@ -30,18 +34,22 @@ Find the existing task worktree and branch with `git worktree list`, matching by
30
34
 
31
35
  ### Rework
32
36
 
33
- Make the requested 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. Update subtasks through MCP.
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.
34
38
 
35
39
  Before editing UI pages, components, app shell, forms, or styling, follow `/xevy:xevy-design` and the project's `./.xevy/design.md`.
36
40
 
37
- ### Review, push, and hand off
41
+ ### Publish implementation
38
42
 
39
- - Run the full project checks. Verify the issue is fixed without regressions and check every “must NOT” constraint. When supported, dispatch a **reviewer** for an independent PASS/PARTIAL/FAIL with file:line evidence; otherwise perform a separate review pass. Fix every finding and re-run until green.
40
- - After final checks and review corrections, run [generate-guide](../generate-guide/SKILL.md) for a UI/user journey when an authorized test environment is available. Test affected and downstream journeys, fix authorized issues, and recapture screenshots on the final build. Keep technical verification separate from user steps. Later fixes invalidate affected proof/captures and require refreshed verification before handoff. Stay in the active engine; report missing capture/publication tools or access as a handoff. This hook grants no deploy, merge, or additional mutation authority.
41
43
  - Commit and push the feature branch, refresh the PR, and give the user its link. Do not merge automatically.
42
44
  - Do not redeploy Preview automatically. Preview is an explicit user action via `/xevy:deploy preview`.
43
45
  - Ask whether to merge with `/xevy:merge`; do not merge on your own.
44
46
 
47
+ ### Separate verification, QA, and review
48
+
49
+ After publishing the code fix, perform or hand off verification of the reported issue, regression checks, and review. Run available checks and inspect “must NOT” constraints; use an independent reviewer when supported. Report PASS/PARTIAL/FAIL with evidence and failed or unavailable checks. Commit/push any authorized code corrections and refresh the PR. Check missing dependencies or access once, record the exact limitation, and hand off remaining checks outside implementation subtasks; preserve actual merge and release approval gates.
50
+
51
+ For an authorized UI/user journey, run [generate-guide](../generate-guide/SKILL.md) in this separate verification workflow. Test affected and downstream journeys, fix authorized issues, and recapture affected proof after later corrections. Keep technical verification separate from user steps. Stay in the selected engine and report missing capture/publication tools or access as a handoff. This hook grants no deploy, merge, or additional mutation authority.
52
+
45
53
  ## 2B. Cloud workflow (`--cloud`)
46
54
 
47
55
  ### Run the server action
@@ -52,10 +60,11 @@ Before editing UI pages, components, app shell, forms, or styling, follow `/xevy
52
60
 
53
61
  ### Review and correct
54
62
 
63
+ - This is the separate post-execution verification/review workflow after the server's code fix. Classify legacy checklist work as above and retain deferred checks in separate handoff notes.
55
64
  - Fetch origin and diff the task's feature branch. Verify the fix resolves the reported issue and introduces no regression; trace it to the failing requirement or QA finding.
56
65
  - Run type-check, lint, and tests. If the result remains broken or incomplete, fix it and commit/push to the feature branch, never a protected branch. When useful, dispatch a **reviewer** for an independent pass.
57
66
  - Before correcting UI code, follow `/xevy:xevy-design` and the project's `./.xevy/design.md`.
58
- - Re-run until green and report PASS/PARTIAL/FAIL with evidence and corrections made.
67
+ - Check available verification for corrections and report PASS/PARTIAL/FAIL with evidence, corrections made, and failed or unavailable checks. Hand off missing dependencies or access; procedural checks remain outside implementation subtasks.
59
68
  - After final corrections and green checks, run [generate-guide](../generate-guide/SKILL.md) for an available authorized UI test journey within this active review session. Reverify and recapture the final build after any later correction. Preserve the selected engine and existing authorization; report capture/publication handoff when the tool subset cannot complete it.
60
69
  - Do not redeploy Preview automatically. Preview is an explicit user action via `/xevy:deploy preview`.
61
70
 
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: plan
3
- description: Plan a task locally in the current coding-agent session by default — inspect the codebase, write the plan spec and ordered subtasks, then review them. Pass --cloud to delegate planning to the Xevy server agent, then review and correct its result.
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.
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_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_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"
7
7
  ---
8
8
 
9
9
  # /xevy:plan — plan locally or in the cloud
@@ -28,16 +28,18 @@ Resolve the remaining task argument or the in-context task. It should already ha
28
28
 
29
29
  Call `mcp__xevy__list_task_decisions`. If any decision is **open**, resolve it first: present it through the host's user-question mechanism, record the answer with `mcp__xevy__answer_decision`, and reflect it in the plan. Open decisions block AI work, so never guess or bypass them.
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.
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.
32
32
 
33
33
  ### Write the plan
34
34
 
35
- - Create a plan spec with `mcp__xevy__create_spec` using kind `plan`. Include step-by-step changes with file paths and line ranges plus a trace matrix: requirement → files → strategy → test.
36
- - Create ordered subtasks with `mcp__xevy__create_subtask`. Group work into reviewable end-to-end pieces; keep frontend and backend work for one capability together.
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.
37
39
 
38
40
  ### Plan-review
39
41
 
40
- When the host supports subagents, dispatch a **plan-reviewer** to cross-check every matrix item against requirements, find orphans and gaps, verify cross-flow risks and “must NOT” constraints, and confirm tests hit the exact branches. Otherwise perform a separate self-review pass. Fold the findings into the spec and subtasks.
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.
41
43
 
42
44
  If planning surfaces a genuine question a human must resolve, record it with `mcp__xevy__create_decision` using preset choices and explanations instead of guessing.
43
45
 
@@ -59,8 +61,8 @@ Report a PASS/PARTIAL verdict, the matrix summary, open decisions, resulting sta
59
61
 
60
62
  - Read the produced plan spec (`list_specs` → `get_spec`) and subtasks (`list_subtasks`).
61
63
  - 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.
62
- - Check cross-flow risks such as guards, context rehydration, effects, and async side effects. Every “must NOT” constraint needs explicit verification.
63
- - Fix gaps by editing the spec or adding/reordering subtasks through MCP. Re-review until the matrix has no orphans.
64
+ - 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.
65
+ - 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. Re-review until the matrix has no orphans.
64
66
  - Do not change task status or start execution yourself. The server applies Process Owner automation after a successful run.
65
67
 
66
68
  Report a PASS/PARTIAL verdict, gaps closed, resulting task status, and task URL.