@xevy/skills 0.1.65 → 0.1.67
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.
- package/.claude-plugin/plugin.json +2 -2
- package/README.md +16 -1
- package/package.json +1 -1
- package/skills/analyze/SKILL.md +91 -0
- package/skills/create-artifact/SKILL.md +3 -3
- package/skills/create-feature/SKILL.md +58 -0
- package/skills/create-feature/evals/evals.json +158 -0
- package/skills/review-feature/SKILL.md +61 -0
- package/skills/review-feature/evals/evals.json +175 -0
- package/skills/review-pull-request/SKILL.md +21 -6
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xevy",
|
|
3
3
|
"displayName": "Xevy",
|
|
4
|
-
"description": "Native
|
|
5
|
-
"version": "0.1.
|
|
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.67",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Xevy"
|
|
8
8
|
},
|
package/README.md
CHANGED
|
@@ -112,12 +112,13 @@ 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) |
|
|
118
119
|
| `merge [task]` | Merge a task branch locally for review; leaves remotes and pull requests unchanged |
|
|
119
120
|
| `merge-pull-request [URL\|number\|branch]` | Evaluate a PR, repair conflicts, handle blockers, and merge it remotely |
|
|
120
|
-
| `review-pull-request [URL\|number\|branch]` |
|
|
121
|
+
| `review-pull-request [URL\|number\|branch]` | Evidence-based PR review; posts the full verdict as one new PR comment by default (opt-out), with code, records, and merge remaining read-only |
|
|
121
122
|
| `move-to-qa [task] [--cloud]` | QA handoff (local by default) |
|
|
122
123
|
| `move-to-verified [task]` | Record explicit QA approval and move an eligible task from For QA to Verified |
|
|
123
124
|
| `deploy` | Coolify preview/main |
|
|
@@ -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
|
@@ -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.
|
|
@@ -143,11 +143,11 @@ For other project images, retain the immutable handle returned by upload/generat
|
|
|
143
143
|
|
|
144
144
|
For other project Artifacts, prefer file transfer so the file bytes stay outside model context and MCP JSON arguments:
|
|
145
145
|
|
|
146
|
-
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
|
|
147
|
-
2. Through MCP, call `prepare_attachment_upload` with the exact filename, MIME type, byte size, description, optional task UUID, and
|
|
146
|
+
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 transfers accepted files through authenticated Xevy validation up to 100 MB; images are limited to 25 MB. On an interrupted transfer, retry the same file and metadata to resume the existing attachment.
|
|
147
|
+
2. Through MCP, call `prepare_attachment_upload` with the exact filename, MIME type, byte size, description, optional task UUID, visibility, and a stable `requestKey` reused on retries. Transfer the local file bytes through an authenticated host helper to the returned Xevy application `uploadUrl` using the exact `uploadMethod` and `requiredHeaders`, then call `complete_attachment_upload` with the returned `attachmentId`. Keep authentication inside the host helper. Uploads use the Xevy application endpoint; keep OVH credentials and signed storage URLs outside model context. 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.
|
|
148
148
|
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.
|
|
149
149
|
|
|
150
|
-
Text-backed Artifacts remain limited to 10 MB after decoding for safe parsing and preview.
|
|
150
|
+
Text-backed Artifacts remain limited to 10 MB after decoding for safe parsing and preview. Authenticated file transfer 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.
|
|
151
151
|
|
|
152
152
|
For a personal-note Artifact, call `create_note_attachment` with the content fields plus `noteId`. Note attachments are always private. Publishing a note is a separate explicit action.
|
|
153
153
|
|
|
@@ -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
|
+
}
|
|
@@ -1,18 +1,22 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: review-pull-request
|
|
3
|
-
description:
|
|
3
|
+
description: Review a GitHub pull request for merge conflicts, code defects, verification failures, and linked Xevy task coverage; post the full verdict as one PR comment by default unless the user opts out. Code, records, and merge behavior remain read-only.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Review a pull request
|
|
7
7
|
|
|
8
|
-
Review the exact PR and report evidence-based findings.
|
|
8
|
+
Review the exact PR and report evidence-based findings. Review remains **read-only for code, records, and merge**: do not edit source files, resolve conflicts, commit, push, submit a GitHub approval/change-request review, merge, deploy, or change Xevy records. There is exactly **one allowed mutation**: posting the full review summary as one new comment on the reviewed PR by default, unless the user explicitly says not to. Any other action requires separate authorization under its own workflow.
|
|
9
9
|
|
|
10
10
|
## 1. Identify the PR and working directory
|
|
11
11
|
|
|
12
|
+
- **Triage review depth first.** Inventory all changed files and affected flows, then classify each as focused (small, isolated, low-impact), standard (ordinary behavior change), or deep (security/auth, data integrity, payments/business decisions, concurrency/retries, migrations, deployment, broad refactors, or other critical paths). This adjusts effort, not coverage: account for every changed file and material flow; uncertain or high-impact areas receive deep review. Keep small PRs focused and avoid redundant historical or test work that cannot affect the verdict.
|
|
13
|
+
- **Keep a compact internal coverage ledger.** Track each changed file/flow, risk tier, reviewer/pass, evidence inspected or tested, and remaining gaps. Account for every changed file and requirement before the verdict. If material gaps mean the full changed scope cannot be reviewed, the verdict must be **MERGE SAFETY UNVERIFIED**. Keep the full ledger internal unless requested.
|
|
14
|
+
- **Parallelize when useful and supported.** For substantial PRs with separable behavior/risk areas and available independent reviewers, delegate disjoint scopes after pinning identical head/base SHAs and sharing task intent and conventions. Run independent safe checks concurrently where supported. Keep small PRs with one reviewer when coordination costs outweigh benefit. The lead owns the full inventory, confirms all delegated results arrived, reconciles disagreements against source evidence, and issues the verdict. Delegation never excuses skipped scope.
|
|
15
|
+
- **Add an omission-focused independent pass for substantial/high-risk reviews when available.** Give the second reviewer the pinned diff, requirements, changed-flow inventory, and ledger; ask them to find omissions, not merely confirm existing findings. Probe applicable error/recovery paths, authorization, concurrency/retries, partial data, and cross-component contracts. If unavailable or unwarranted, the lead performs an explicit gap pass and does not claim independent review.
|
|
12
16
|
- Accept a PR URL, number, or branch. If omitted, use the current branch's PR only when exactly one open PR matches; otherwise ask which PR.
|
|
13
17
|
- Identify the repository from the PR URL/metadata; do not ask the user to select a project directory or worktree when the PR uniquely identifies them. Ask only if repository identity is ambiguous or inaccessible.
|
|
14
18
|
- Review the PR's remote source and target branches, pinning their actual SHAs and merge-base. For required local verification, automatically locate an existing Git worktree where the PR source branch is checked out. Use that worktree only if it belongs to this PR/source branch and is safe to use; do not disrupt unrelated changes or another active task. If no suitable worktree exists, create a dedicated worktree for the PR source branch and record its path. Never ask the user which worktree to use. Do not switch branches in an existing checkout.
|
|
15
|
-
- Read the applicable `AGENTS.md` / `AGENTS.override.md` chain from the selected worktree. Keep
|
|
19
|
+
- Read the applicable `AGENTS.md` / `AGENTS.override.md` chain from the selected worktree. Keep inspection non-mutating: do not edit tracked files, commit, push, or merge. Only the final summary-comment step below may post a comment. Fetch/update remote refs as needed without altering another checkout. If the PR source branch is not available locally, fetch it and create the worktree at the exact reviewed head SHA; ensure the worktree represents the PR head, not a stale local branch.
|
|
16
20
|
- Testing is required. In the PR source worktree, run the repository's relevant focused tests and applicable lint, type-check, and build checks when feasible; include regression tests for suspected issues where practical. Avoid exposing secrets and do not run destructive commands. If dependencies, credentials, environment, or infrastructure prevent a check, report the exact limitation and mark that verification unverified; do not imply tests passed or issue an unqualified safe-to-merge verdict. Preserve pre-existing worktree changes and do not clean/reset them.
|
|
17
21
|
- Check whether this session is locked to a different task; do not switch its scope without the user's explicit approval under the session-lock rules.
|
|
18
22
|
- For a remote Dev Session, use `read_dev_session_pull_request` with the linked repository ID and PR number to read authenticated PR evidence; select the `dev_session` capability group if needed. Outside a session, use `code_pull_request` with the project and linked repository. Read `metadata`, then paginate `files`, `commits`, `reviews`, and `checks` until `nextPage` is null; inspect `diff` and every `truncated` flag. Use the returned top-level `headSha` and `baseSha` for current commit identity; `data.base.sha` retains GitHub's recorded PR base and can differ from the current target. Treat truncated or unavailable evidence as incomplete. Credentials stay in the toolbox; these tools require no `gh` login or token in the agent shell. If access is expired, ask the GitHub connection owner to reconnect and retry.
|
|
@@ -23,7 +27,7 @@ Review the exact PR and report evidence-based findings. This skill is **read-onl
|
|
|
23
27
|
|
|
24
28
|
- Look for an explicit Xevy task code/link in the PR title, body, branch, or project metadata. Do not assume a coincidental code is a link; ask if ambiguous.
|
|
25
29
|
- Resolve every linked Xevy task by code and read its original requirements plus relevant Analysis, specs, subtasks, decisions, and QA/review notes as needed. Check open decisions before task-based review; surface unresolved decisions rather than inventing expected behavior. Record each distinct linked task and its freshly fetched current status for the final response; never infer status from a PR, prior lookup, or another task.
|
|
26
|
-
- Inspect the full commit history contributing to the PR, not only the final diff or latest commit. Review commit messages
|
|
30
|
+
- Inspect the full commit history contributing to the PR, not only the final diff or latest commit. Review commit messages and identify task/scope references across the history. Inspect per-commit diffs and earlier versions to the depth needed to resolve intent, inherited/unrelated work, or regression origin; do not mechanically re-read historical diffs when they cannot change the current verdict. Compare the PR head to its current base for final behavior; history provides context and never excuses a defect in the final state.
|
|
27
31
|
- Check for multiple tasks in the PR title/body, branch, every commit message, and changed scope, including inherited commits. Deduplicate aliases that reference the same task (for example a Xevy code and its external tracker code); multiple identifiers alone do not prove multiple tasks. Distinguish intentionally included work from historical references or dependencies. Resolve identifiable additional Xevy tasks with targeted reads and check their status, remaining requirements, and relevance to the intended task. Do not assume a task is complete from its status alone or incomplete solely because it is not done.
|
|
28
32
|
- If no task is linked, review against the PR's stated objective and repository conventions. State that task-requirement coverage could not be assessed.
|
|
29
33
|
|
|
@@ -38,8 +42,8 @@ Review the exact PR and report evidence-based findings. This skill is **read-onl
|
|
|
38
42
|
- Investigate each suspected issue before reporting it: first establish intended behavior from the linked task and acceptance criteria, explicit decisions, PR description, design/spec documentation, and established surrounding behavior; then trace reachable callers, affected users/data, triggering conditions, existing guards, and consequences if left unfixed. Use a safe reproduction or test where feasible. Do not call an intentional change or omission a defect merely because a control, feature, behavior, or test is absent compared with the base branch. For example, a removed button is not a finding if its removal is required or explicitly intended. Report only behavior that conflicts with established intent or is an unintended consequence of the change as a confirmed finding. If intent is ambiguous or cannot be resolved, put it under **Warnings / Questions** with the missing evidence and potential impact; do not state it as a defect or release blocker. Classify each confirmed issue as **Release blocker** or **Non-blocking** independently of severity. A release blocker prevents a required flow, violates a critical task requirement, causes materially incorrect decisions, or creates significant security, data-integrity, or operational risk. Explain the concrete unfixed consequence; do not infer blocker status from severity alone. If reachability or impact cannot be established, report it under Questions/Risks with blocker status unverified, not as a confirmed blocker.
|
|
39
43
|
- Identify risky changes even when no defect is confirmed: destructive/bulk data operations; auth and permissions; financial or business-decision logic; API/integration contracts; jobs, retries and concurrency; deployment/configuration/dependencies; critical UI actions; broad refactors or unrelated/inherited scope. Assess affected users/data, reversibility, compatibility, test coverage, and recovery safeguards. Do not treat a risk category alone as a defect or release blocker; escalate only when evidence supports an unsafe condition, and mark material unresolved safety questions unverified.
|
|
40
44
|
- Build a risk-based test matrix from every changed behavior: expected outcome, counterexample, overlapping/multiple records, ordering, and relevant boundary conditions. Identify what was exercised by local tests or CI, what was assessed only by code inspection, and what remains unverified. Prioritize tests for high-impact paths over indiscriminate test runs. A passing test suite does not replace tracing untested combinations.
|
|
41
|
-
- On a repeat review, obtain the previous review report (ask the user for it if not accessible) and record its reviewed head/base SHAs, findings, coverage ledger, and unverified items. Recheck every previous finding and all changed lines since the earlier head,
|
|
42
|
-
- Run relevant tests, lint, type-check, and build checks only where safe in the permitted working directory; avoid commands that rewrite tracked files or require secrets. If not run, explain why. Separate PR-introduced failures from baseline/infrastructure failures where evidence supports it. Never claim there are no code issues solely because CI is green.
|
|
45
|
+
- On a repeat review, obtain the previous review report (ask the user for it if not accessible) and record its reviewed head/base SHAs, findings, coverage ledger, and unverified items. Recheck every previous finding and all changed lines since the earlier head, then repeat the full changed-file and affected-flow inventory; do not limit review to the fix diff. Reuse prior evidence only for unchanged files/flows when the head/base comparison, requirements, dependencies, interfaces, and relevant assumptions remain unchanged and the prior evidence is available. Reopen areas affected by the fix, a moved base, changed contracts, or assumptions; mark unavailable or stale coverage unverified. Never infer safety solely from unchanged lines. Attribute each new finding as introduced by later changes, exposed by a base change, pre-existing but missed, or unknown; do not claim regression origin without evidence.
|
|
46
|
+
- Run relevant tests, lint, type-check, and build checks only where safe in the permitted working directory; avoid commands that rewrite tracked files or require secrets. Select checks from the risk-based matrix, prioritize high-impact paths, and run independent checks concurrently when safe and supported. If not run, explain why. Separate PR-introduced failures from baseline/infrastructure failures where evidence supports it. Never claim there are no code issues solely because CI is green.
|
|
43
47
|
- Immediately before the verdict, re-read the PR's head and base SHAs. If either changed during review, refresh affected diff, mergeability, checks, and verification or mark the verdict stale/inconclusive; never present an earlier SHA's results as current.
|
|
44
48
|
|
|
45
49
|
## 4. Deliver a verdict
|
|
@@ -56,7 +60,18 @@ Review the exact PR and report evidence-based findings. This skill is **read-onl
|
|
|
56
60
|
- If multiple distinct tasks contribute changes to the PR, include **WARNING — Multiple tasks in this PR**, listing their identifiers, completion/verification status, and whether their inclusion is approved and necessary for the intended task. Explain briefly that unrelated or unfinished work would merge together. If additional work is suspected but task linkage cannot be established, label it suspected and state the missing evidence. Ask for clarification when scope approval is ambiguous; do not invent approval. Treat confirmed critical scope violations or unsafe unfinished behavior as blockers, and material unresolved scope/safety questions as unverified—not every multi-task PR as automatically unsafe.
|
|
57
61
|
- Include a short **Warnings / Questions** section when needed for intentional changes that may surprise reviewers, ambiguous intent, suspected risks, multiple-task scope, or material unverified behavior. Explain what is observed, why it may matter, and what intent/evidence needs confirmation. Do not list intended behavior as a finding; when intent is confirmed, describe it only as an informational warning if it is useful to alert reviewers. Keep warnings separate from confirmed defects and blockers. Reflect unresolved material safety questions in the merge indicator. Omit the section when there is nothing material to flag.
|
|
58
62
|
- On repeat reviews, provide a finding ledger: each prior finding marked fixed/still present/unverified, plus each new finding's evidenced origin (fix change, base change, pre-existing miss, or unknown). Explicitly acknowledge a pre-existing miss rather than calling it a regression. Compare coverage gaps with the earlier report.
|
|
63
|
+
- For an optional process pilot/retrospective, record elapsed review time, later-confirmed missed issues, false positives, and unverified coverage across representative small and large PRs. Do not claim faster or more complete reviews without comparative evidence.
|
|
59
64
|
- Summarize verification in 1–3 bullets: what passed, material unverified flows, and access limitations. Keep the complete risk-based test matrix and every affected file/flow in the internal coverage ledger; include detail in the response only for consequential gaps or on request. If the full changed scope cannot be reviewed, use **MERGE SAFETY UNVERIFIED** unless a confirmed blocker already requires **NOT SAFE TO MERGE**.
|
|
60
65
|
- When tasks are linked, list every linked task identifier with its freshly refreshed status and gate result, then list requirements as concise bullets labeled met, partial, unmet, or unverified, each with evidence. Unknown/inaccessible task statuses must be explicitly marked unverified and are procedural blockers. When multiple tasks are linked, every task must pass the status gate; one failing task blocks the recommendation. Without a task, explicitly note that task coverage was not assessed.
|
|
61
66
|
- State limitations (missing credentials, unavailable checks, unrun tests, stale mergeability, uncertain task link). Say “no issues found in the reviewed scope,” not “no issues exist,” when appropriate.
|
|
62
67
|
- Do not merge or modify records as a consequence of a favorable verdict. Offer a separate follow-up if fixes or a merge are wanted.
|
|
68
|
+
|
|
69
|
+
## 5. Post the completed verdict as one PR comment
|
|
70
|
+
|
|
71
|
+
- Post **exactly one comment per completed review**, only after the complete verdict is established, unless the user explicitly says not to post. Never post mid-review or for aborted/inaccessible PRs. A completed review may report blockers or unverified checks; do not turn a posting failure into a favorable verdict.
|
|
72
|
+
- Render the full verdict from step 4 as one Markdown comment (headings and bullets, no tables), not just a teaser or link. Include the merge indicator and reviewed head/base SHAs, PR URL, every linked task code and freshly refreshed status (or Not linked/Unverified), the actual **Reviewed at:** timestamp, all findings and their **If not fixed:** and **Error if not fixed: Yes / No / Unverified** details, warnings, verification summary and limitations, and concise requirement coverage. End with the exact attribution footer: `🤖 Review generated by Xevy's review-pull-request skill`.
|
|
73
|
+
- On local checkouts with an existing authenticated `gh` login, verify the PR/repository identity and run `gh pr comment <PR> --body-file <tempfile>` in the PR's checkout. Use a private temporary UTF-8 file, not shell interpolation of verdict text; remove that temporary file afterwards. Do not expose credentials or request a new local login as a fallback from a Dev Session.
|
|
74
|
+
- In remote Dev Sessions use `comment_dev_session_pull_request` with sessionId, linked repositoryId, number, and body. Via Xevy CLI/MCP outside a session, use `comment_code_pull_request` with the project identifiers, linked repositoryId, number, and body. Select the `dev_session` or `repositories` capability group respectively if needed. These tools use Xevy's sealed GitHub connection and the session's pinned identity where applicable; no gh dependency, login, or token is needed in a Dev Session shell.
|
|
75
|
+
- Repeat reviews post a new comment: **never edit or delete previous comments**. Never post a second comment for the same completed review or automatically retry an uncertain write. If the request times out or returns an invalid receipt, inspect the PR for the comment first; do not claim success without a confirmed receipt or observed comment.
|
|
76
|
+
- If posting is unavailable or fails (including a missing toolbox endpoint, expired GitHub connection, insufficient write permission, or network error), still deliver the full verdict to the user and state exactly why the comment was not posted or why posting is unconfirmed. Include the comment URL on confirmed success; state when the user opted out. Do not silently drop findings, split into multiple comments, or fall back to editing old comments if the verdict exceeds the tool's 65536-character limit; report that posting limitation honestly.
|
|
77
|
+
- Include **no secrets or internal coverage ledgers in comments**. Never copy tokens, sealed credentials, environment values, private logs, or internal reviewer/coverage matrices into the body. The concise requirement coverage and verification summary belong in the verdict; internal ledgers do not.
|