@xevy/skills 0.1.65 → 0.1.66

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.
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "xevy",
3
3
  "displayName": "Xevy",
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.65",
4
+ "description": "Native Xevy SDLC and Features workflows through MCP: plan, implement, review, record QA evidence and publish verified screenshot guides.",
5
+ "version": "0.1.66",
6
6
  "author": {
7
7
  "name": "Xevy"
8
8
  },
package/README.md CHANGED
@@ -112,6 +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 [request]` | Clarify the goal, check code and environment data, and recommend a solution in plain language |
115
116
  | `plan [task] [--cloud]` | Reconnaissance, numbered technical steps, and linked visualization for approval |
116
117
  | `execute [task] [--cloud]` | Build, verify, and open a PR (local by default) |
117
118
  | `fix [task] [--cloud]` | Rework after review (local by default) |
@@ -171,3 +172,17 @@ Version manifest for clients: `GET /api/agent-packages` on your Xevy host.
171
172
  - One-command setup: `npx @xevy/cli setup` (`@xevy/cli`)
172
173
  - MCP docs: https://xevy.ai/docs/mcp
173
174
  - Coding-agent MCP setup guide: https://xevy.ai/docs/mcp
175
+
176
+ ## Features workflows
177
+
178
+ - `/create-feature` builds a requested capability, or registers an existing unrecorded one, then records journeys, QA results and a screenshot guide.
179
+ - `/review-feature` tests an existing capability, registering it first when needed, and records its independent path results, findings and normal-flow guide.
180
+
181
+ These workflows use Features MCP/API records. Test execution remains agent-led; the first version has no scan scheduler.
182
+
183
+ ```text
184
+ /create-feature task-management --workspace acme --project shop
185
+ /review-feature task-management --workspace acme --project shop
186
+ ```
187
+
188
+ Explicit target flags select the project. The skill verifies that the inspected repository and test environment belong to that target before writing.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xevy/skills",
3
- "version": "0.1.65",
3
+ "version": "0.1.66",
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": [
@@ -0,0 +1,91 @@
1
+ ---
2
+ name: analyze
3
+ description: >-
4
+ Analyze a user request before implementation. Clarify the intended outcome,
5
+ check reported issues, relevant code, and production or staging data through
6
+ read-only connectors, then recommend a solution with severity, priority,
7
+ workarounds, and a durable fix. Produce a complete task brief ready for a
8
+ developer to begin work. Use when a user wants to understand a problem,
9
+ decide on a solution, or prepare a task for developer handoff.
10
+ ---
11
+
12
+ # /analyze
13
+
14
+ Analyze the request thoroughly, explain the result briefly, and prepare enough detail for a developer to begin work. Establish the problem, agree on the intended outcome, and carry the findings into the handoff. Own the technical investigation and speak to the user naturally in everyday language.
15
+
16
+ ## Understand the goal
17
+
18
+ - Identify who is affected, what they are trying to accomplish, current behavior, expected behavior, and the intended benefit. Use existing conversation and project context first.
19
+ - Treat the proposed change as a candidate solution. Check whether it achieves the goal and what consequences matter. Recommend it when it fits. Explain a better approach when the evidence supports one, preserving the user's scope and explicit preferences.
20
+ - Distinguish a defect from a new preference or enhancement. Scale investigation to the uncertainty and impact of the request.
21
+
22
+ ## Gather evidence
23
+
24
+ Read the original issue and relevant related reports when available. Trace the relevant code from its normal entry point through validation, permissions, settings, and data access as needed. Check actual behavior where possible. Distinguish the checked-out code from the version deployed in the environment being investigated.
25
+
26
+ When records, configuration, or affected counts matter, use the project's connectors first.
27
+
28
+ 1. Resolve the project and reported environment. Discover available connectors with `connector_list`. Confirm their environment from available metadata. If the mapping is ambiguous, ask before querying. Production checks can proceed through an authorized read-only connector for the reported production issue.
29
+ 2. For SQL, inspect structure with `connector_sql_schema`, then use `connector_query` for narrowly scoped read-only queries. For a service, discover the operation with `connector_search`, check parameters, read semantics, and cost with `connector_describe`, then call a read operation through `connector_execute`.
30
+ 3. Use bounded queries and small samples. Report sanitized counts and relevant facts. Keep credentials and personal records out of the response. State sample size, time range, and truncation when they affect the conclusion. Sample results support claims about that sample.
31
+ 4. Connect the observed records to the code path that handles them. Consider whether data, configuration, code, or expected behavior explains the issue. A code hypothesis needs runtime evidence before being described as a confirmed cause.
32
+
33
+ If access is unavailable, continue independent checks and state what remains unverified and what access would resolve it. Ask for the smallest missing detail. Never silently substitute staging results for production evidence. Use an already authorized read-only fallback only when a suitable connector is unavailable. The sibling [investigate skill](../investigate/SKILL.md) supplies additional diagnostic patterns when needed, subject to this skill's read-only scope.
34
+
35
+ ## Ask questions that affect the decision
36
+
37
+ - Investigate technical facts yourself. Ask the user about intent, affected people, business consequences, deadlines, and choices that change the outcome.
38
+ - Gather evidence through available code, connectors, logs, and direct read-only inspection first. Ask for a page name, URL, steps, or a short description when context is missing. Request a screenshot or recording only when a specific visual detail is essential to the decision and available checks or a text description cannot resolve it. Explain briefly what it would clarify and request only the relevant view. Continue independent analysis while waiting. Use images the user volunteers when relevant.
39
+ - Ask one focused question at a time where possible. Offer a few concrete choices with a recommendation when helpful, while allowing a different answer.
40
+ - Prefer an available `ask_question` tool or equivalent structured question tool for clarification and decisions, especially when the user can choose between concrete options. Use tools only in the modes and for the purposes they support. Ask in normal chat when that is clearer, more natural, or better suited to the answer, or when a suitable tool is unavailable. Keep either form short and easy to answer, and avoid repeating a question across both channels.
41
+ - Describe what someone will see or do. Use familiar terms and explain necessary technical terms briefly.
42
+ - Resolve material ambiguity before presenting a final request for approval. Continue useful independent checks while an answer is pending. Label assumptions and unresolved decisions explicitly.
43
+ - Choose routine implementation details from existing project patterns. Ask about size, position, or behavior when the answer meaningfully changes the experience.
44
+
45
+ For example, for "show the footer everywhere," inspect current page coverage and footer behavior, then ask if still unclear, "When someone is halfway down a page, should they already see the footer, or is it enough that they can reach it by scrolling to the bottom?" Clarify which pages matter if "everywhere" remains ambiguous. Reuse established sizing when it meets the goal.
46
+
47
+ ## Assess the options
48
+
49
+ Explain whether the original proposal achieves the goal. Compare alternatives only when they affect the user's decision. Consider effort, disruption, limitations, and the chance of the problem returning. Include dependencies or risks when they affect the recommendation.
50
+
51
+ - **Severity** describes current harm. Use critical, high, medium, low, enhancement, or unknown, with a short reason tied to observed impact. Reserve critical for urgent severe harm such as widespread loss of a core service or active data exposure.
52
+ - **Priority** describes when to act. Recommend now, next, later, or unknown, with a reason based on impact, reach, deadlines, dependencies, and available alternatives. Label it a recommendation and respect the project's established scale when one exists.
53
+ - **Workaround** describes something the user can do today. **Quick fix** describes a small implementation change. Explain limitations and side effects when either is useful. Say when none is established.
54
+ - **Durable fix** addresses the cause or lasting need. The smallest change may already be durable. Avoid inventing a larger rebuild to fill this field.
55
+
56
+ Use confirmed, likely, or unknown for important findings. Separate observed symptoms, suspected causes, and missing evidence. Severity and priority may remain unknown while impact is being checked.
57
+
58
+ ## Explain the result briefly
59
+
60
+ End with a few short, conversational sentences. State what you confirmed, the practical workaround when available, and the recommended next step. Use language a nontechnical person can act on. Describe uncertainty honestly when the issue is still unconfirmed.
61
+
62
+ Keep severity labels, priority ratings, code references, detailed evidence, implementation notes, and acceptance criteria in the developer handoff. Surface a detail in the conversation when it affects the user's decision, such as urgency, an important risk, a limitation of the workaround, or an unresolved choice. Provide further detail when the user asks.
63
+
64
+ Choose the closing question or action from the recommended next step within analysis and developer handoff. Ask about creating a ticket when a ticket is the useful next action and creation needs approval, or ask the specific missing question when more information is needed. Describe workarounds and fixes as work for the developer. Do not offer to implement a fix, change records, or apply a workaround yourself. When ticket creation is already authorized, create it and report the result briefly. Avoid a fixed closing question or asking again for approval already given.
65
+
66
+ For example, when supported by the findings, "I confirmed the issue. A developer can update the affected record so the user can continue. Adding a Delete button to Users would let your team handle this themselves. Would you like me to create a ticket for that?" This example describes a possible next step. Database changes require their own applicable authorization.
67
+
68
+ ## Prepare the developer handoff
69
+
70
+ Prepare a self-contained brief once the decisions that affect scope and behavior are resolved. Put the complete brief into the ticket when creation is authorized. A developer receiving only the ticket should have enough context to begin work. Keep the brief out of the conversational summary unless the user asks to review it. Scale detail to the task and combine fields where that improves readability.
71
+
72
+ - Task title stating the outcome to deliver.
73
+ - Problem, goal, affected users, and current versus expected behavior. Include reproduction steps for a defect when established.
74
+ - Environment and evidence checked, with relevant issue references, sanitized findings, important limits, and uncertainty.
75
+ - Severity and recommended priority, each with a plain-language reason.
76
+ - Workaround or quick fix, when available, and its limits.
77
+ - Selected solution, scope, affected pages or workflows, and relevant trade-offs. State whether the task delivers the quick fix, durable fix, or both. Keep deferred work explicit when it affects delivery.
78
+ - Technical findings needed to begin, including relevant code locations, existing patterns to reuse, data or configuration dependencies, and the confirmed or suspected cause. Keep implementation suggestions distinct from required outcomes.
79
+ - Testable acceptance criteria describing observable results. Cover relevant validation, permissions, failure recovery, and compatibility where the investigation shows they matter.
80
+ - Verification steps and the environment or access needed to run them. Distinguish checks already completed during analysis from checks the developer must perform after implementation.
81
+ - Dependencies, blockers, and remaining assumptions that affect delivery.
82
+
83
+ Before calling the brief ready for development, check that the intended behavior, scope, and acceptance criteria are clear, consequential user decisions are answered, and the developer has the evidence and prerequisites needed to start. Resolve gaps through available inspection and focused questions. Carry routine technical choices into the developer's work. A cause may remain a hypothesis if the task gives the developer a concrete way to confirm it and proceed.
84
+
85
+ If a material decision or access prerequisite still blocks work, label the brief provisional and name exactly what is needed. Where diagnosis itself is the necessary next task, define its investigation scope, required access, expected findings, and completion criteria. Recommend creating a task only when the analysis establishes useful work to do.
86
+
87
+ Include technical detail where it helps the developer implement or verify the task. Never invent affected counts, reproduction results, access, or a confirmed cause. When evidence is insufficient, explain briefly what the next check would resolve.
88
+
89
+ ## Scope
90
+
91
+ Investigation uses read-only inspection. When the user authorizes task creation, use the project's task-creation workflow and include the complete brief so the assigned developer can work without the conversation history. Respect the project's readiness and approval rules. Keep implementation, data changes, deployments, and other persistent work records behind their applicable user authorization. Never approve a service mutation during investigation. Finish with a brief conversational result and the question or completed action appropriate to the recommended next step. After creating a ticket, give its link and a short description.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: create-feature
3
+ description: Build a requested capability and record it in the Features app with journeys, tested cases, QA evidence and a screenshot guide. Also register and review an existing capability that is missing from Features.
4
+ ---
5
+
6
+ # Create and verify a feature
7
+
8
+ Deliver the requested capability, its Features record, separate journey test cases and an evidence-backed user guide. Use the current coding engine and repository workflow. This skill grants no additional merge, deployment, production mutation or release approval.
9
+
10
+ Usage: `/create-feature [capability] --workspace WORKSPACE --project PROJECT`.
11
+
12
+ ## Resolve the work
13
+
14
+ Parse `--workspace WORKSPACE` and `--project PROJECT` as explicit target slugs; use both flags together. They select the requested project ahead of linked-repository defaults. Read `.xevy/project.json` and validate the selected project, inspected repository and test environment agree before writing. When they differ, verify the repository/environment belongs to the explicit target; stop misdirected writes while that association is unresolved. Preserve the repository link and never silently substitute a project with a similar name or feature key. An empty command still needs the capability or feature to be identified.
15
+
16
+ Read `.xevy/project.json` when available and the project instructions. Discover the actual Features tools before writing: `list_features`, `get_feature`, `upsert_feature`, `upsert_feature_journey`, `upsert_feature_test_case`, `start_feature_review`, `record_feature_test_result`, `complete_feature_review`, `publish_feature_guide`, and `record_feature_finding`.
17
+
18
+ Search the feature list and inspect a matching record. Reuse its IDs and stable keys. A feature describes a capability; a journey describes one user goal; test cases describe that journey's normal, validation, alternative, permission and error paths. A guide teaches one normal journey.
19
+
20
+ Determine whether the request calls for new software or registration of existing behavior. For an existing unrecorded capability, inspect its implementation and user flow, then register it without rebuilding it. For new software, establish the requested behavior, follow the repository's implementation and approval rules, implement the capability, and perform the relevant code checks before the final review. Use the available execute/fix workflow when appropriate; preserve the active engine and authorized scope.
21
+
22
+ If required tools or access are unavailable, retain useful local work and identify the missing capability and exact next action. Do not fabricate feature IDs, successful calls, screenshots or recorded QA.
23
+
24
+ ## Register the capability and paths
25
+
26
+ Use `upsert_feature` with a stable project key, title, module, summary and documentation. Document behavior that the evidence supports. Preserve the user's intended outcomes when they differ from the current implementation.
27
+
28
+ Use `upsert_feature_journey` for each relevant user goal. Use `upsert_feature_test_case` for independently observable expected outcomes. Include normal use and the relevant validation, cancellation/alternative, role restrictions, service failure and recovery paths. Mark required coverage deliberately; optional checks need a concrete scope reason.
29
+
30
+ Keep a case's stable key when its wording changes. Update its steps and expected result before starting the final review; changing definitions invalidates current coverage. Avoid deriving both behavior and its correctness solely from the same implementation.
31
+
32
+ ## Execute and record QA
33
+
34
+ 1. Establish the exact environment URL, build/commit, browser, viewport, role and safe disposable fixtures. Obtain any access or external-write authorization required by that environment.
35
+ 2. Call `start_feature_review`. It snapshots definitions and records scope; it does not execute tests. Default to all required cases for the feature. A narrow rerun leaves cases outside its scope untested in current coverage.
36
+ 3. Execute each selected case in the actual application. Verify visible results and meaningful saved/downstream effects. Capture original screenshots using the available browser or [Computer tools](../computer/SKILL.md), then store them with the project-readable private evidence workflow below.
37
+ 4. Call `record_feature_test_result` with the case ID, actual observation and evidence. Use `passed` only for verified outcomes, `failed` for an observed mismatch, `blocked` with the missing prerequisite, and `skipped` for a deliberately unexecuted case with a reason. A successful click, code test or API acknowledgement alone does not establish a complete user journey.
38
+ 5. Complete the review with `complete_feature_review`. Preserve failures and incomplete coverage. After authorized fixes or later build changes, start a fresh review, rerun affected and downstream paths, and refresh its final-build captures. Keep earlier evidence as history.
39
+
40
+ Original captures support the exact step they show. Use safe fixtures to keep sensitive data out of the image. Generated illustrations, rewritten screenshots and old-build captures cannot establish tested behavior. Keep screen bytes outside tool text; use saved attachment/version references.
41
+
42
+ Stored screenshot and artifact evidence must belong to this project, have a ready immutable version and use project-level read scope (`sessionId: null`) so authorized project members can open it. Keep it private with `public: false`. A same-project attachment readable only in a personal session, or restricted by Computer grants, cannot be recorded as Features evidence or published in its guide; public visibility does not remove those restrictions.
43
+
44
+ For an authorized local original PNG, call `prepare_attachment_upload` with the target workspace/project, `fileName`, `mimeType: image/png`, `sizeBytes` and explicit `public: false`. Stream the local file bytes to the returned short-lived upload URL with its method and required headers, outside tool arguments, then call `complete_attachment_upload`. Retain the returned attachment UUID and immutable version. This direct-upload workflow creates project-level storage; verify its scope and readiness before recording it. A normal multipart upload can create session-private storage. Check a Computer capture's actual project read scope before reuse and preserve its grant restrictions.
45
+
46
+ Keep personal Drive and session-private files in their existing scope. Never change their visibility, relabel their ownership or reupload another user's files to make evidence pass. When authorized project-readable captures are unavailable, record verified behavior with admissible note/URL evidence and report the screenshot guide as blocked with the required capture/upload step. Guide publication requires every referenced image to pass the same project/read-scope checks and already belong to its normal result's evidence.
47
+
48
+ ## Record findings and publish the guide
49
+
50
+ After completing the review, record each runtime finding with `record_feature_finding`: stable key, failed `resultId`, feature/journey/case/review IDs, severity, expected/observed result, reproduction steps and evidence. Reuse its key on later occurrences. A source-only risk uses `origin: source` and navigable repository-relative source references; retain its unverified runtime state.
51
+
52
+ Publish the journey's normal-flow guide with `publish_feature_guide` when its normal case passed on the current definition and completed review. Each step includes an action, expected result and the exact screenshot attachment/version already present in that normal result's evidence. Keep alternative and unhappy paths in their separate test cases. A failed negative case can coexist with a valid normal-flow guide; the feature's QA status still reflects the failure. A failed or blocked normal case cannot support a newly verified guide.
53
+
54
+ If a separate HTML/PDF artifact is requested, use [generate-guide](../generate-guide/SKILL.md) and [create-artifact](../create-artifact/SKILL.md) with the same final-build evidence. The native Features guide remains the record for this workflow.
55
+
56
+ Record the QA outcome and remaining gaps. A bug task can be created through `create_task_from_feature_finding` when task creation is authorized; repeated calls return its existing task. Creating that task does not resolve the finding. Resolving a runtime bug requires a newer passed case result. Preserve human QA and release gates.
57
+
58
+ Return the feature and journey names, recorded review/build, guide availability, findings and blocked or untested paths. Use tool-returned links when available. Claim completion only for work and records that were verified.
@@ -0,0 +1,158 @@
1
+ {
2
+ "skill_name": "create-feature",
3
+ "mode": "isolated-dry-run",
4
+ "instruction": "Use the supplied fixture state to choose a concrete operation trace and resulting record graph. Do not call live services or change real repositories. Judge actual scope, IDs, order, evidence binding and outcomes, not preferred wording.",
5
+ "evals": [
6
+ {
7
+ "id": 1,
8
+ "prompt": "Use /create-feature to register our existing wishlist capability in workspace acme, project shop. It works already; add its QA and user guide.",
9
+ "fixture": {
10
+ "linkedProject": {
11
+ "workspace": "acme",
12
+ "project": "shop"
13
+ },
14
+ "capabilityExists": true,
15
+ "featureRecords": [],
16
+ "softwareEvidence": "Wishlist button adds item to saved wishlist and reopening shows it.",
17
+ "caseObservations": {
18
+ "normal": "passed",
19
+ "missing-product": "passed"
20
+ },
21
+ "screenshot": {
22
+ "attachmentId": "66666666-6666-4666-8666-666666666666",
23
+ "versionNumber": 2,
24
+ "project": "shop",
25
+ "sessionId": null,
26
+ "isPublic": false,
27
+ "status": "ready",
28
+ "readableBy": "authorized project members"
29
+ },
30
+ "toolsAvailable": "Features operations and browser capture"
31
+ },
32
+ "expected_output": "A reused stable wishlist identity is registered, journeys/cases are recorded, actual observations lead to a completed review and a normal guide using the same screenshot version. Existing software is preserved.",
33
+ "checks": [
34
+ "No implementation task or code rewrite for existing behavior.",
35
+ "Stable keys are searched before upsert.",
36
+ "Guide images are included in passed normal-result evidence.",
37
+ "Review completion occurs before runtime findings or guide publication."
38
+ ]
39
+ },
40
+ {
41
+ "id": 2,
42
+ "prompt": "Use /create-feature for a new required-title validator. Implement the approved change, test it and record the outcome.",
43
+ "fixture": {
44
+ "linkedProject": {
45
+ "workspace": "acme",
46
+ "project": "shop"
47
+ },
48
+ "implementationAuthorized": true,
49
+ "approvedExpectedBehavior": "Reject empty titles and preserve valid task creation.",
50
+ "capabilityExists": false,
51
+ "afterImplementationObservations": {
52
+ "normal": "failed",
53
+ "empty-title": "passed"
54
+ },
55
+ "normalFailure": "Saving a valid task returns a server error.",
56
+ "screenshot": {
57
+ "attachmentId": "66666666-6666-4666-8666-666666666666",
58
+ "versionNumber": 1,
59
+ "project": "shop",
60
+ "sessionId": null,
61
+ "isPublic": false,
62
+ "status": "ready",
63
+ "readableBy": "authorized project members"
64
+ }
65
+ },
66
+ "expected_output": "Implementation follows the repository workflow. The failed normal case produces a truthful review/finding and no verified normal guide. Any authorized correction requires a fresh final-build review.",
67
+ "checks": [
68
+ "New software is implemented before its final recorded review.",
69
+ "Normal failure remains failed.",
70
+ "No guide publication from a failed normal case.",
71
+ "No human QA or release status is fabricated."
72
+ ]
73
+ },
74
+ {
75
+ "id": 3,
76
+ "prompt": "/create-feature product-export --workspace acme --project warehouse",
77
+ "fixture": {
78
+ "linkedProject": {
79
+ "workspace": "acme",
80
+ "project": "shop"
81
+ },
82
+ "explicitTarget": {
83
+ "workspace": "acme",
84
+ "project": "warehouse"
85
+ },
86
+ "repositoryAssociation": "This checkout belongs only to shop. No verified warehouse source or test environment is available.",
87
+ "capabilityExists": false
88
+ },
89
+ "expected_output": "Stop misdirected implementation and persistent writes, identify the unresolved repository/environment association, and retain the explicit requested target.",
90
+ "checks": [
91
+ "Explicit flags remain the target.",
92
+ "No mutation in shop or warehouse until association is resolved.",
93
+ "Repository link is preserved."
94
+ ]
95
+ },
96
+ {
97
+ "id": 4,
98
+ "prompt": "Use /create-feature to record the verified normal flow and its screenshot guide for acme/shop. A same-project session capture and an authorized local original PNG are available. Keep the guide private and usable by project members.",
99
+ "fixture": {
100
+ "target": {
101
+ "workspace": "acme",
102
+ "project": "shop"
103
+ },
104
+ "normalBehaviorObserved": "Saving a valid task succeeds and reopening preserves its title.",
105
+ "sessionCapture": {
106
+ "attachmentId": "88888888-8888-4888-8888-888888888888",
107
+ "versionNumber": 1,
108
+ "project": "shop",
109
+ "sessionId": "99999999-9999-4999-8999-999999999999",
110
+ "isPublic": false,
111
+ "readableBy": "current session only"
112
+ },
113
+ "authorizedLocalOriginal": {
114
+ "path": "/tmp/normal-task.png",
115
+ "mimeType": "image/png",
116
+ "sizeBytes": 2048,
117
+ "owner": "current reviewer",
118
+ "build": "current reviewed build"
119
+ },
120
+ "uploadToolsAvailable": [
121
+ "prepare_attachment_upload",
122
+ "complete_attachment_upload"
123
+ ],
124
+ "directUploadResponse": {
125
+ "attachmentId": "66666666-6666-4666-8666-666666666666",
126
+ "versionNumber": 4,
127
+ "project": "shop",
128
+ "sessionId": null,
129
+ "isPublic": false,
130
+ "status": "ready",
131
+ "readableBy": "authorized project members"
132
+ },
133
+ "alternateNoLocalCapture": {
134
+ "authorizedLocalOriginal": null,
135
+ "authorizedProjectCapture": null
136
+ },
137
+ "restrictedComputerCapture": {
138
+ "attachmentId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
139
+ "versionNumber": 1,
140
+ "project": "shop",
141
+ "sessionId": null,
142
+ "isPublic": false,
143
+ "status": "ready",
144
+ "readableBy": "Computer grant holders only"
145
+ }
146
+ },
147
+ "expected_output": "Exclude the session-private capture from Features evidence. Prepare a scoped direct upload with public:false, stream the authorized local bytes outside tool arguments, complete the upload, and bind the ready project-level version to the normal result before guide publication. The resulting guide stays private and project-readable. Without an authorized project-level capture, preserve truthful behavior evidence and report the guide blocked.",
148
+ "checks": [
149
+ "Same project alone does not make session-private or Computer-restricted evidence admissible.",
150
+ "Explicit public:false is passed to prepare_attachment_upload; no public link or visibility promotion.",
151
+ "File bytes use the signed upload transport outside tool arguments, then complete_attachment_upload.",
152
+ "Only the project-level ready immutable version appears in the normal result and guide.",
153
+ "No personal Drive migration, ownership relabeling or reupload of another user's assets.",
154
+ "No-local-capture variant leaves guide blocked without falsifying the observed normal result."
155
+ ]
156
+ }
157
+ ]
158
+ }
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: review-feature
3
+ description: Test an existing capability and record its journeys, case results, findings and screenshot guides in the Features app. Register the capability first when it has no Features record.
4
+ ---
5
+
6
+ # Review a feature with evidence
7
+
8
+ Produce a review of the actual capability: independently tested paths, evidence, findings and a verified normal-flow user guide. Registration is part of this workflow when the existing feature is missing from Features. Implementation fixes, external mutations, merge and release actions follow the user's existing authorization.
9
+
10
+ Usage: `/review-feature [capability] --workspace WORKSPACE --project PROJECT`.
11
+
12
+ ## Find or register the feature
13
+
14
+ Parse `--workspace WORKSPACE` and `--project PROJECT` as explicit target slugs; use both flags together. They select the requested project ahead of linked-repository defaults. Read `.xevy/project.json` and validate the selected project, inspected repository and test environment agree before writing. When they differ, verify the repository/environment belongs to the explicit target; stop misdirected writes while that association is unresolved. Preserve the repository link and never silently substitute a project with a similar name or feature key. An empty command still needs the capability or feature to be identified.
15
+
16
+ Resolve access to the explicit project, or use `.xevy/project.json` and available project discovery when scope flags are absent. Read its instructions and verify access to the test environment and Features tools. Use `list_features`, then `get_feature` to inspect matching records, stable keys, journeys, cases and prior reviews.
17
+
18
+ If the capability already exists in software but lacks a record, inspect its source and visible behavior and call `upsert_feature`. Reuse the same project key on repeat. Add or update its journeys and test cases through `upsert_feature_journey` and `upsert_feature_test_case`. Registration supports the existing capability and does not authorize rebuilding it.
19
+
20
+ One feature can have several journeys. Each journey is a user goal with separate normal, validation, alternative, permission and error/recovery cases. Keep each expected result observable. Cover the relevant unhappy paths and role boundaries; make required versus optional scope explicit. Base correctness on approved requirements and business rules as well as implementation evidence.
21
+
22
+ Update definitions before a review starts. Stable keys preserve identity while edits advance revisions. Inspect any existing findings and guides so the review advances the same history and avoids duplicates.
23
+
24
+ ## Run the review
25
+
26
+ Record the exact build/commit, environment URL, browser, viewport, test role and disposable fixtures. Use an isolated preview/staging environment when appropriate; protect real records and obtain any authorization required for the proposed writes.
27
+
28
+ Call `start_feature_review` to snapshot the case definitions. This records scope; execution remains your job. Default to all required feature cases. A selected subset leaves omitted cases untested in current coverage; never combine successful results from different builds or environments into a claimed full pass.
29
+
30
+ Execute each case in the actual app. Confirm visible outcomes and meaningful persistence or downstream behavior, including relevant reopening and next-step flows. Record each outcome with `record_feature_test_result` and honest observations:
31
+
32
+ - `passed`: the stated expected result was verified.
33
+ - `failed`: observed behavior differs; include reproduction evidence.
34
+ - `blocked`: a specific prerequisite prevented execution; state it.
35
+ - `skipped`: the case was intentionally left unexecuted; state why.
36
+
37
+ Use the available browser observation tools or [Computer tools](../computer/SKILL.md). Store original screenshots with the project-readable private evidence workflow below and retain the immutable attachment/version reference. Include every screenshot needed for a normal guide in that normal case result's evidence. Verify role restrictions at the relevant boundary; a disabled UI action proves a UI restriction, while server authorization requires its own check.
38
+
39
+ Screenshots must come from the tested build and show their documented step. Generated/mock images, edited captures and passing unit tests do not substitute for actual journey evidence. Keep credentials and customer data out of captures through safe fixture selection. Keep image bytes outside tool arguments.
40
+
41
+ Stored screenshot and artifact evidence must belong to this project, have a ready immutable version and use project-level read scope (`sessionId: null`) so authorized project members can open it. Keep it private with `public: false`. A same-project attachment readable only in a personal session, or restricted by Computer grants, cannot be recorded as Features evidence or published in its guide; public visibility does not remove those restrictions.
42
+
43
+ For an authorized local original PNG, call `prepare_attachment_upload` with the target workspace/project, `fileName`, `mimeType: image/png`, `sizeBytes` and explicit `public: false`. Stream the local file bytes to the returned short-lived upload URL with its method and required headers, outside tool arguments, then call `complete_attachment_upload`. Retain the returned attachment UUID and immutable version. This direct-upload workflow creates project-level storage; verify its scope and readiness before recording it. A normal multipart upload can create session-private storage. Check a Computer capture's actual project read scope before reuse and preserve its grant restrictions.
44
+
45
+ Keep personal Drive and session-private files in their existing scope. Never change their visibility, relabel their ownership or reupload another user's files to make evidence pass. When authorized project-readable captures are unavailable, record verified behavior with admissible note/URL evidence and report the screenshot guide as blocked with the required capture/upload step. Guide publication requires every referenced image to pass the same project/read-scope checks and already belong to its normal result's evidence.
46
+
47
+ Complete the review with `complete_feature_review` after recording the available results. Missing, blocked or stale cases remain incomplete. Completion freezes history and grants no human QA or release approval.
48
+
49
+ ## Findings, fixes and guide
50
+
51
+ Use `record_feature_finding` after review completion to record runtime failures with their failed `resultId`, feature/journey/case/review IDs, stable finding key, severity, expected/observed behavior and reproduction evidence. Repeated occurrences reuse the same key. Source inspection findings use `origin: source` and repository-relative source references; their runtime impact remains unverified.
52
+
53
+ Perform a fix only when the current task authorizes it. After any code or definition change, run a fresh review against the resulting build and recapture affected and downstream evidence. Resolve a runtime finding through `update_feature_finding` only with a newer passed case result. Task completion alone does not establish resolution.
54
+
55
+ Publish a normal-flow guide with `publish_feature_guide` when its normal case passed on the current definition in a completed review. Include numbered user actions, expected results and original screenshot references already attached to that passed result. Other cases remain in the journey's test-case list. A negative-path failure preserves the normal guide's availability and the feature's failing QA status. A failed or blocked normal case leaves the guide awaiting verified execution.
56
+
57
+ Use `create_task_from_feature_finding` for a linked draft bug task when creating tasks is authorized. Repeat calls return the existing task and leave the finding's verification state intact. If a separate export is requested, use [generate-guide](../generate-guide/SKILL.md) and [create-artifact](../create-artifact/SKILL.md) with the same evidence.
58
+
59
+ ## Handoff
60
+
61
+ Return the tested feature, build/environment, case coverage, guide availability, recorded findings and remaining gaps. Use returned links and real IDs. Where tools, authentication, fixtures or capture access are missing, preserve useful local evidence and name the exact missing capability and next action. Report blocked or untested scope truthfully; never fabricate successful records or capture/publication links.
@@ -0,0 +1,175 @@
1
+ {
2
+ "skill_name": "review-feature",
3
+ "mode": "isolated-dry-run",
4
+ "instruction": "Use the supplied fixture state to choose a concrete operation trace and resulting record graph. Do not call live services or change real repositories. Judge actual scope, IDs, order, evidence binding and outcomes, not preferred wording.",
5
+ "evals": [
6
+ {
7
+ "id": 1,
8
+ "prompt": "Review task creation and publish a guide if its normal flow is usable.",
9
+ "fixture": {
10
+ "project": "delivery",
11
+ "existingFeature": {
12
+ "id": "11111111-1111-4111-8111-111111111111",
13
+ "key": "tasks"
14
+ },
15
+ "build": "commit-A",
16
+ "normal": {
17
+ "caseId": "44444444-4444-4444-8444-444444444444",
18
+ "status": "passed",
19
+ "screenshot": {
20
+ "attachmentId": "66666666-6666-4666-8666-666666666666",
21
+ "versionNumber": 3,
22
+ "sessionId": null,
23
+ "isPublic": false,
24
+ "status": "ready",
25
+ "readableBy": "authorized project members"
26
+ }
27
+ },
28
+ "emptyTitle": {
29
+ "status": "failed",
30
+ "observation": "An empty task was saved."
31
+ },
32
+ "serverPermission": {
33
+ "status": "blocked",
34
+ "reason": "Guest API fixture unavailable."
35
+ }
36
+ },
37
+ "expected_output": "The normal guide can be published from its passed result and exact screenshot version. The negative failure becomes a linked finding after review completion. Failed and blocked coverage remains visible.",
38
+ "checks": [
39
+ "Normal and unhappy paths are separate cases.",
40
+ "Feature QA remains failing despite guide availability.",
41
+ "Blocked server permission is not inferred from a disabled UI control.",
42
+ "Finding binds the failed result rather than the normal result."
43
+ ]
44
+ },
45
+ {
46
+ "id": 2,
47
+ "prompt": "Review the existing notifications feature; it is missing from Features.",
48
+ "fixture": {
49
+ "capabilityExists": true,
50
+ "registeredFeature": null,
51
+ "availableTools": [
52
+ "browser",
53
+ "read_repository"
54
+ ],
55
+ "unavailableTools": [
56
+ "list_features",
57
+ "upsert_feature",
58
+ "start_feature_review",
59
+ "record_feature_test_result",
60
+ "publish_feature_guide"
61
+ ]
62
+ },
63
+ "expected_output": "Useful local inspection can continue, but the response identifies missing recording tools and provides a precise registration/review handoff. It invents no stored feature, review or guide.",
64
+ "checks": [
65
+ "No reimplementation of the existing capability.",
66
+ "No fabricated IDs or successful tool receipts.",
67
+ "Missing recording capability is explicit."
68
+ ]
69
+ },
70
+ {
71
+ "id": 3,
72
+ "prompt": "Review this feature and use the supplied screenshot in its normal guide.",
73
+ "fixture": {
74
+ "currentProject": "shop",
75
+ "normalBehaviorObserved": "Task saves and reopens correctly.",
76
+ "suppliedScreenshot": {
77
+ "attachmentId": "66666666-6666-4666-8666-666666666666",
78
+ "versionNumber": 1,
79
+ "project": "other-project"
80
+ },
81
+ "authorizedCaptureAvailable": false
82
+ },
83
+ "expected_output": "The foreign screenshot is excluded. Actual behavior can be recorded with permitted evidence, while guide publication remains unavailable until an authorized original capture exists.",
84
+ "checks": [
85
+ "Project/version guard remains intact.",
86
+ "No retry that drops scope or changes image ownership.",
87
+ "No guide is published with foreign or invented screenshot evidence."
88
+ ]
89
+ },
90
+ {
91
+ "id": 4,
92
+ "prompt": "Review the task-creation bug and create a task for it if needed.",
93
+ "fixture": {
94
+ "featureKey": "tasks",
95
+ "existingFindingKey": "create/empty-title",
96
+ "findingTask": {
97
+ "taskId": "77777777-7777-4777-8777-777777777777",
98
+ "url": "https://example.test/task/77777777-7777-4777-8777-777777777777"
99
+ },
100
+ "runtimeObserved": "Same empty-title failure persists.",
101
+ "taskCreationAuthorized": true,
102
+ "createTaskFromFindingResponse": {
103
+ "alreadyExisted": true
104
+ }
105
+ },
106
+ "expected_output": "Reuse feature/case/finding identities and the linked task. A repeated task operation returns the existing task and leaves the finding unresolved.",
107
+ "checks": [
108
+ "No generic duplicate create_task.",
109
+ "No finding resolution from task existence or task completion.",
110
+ "Existing task URL is returned."
111
+ ]
112
+ },
113
+ {
114
+ "id": 5,
115
+ "prompt": "Use /review-feature to record the verified normal flow and its screenshot guide for acme/shop. A same-project session capture and an authorized local original PNG are available. Keep the guide private and usable by project members.",
116
+ "fixture": {
117
+ "target": {
118
+ "workspace": "acme",
119
+ "project": "shop"
120
+ },
121
+ "normalBehaviorObserved": "Saving a valid task succeeds and reopening preserves its title.",
122
+ "sessionCapture": {
123
+ "attachmentId": "88888888-8888-4888-8888-888888888888",
124
+ "versionNumber": 1,
125
+ "project": "shop",
126
+ "sessionId": "99999999-9999-4999-8999-999999999999",
127
+ "isPublic": false,
128
+ "readableBy": "current session only"
129
+ },
130
+ "authorizedLocalOriginal": {
131
+ "path": "/tmp/normal-task.png",
132
+ "mimeType": "image/png",
133
+ "sizeBytes": 2048,
134
+ "owner": "current reviewer",
135
+ "build": "current reviewed build"
136
+ },
137
+ "uploadToolsAvailable": [
138
+ "prepare_attachment_upload",
139
+ "complete_attachment_upload"
140
+ ],
141
+ "directUploadResponse": {
142
+ "attachmentId": "66666666-6666-4666-8666-666666666666",
143
+ "versionNumber": 4,
144
+ "project": "shop",
145
+ "sessionId": null,
146
+ "isPublic": false,
147
+ "status": "ready",
148
+ "readableBy": "authorized project members"
149
+ },
150
+ "alternateNoLocalCapture": {
151
+ "authorizedLocalOriginal": null,
152
+ "authorizedProjectCapture": null
153
+ },
154
+ "restrictedComputerCapture": {
155
+ "attachmentId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
156
+ "versionNumber": 1,
157
+ "project": "shop",
158
+ "sessionId": null,
159
+ "isPublic": false,
160
+ "status": "ready",
161
+ "readableBy": "Computer grant holders only"
162
+ }
163
+ },
164
+ "expected_output": "Exclude the session-private capture from Features evidence. Prepare a scoped direct upload with public:false, stream the authorized local bytes outside tool arguments, complete the upload, and bind the ready project-level version to the normal result before guide publication. The resulting guide stays private and project-readable. Without an authorized project-level capture, preserve truthful behavior evidence and report the guide blocked.",
165
+ "checks": [
166
+ "Same project alone does not make session-private or Computer-restricted evidence admissible.",
167
+ "Explicit public:false is passed to prepare_attachment_upload; no public link or visibility promotion.",
168
+ "File bytes use the signed upload transport outside tool arguments, then complete_attachment_upload.",
169
+ "Only the project-level ready immutable version appears in the normal result and guide.",
170
+ "No personal Drive migration, ownership relabeling or reupload of another user's assets.",
171
+ "No-local-capture variant leaves guide blocked without falsifying the observed normal result."
172
+ ]
173
+ }
174
+ ]
175
+ }