@xevy/skills 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.claude-plugin/plugin.json +23 -0
  2. package/README.md +133 -0
  3. package/bin/cli.mjs +387 -0
  4. package/bin/version.mjs +120 -0
  5. package/bin/xevy-creds.mjs +81 -0
  6. package/bin/xevy-link-repo.mjs +47 -0
  7. package/bin/xevy-sync-env.mjs +102 -0
  8. package/package.json +33 -0
  9. package/skills/analyze/SKILL.md +26 -0
  10. package/skills/analyze-here/SKILL.md +30 -0
  11. package/skills/create-document/SKILL.md +32 -0
  12. package/skills/create-report/SKILL.md +169 -0
  13. package/skills/create-report/examples.md +134 -0
  14. package/skills/create-xevy-task/SKILL.md +68 -0
  15. package/skills/deploy/SKILL.md +25 -0
  16. package/skills/execute/SKILL.md +29 -0
  17. package/skills/execute-here/SKILL.md +35 -0
  18. package/skills/fix/SKILL.md +26 -0
  19. package/skills/fix-here/SKILL.md +23 -0
  20. package/skills/generate-image/SKILL.md +31 -0
  21. package/skills/investigate/SKILL.md +218 -0
  22. package/skills/investigate/examples.md +170 -0
  23. package/skills/manage-documents/SKILL.md +39 -0
  24. package/skills/mark-ready/SKILL.md +29 -0
  25. package/skills/merge/SKILL.md +24 -0
  26. package/skills/merge-here/SKILL.md +22 -0
  27. package/skills/move-to-qa/SKILL.md +21 -0
  28. package/skills/move-to-qa-here/SKILL.md +21 -0
  29. package/skills/plan/SKILL.md +24 -0
  30. package/skills/plan-here/SKILL.md +26 -0
  31. package/skills/xevy-design/SKILL.md +103 -0
  32. package/skills/xevy-design/reference/craft.md +69 -0
  33. package/skills/xevy-design/reference/critique.md +33 -0
  34. package/skills/xevy-design/reference/polish.md +25 -0
  35. package/skills/xevy-design/reference/setup.md +82 -0
  36. package/skills/xevy-design/reference/shape.md +40 -0
  37. package/skills/xevy-setup/SKILL.md +56 -0
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: manage-documents
3
+ description: Manage Xevy project documents end to end — list, find, read, edit, organise, share, and delete. Use when the user wants to review existing docs, update a doc's body/title, change status (draft/for review/done), share or unshare (private/shared/public link), reorder, or remove a document. For creating a brand-new document, prefer /xevy:create-document.
4
+ argument-hint: "[what to do, e.g. 'list shared docs', 'publish the runbook', 'archive old RFC']"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read mcp__xevy__get_current_user mcp__xevy__list_workspaces mcp__xevy__list_projects mcp__xevy__list_documents mcp__xevy__list_workspace_documents mcp__xevy__get_document mcp__xevy__create_document mcp__xevy__update_document mcp__xevy__delete_document"
7
+ ---
8
+
9
+ # /xevy:manage-documents — manage project documents
10
+
11
+ Full lifecycle management of Xevy documents. Documents are project-scoped but **personal**: `private` to their creator by default, optionally `shared` with project members, or `public` (readable by anyone with the link, no login). `$ARGUMENTS` describes what to do.
12
+
13
+ ## 1. Resolve context
14
+ - Prefer `.xevy/project.json` for `workspaceIdentifier` + `projectIdentifier`. If missing, call `mcp__xevy__list_projects` (and `mcp__xevy__list_workspaces` when there's more than one workspace) and ask which project when ambiguous.
15
+ - `mcp__xevy__get_current_user` confirms whose documents you can see (private docs are owner-only).
16
+
17
+ ## 2. Find the document(s)
18
+ - **One project:** `mcp__xevy__list_documents` → your private docs plus anything shared/public in that project.
19
+ - **Across the workspace:** `mcp__xevy__list_workspace_documents` → every accessible document in all projects (each item carries `projectIdentifier` and, when public, a `publicUrl`).
20
+ - **Read one:** `mcp__xevy__get_document` with the `documentId` for the full markdown `details`.
21
+ - Match the user's description (title/topic) to a document; if several match, list the candidates and ask which one. Never guess at a destructive action.
22
+
23
+ ## 3. Apply the change — all via `mcp__xevy__update_document`
24
+ - **Edit body / title:** set `details` (markdown) and/or `title`. When revising, read the current `details` first and preserve content the user didn't ask to change.
25
+ - **Status:** set `status` to `draft`, `for_review`, or `done`.
26
+ - **Visibility / sharing:**
27
+ - `private` — only the creator.
28
+ - `shared` — project members ("share with the team").
29
+ - `public` — anyone with the link, no login. **Confirm first** before making something public, and again before reverting a public doc to private (its shared link will stop working).
30
+ - **Reorder:** set `sortOrder` (lower sorts first) to move a document up/down the project's list.
31
+ - **Metadata:** pass a `metadata` object to merge arbitrary keys.
32
+
33
+ ## 4. Delete
34
+ - `mcp__xevy__delete_document` (soft delete). This is destructive — confirm the exact title with the user first. Private docs can only be deleted by their owner.
35
+
36
+ ## 5. Report
37
+ - State what changed (title, status, visibility) and, when a document is **public**, give the no-login link from the tool's `publicUrl` field (shape: `<XEVY_BASE>/d/<documentId>`).
38
+ - For lists, show title · status · visibility (and project, for workspace-wide lists) — concise, scannable.
39
+ - Never paste private document content into third-party tools, and never print secrets.
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: mark-ready
3
+ description: Mark a task ready for work — answer any open questions (decisions) first, then move its status to ready. Analyze is optional; this is the human gate that promotes a task from draft → ready. Runs locally in this session (no cloud agent, no code changes).
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Bash mcp__xevy__find_task mcp__xevy__list_task_decisions mcp__xevy__answer_decision mcp__xevy__update_task_status"
7
+ ---
8
+
9
+ # /xevy:mark-ready — answer open questions, then mark the task ready
10
+
11
+ This is the **human gate** that promotes a task from `draft` → `ready`. Analyze is optional, so a task does not need an Analysis section to become ready. This command runs locally in this session: it does **not** start a cloud agent, write code, or touch git — it only resolves open questions and flips the status.
12
+
13
+ ## 1. Resolve the task
14
+ Resolve from `$ARGUMENTS` (`mcp__xevy__find_task` by code) or the in-context task. If ambiguous, ask which task — never guess.
15
+
16
+ ## 2. Check the current status
17
+ Read the resolved task's status. `mark-ready` only promotes a task that is in **`draft`**. If it is already `ready` or further along (`in_progress` / `for_review` / `for_qa` / `done`), STOP and report the current status — do **NOT** move it backwards. Continue only when the status is `draft`.
18
+
19
+ ## 3. Answer open questions (MANDATORY gate)
20
+ - Call `mcp__xevy__list_task_decisions` for the task.
21
+ - For **every** decision that is still OPEN, present the question and its preset choices to the user, then record their answer with `mcp__xevy__answer_decision` (pass the chosen `answerChoiceId` and/or `answerText`). Never fabricate an answer or skip an open question.
22
+ - Answering may trigger a server-side analyze re-run — that is expected and does **not** change the task status.
23
+ - Do not proceed while any decision is still open.
24
+
25
+ ## 4. Mark ready
26
+ Once **no** open decisions remain, call `mcp__xevy__update_task_status({ taskId, status: "ready" })`.
27
+
28
+ ## 5. Report
29
+ Report the task code/title, its new status (`ready`), and the task URL. Don't push the user into `/xevy:plan` or `/xevy:analyze` — let them choose the next step at their own pace.
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: merge
3
+ description: Merge a task's branch in the cloud — the Xevy server agent's 'merge' action verifies the open-subtasks gate, syncs the base branch into the feature to resolve conflicts, then lands the feature into the base/default branch (GitHub PR merge when possible, else a local merge + push of the base). Review the result and run tests after. Use /xevy:merge-here to merge locally.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions mcp__xevy__deploy_main mcp__xevy__get_deploy_status"
7
+ ---
8
+
9
+ # /xevy:merge — merge in the cloud (then review)
10
+
11
+ Cloud is the default engine: the server agent verifies the open-subtasks gate, syncs the base branch into the feature to resolve conflicts, then **lands the feature into the base/default branch** — via the GitHub merge API when possible (honouring branch protection), otherwise a local merge + push of the base. No task-status change. **You then review.** To merge locally, use `/xevy:merge-here`.
12
+
13
+ ## 1. Resolve
14
+ Resolve the task (`$ARGUMENTS` / context).
15
+
16
+ ## 2. Run the cloud action
17
+ - `mcp__xevy__start_ai_action({ taskId, action: "merge", stream: true })` — **always pass `stream: true`**. The call blocks and streams live per-step progress; report it as it arrives, plus any conflicts/verification results it reports. Do **NOT** use fire-and-forget or `sleep`/manual poll loops — streaming is the default and is reliable. Only if this streamed call returns *before* a terminal status (genuine disconnect — the run keeps going server-side) resume with `get_ai_execution`. On failure surface output.
18
+
19
+ ## 3. Review & correct (MANDATORY)
20
+ - `git fetch origin` and inspect the merged branch. Confirm the merge is clean, the base was integrated, and the build/tests still pass. If conflicts were left or tests fail, **fix them** on the feature branch (never push a protected branch directly) and re-verify.
21
+ - Report PASS/PARTIAL/FAIL with evidence. Merge mode must NOT move the task to done.
22
+
23
+ ## 4. Main deploy (optional, policy-aware)
24
+ - If the user wants main updated, `mcp__xevy__deploy_main` deploys the project's REMOTE default branch. NEVER push protected branches (master/main/develop/staging) to make main reflect local work — land via PR first; warn that main shows the remote/PR-merged state. Report the main URL.
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: merge-here
3
+ description: Merge a task's branch locally in this Claude Code session — merge the feature branch into the current branch for review (no push), run tests, resolve conflicts, then review. Cloud equivalent is /xevy:merge.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Edit Bash mcp__xevy__find_task mcp__xevy__deploy_main mcp__xevy__get_deploy_status"
7
+ ---
8
+
9
+ # /xevy:merge-here — merge locally (then review)
10
+
11
+ ## 1. Resolve + merge
12
+ Resolve the task (`$ARGUMENTS` / context) and its canonical branch. Merge that branch into the CURRENT checked-out branch in the current worktree (fetch + merge from remote if it only exists there). If conflicts occur, resolve them directly (don't abort), stage, and complete the merge commit.
13
+
14
+ ## 2. Review & correct (MANDATORY)
15
+ Run verification for the merged scope: `git status`, then the project's test/lint/build checks. Report clear PASS/FAIL plus any conflict files you resolved. Fix failures before finishing.
16
+
17
+ ## 3. Rules
18
+ - The merge is LOCAL ONLY — do NOT push, and do NOT change task status (no move to done). The user pushes manually from the main worktree.
19
+ - Keep the task worktree for iteration (don't delete it).
20
+
21
+ ## 4. Main deploy (optional, policy-aware)
22
+ If the user wants main updated: NEVER push a protected base (master/main/develop/staging) directly — those need a PR. If the base is protected, call `mcp__xevy__deploy_main` (deploys the REMOTE default branch) and warn it won't include this local merge until the PR lands. Only a non-protected base may be pushed (with explicit approval) before deploying. Report the main URL.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: move-to-qa
3
+ description: Move a task to QA in the cloud — run the Xevy server agent's 'move-to-qa' action (creates/updates QA Notes, sets status for_qa), then review the QA Notes for completeness. Use /xevy:move-to-qa-here to do it locally.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Bash mcp__xevy__find_task mcp__xevy__list_task_notes mcp__xevy__get_task_note mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
+ ---
8
+
9
+ # /xevy:move-to-qa — move to QA in the cloud (then review)
10
+
11
+ Cloud is the default engine: the server agent creates/updates QA Notes and sets status to `for_qa`. **You then review the notes.** To do it locally, use `/xevy:move-to-qa-here`.
12
+
13
+ ## 1. Resolve
14
+ Resolve the task (`$ARGUMENTS` / context).
15
+
16
+ ## 2. Run the cloud action
17
+ - `mcp__xevy__start_ai_action({ taskId, action: "move-to-qa", stream: true })` — **always pass `stream: true`**. The call blocks and streams live per-step progress; report it as it arrives. Do **NOT** use fire-and-forget or `sleep`/manual poll loops — streaming is the default and is reliable. Only if this streamed call returns *before* a terminal status (genuine disconnect — the run keeps going server-side) resume with `get_ai_execution`. On failure surface output.
18
+
19
+ ## 3. Review & correct (MANDATORY)
20
+ - Read the QA Notes (`list_task_notes` → `get_task_note`). Verify they are non-technical and UI-verifiable, with: pre-test preconditions, step-by-step reproduction (expected vs actual), validation checks, evidence to capture, and a final verdict section.
21
+ - If thin or technical, **fix** them (rewrite via the local variant or `update_task_note`). Confirm status is `for_qa` (not `done`). Report what you corrected and the task URL.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: move-to-qa-here
3
+ description: Move a task to QA locally in this Claude Code session — write/update non-technical, UI-verifiable QA Notes, set status for_qa, then review. Cloud equivalent is /xevy:move-to-qa.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__list_task_notes mcp__xevy__create_task_note mcp__xevy__update_task_note mcp__xevy__update_task_status"
7
+ ---
8
+
9
+ # /xevy:move-to-qa-here — move to QA locally (then review)
10
+
11
+ ## 1. Resolve
12
+ Resolve the task (`$ARGUMENTS` / context). Read the implementation and what changed.
13
+
14
+ ## 2. Write QA Notes
15
+ Create or update a note titled `QA Re-Testing Guide` (`create_task_note`/`update_task_note`). Keep it non-technical and UI-verifiable, with these sections in order: (1) Pre-Test Preconditions — deployment/context/account readiness; (2) Reproduction Steps — step table with expected vs actual + pass/fail; (3) Expected vs Actual Behaviour + edge-case checklist; (4) Validation Checks — functional, UI/UX, data/state, integration; (5) Screenshots/Logs/Evidence — what + how to capture; (6) Final Verdict — Pass/Fail/Partial + follow-ups.
16
+
17
+ ## 3. Set status
18
+ Set the task status to `for_qa` (`update_task_status`). Do NOT move to `done`.
19
+
20
+ ## 4. Review & correct (MANDATORY)
21
+ Re-read the QA Notes: are the steps something a non-technical QA can follow and verify in the UI? Are expected results concrete? Fix gaps before finishing. Report the task URL and a short summary.
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: plan
3
+ description: Plan a task in the cloud — run the Xevy server agent's 'plan' action (writes plan spec + ordered subtasks), then review and correct the plan. Use /xevy:plan-here to plan locally.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__list_specs mcp__xevy__get_spec mcp__xevy__list_subtasks mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
+ ---
8
+
9
+ # /xevy:plan — plan in the cloud (then review)
10
+
11
+ Cloud is the default engine: the server agent writes the plan spec + ordered subtask checklist; **you then review and correct it**. To plan locally, use `/xevy:plan-here`.
12
+
13
+ ## 1. Resolve the task
14
+ Resolve from `$ARGUMENTS` or context. The task should be analyzed first (a `## Analysis` section). If not, suggest `/xevy:analyze` and stop.
15
+
16
+ ## 2. Run the cloud action
17
+ - `mcp__xevy__start_ai_action({ taskId, action: "plan", stream: true })` — **always pass `stream: true`**. The call blocks and streams live per-step progress; report it as it arrives. Do **NOT** use fire-and-forget or `sleep`/manual poll loops — streaming is the default and is reliable. Only if this streamed call returns *before* a terminal status (genuine disconnect — the run keeps going server-side) resume with `get_ai_execution`. On failure, surface the output and offer retry or `/xevy:plan-here`.
18
+
19
+ ## 3. Review & correct (MANDATORY — act as plan-reviewer)
20
+ - Read the produced plan spec (`list_specs` → `get_spec`) and subtasks (`list_subtasks`).
21
+ - Build a quick trace matrix: every requirement from the task/Analysis → a subtask/step that covers it. Flag orphans (requirements with no step) and gaps (steps with no requirement). Inspect the code with Read/Grep to confirm the plan is feasible and references real files.
22
+ - Check cross-flow risks (guards, context rehydration, effects, async side effects) are addressed, and that any "must NOT" constraints have explicit verification.
23
+ - **Fix** gaps: edit the spec / add or reorder subtasks via MCP. Re-review until the matrix has no orphans.
24
+ - Report a PASS/PARTIAL verdict, the gaps you closed, and the task URL.
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: plan-here
3
+ description: Plan a task locally in this Claude Code session — dispatch scout + plan-reviewer subagents, write the plan spec + ordered subtasks via MCP, then review. Cloud equivalent is /xevy:plan.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash Agent mcp__xevy__find_task mcp__xevy__create_spec mcp__xevy__update_spec mcp__xevy__list_specs mcp__xevy__create_subtask mcp__xevy__list_subtasks mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision"
7
+ ---
8
+
9
+ # /xevy:plan-here — plan locally (then review)
10
+
11
+ Run planning yourself in this session.
12
+
13
+ ## 1. Resolve + recon
14
+ Resolve the task (`find_task` (by code)); it should have a `## Analysis` section (else suggest `/xevy:analyze-here`). **Decisions gate (BEFORE the work):** call `mcp__xevy__list_task_decisions`; if any decision is **open**, resolve it first (open decisions block AI actions) — present each via **AskUserQuestion**, record with `mcp__xevy__answer_decision`, and reflect it in the plan. Dispatch the **scout** subagent (`Agent`) for codebase recon — relevant files, callers/callees, similar patterns, baseline health.
15
+
16
+ ## 2. Write the plan
17
+ - Create a plan spec (`mcp__xevy__create_spec`, kind `plan`) with step-by-step changes (file paths + line ranges) and a trace matrix (requirement → files → strategy → test).
18
+ - Create ordered subtasks (`mcp__xevy__create_subtask`) grouping the work into reviewable pieces, each end-to-end (frontend + backend for one feature together).
19
+
20
+ ## 3. Plan-review
21
+ Dispatch the **plan-reviewer** subagent to cross-check every matrix item vs requirements (no orphans/gaps), verify cross-flow risks and "must NOT" constraints are covered, and that tests hit the exact branches. Fold its findings back into the spec/subtasks.
22
+
23
+ When planning surfaces a genuine open question a human must resolve, record it with `mcp__xevy__create_decision` (preset choices + explanation) rather than guessing — it gates execution until answered.
24
+
25
+ ## 4. Review & correct (MANDATORY)
26
+ Confirm the final plan is complete and feasible against the actual code; fix any remaining gap before finishing. Post-check: call `mcp__xevy__list_task_decisions` — if any decision is still open, surface it. Report a PASS/PARTIAL verdict, the matrix summary, any open decisions, and the task URL.
@@ -0,0 +1,103 @@
1
+ ---
2
+ name: xevy-design
3
+ description: Use when the user wants to design, redesign, shape, critique, polish, or build a frontend interface in an Xevy project — pages, app shells, components, forms, dashboards, settings, onboarding, empty states. Covers visual hierarchy, layout, spacing, typography, colour, motion, accessibility, responsive behaviour, UX copy, and reusable design systems. The project's design system lives in ./.xevy/design.md and is mirrored to a Document in the Xevy database; visual probes and mocks are produced with Xevy image generation. Not for backend-only or non-UI tasks.
4
+ argument-hint: "[command] [target] — e.g. 'craft the deploy settings panel', 'critique the task board', 'shape onboarding'"
5
+ allowed-tools: "Read Write Edit Bash Glob Grep mcp__xevy__generate_image mcp__xevy__get_current_user mcp__xevy__list_workspaces mcp__xevy__list_projects mcp__xevy__list_documents mcp__xevy__get_document mcp__xevy__create_document mcp__xevy__update_document mcp__xevy__find_task"
6
+ ---
7
+
8
+ # /xevy:xevy-design — design & build production-grade frontend
9
+
10
+ Designs and iterates real, working frontend interfaces for an Xevy project. Committed design choices, exceptional craft, no generic AI output. `$ARGUMENTS` selects a command (see the table) or is a freeform design request.
11
+
12
+ ## Setup (non-optional)
13
+
14
+ Pass these gates before any design work or file edit. Skipping them produces generic output that ignores the project.
15
+
16
+ | Gate | Check | If it fails |
17
+ |---|---|---|
18
+ | Project | `workspaceIdentifier` + `projectIdentifier` resolved (from `.xevy/project.json`, else `list_projects` / `list_workspaces`). | Resolve first; ask which project only when ambiguous. |
19
+ | Design context | `./.xevy/design.md` is loaded and is not empty/placeholder (<200 chars, `[TODO]` markers). | Run `setup` ([reference/setup.md](reference/setup.md)), then resume the original request. Never invent a design system silently. |
20
+ | Shape | For `craft`, a **user-confirmed** design brief exists for this task. | Run `shape` and wait for explicit confirmation. The design context is not a brief. |
21
+ | Image | Visual probes/mocks are generated with `generate_image`, or skipped with a one-line reason. | Resolve the image gate in `shape.md` / `craft.md` before code. |
22
+
23
+ State this line before editing project files:
24
+
25
+ ```text
26
+ FRONTEND_PREFLIGHT: project=pass design_context=pass shape=pass|not_required image=pass|skipped:<reason>
27
+ ```
28
+
29
+ ### Loading the design context
30
+
31
+ 1. Read `./.xevy/design.md`. If present and substantial, it is the source of truth — use it.
32
+ 2. If absent, look in the database: `list_documents` for the current project and find the one titled **"Design System"**. If found, write its `details` to `./.xevy/design.md` (preserving the pointer marker, below) and use it.
33
+ 3. If neither exists, run **`setup`** to author it. Do not proceed to design with no context.
34
+
35
+ If the design context is already in this session's history, don't re-read it. Re-load only after `setup` rewrites it or the user edits it.
36
+
37
+ ## design.md ⇄ Database (the source of truth, persisted both ways)
38
+
39
+ The project's design decisions live in **two synced places**:
40
+
41
+ - **`./.xevy/design.md`** — canonical local working copy that this skill reads each session. Its first line is a pointer marker carrying the database Document id:
42
+
43
+ ```html
44
+ <!-- xevy:document-id: <uuid> -->
45
+ ```
46
+
47
+ - **An Xevy Document** (title `Design System`, visibility `shared`) — the database mirror. It shows in the project's Documents app and is readable by the Xevy cloud agent and teammates.
48
+
49
+ **Sync contract:**
50
+
51
+ | Event | Action |
52
+ |---|---|
53
+ | `setup` authors a new design system | Write `./.xevy/design.md`, then `create_document` (title `Design System`, visibility `shared`) with the same body. Prepend the returned id as the pointer marker. |
54
+ | You edit `./.xevy/design.md` (e.g. after `extract`/`document`, or a confirmed system change) | `update_document` the pointered id with the new `details` so the database stays in sync. If the marker is missing, fall back to find-by-title, else `create_document`. |
55
+ | design.md absent but DB doc exists | Pull `details` into `./.xevy/design.md`. |
56
+
57
+ Never let the two drift. The local file is authoritative for editing; the database doc is the shared, durable record. Never paste private app data, customer data, or secrets into design.md or the doc.
58
+
59
+ ## Register: brand vs product
60
+
61
+ Every design task is **brand** (marketing, landing, campaign — design IS the product) or **product** (app UI, dashboard, settings, tools — design SERVES the product). Most Xevy surfaces are **product**. Identify before designing; the `register` field in design.md is the tiebreaker, but a cue in the task ("landing page" vs "settings panel") wins.
62
+
63
+ ## Shared design laws
64
+
65
+ Apply to every task. The project's specifics (palette, type, components, anti-references) come from `design.md`; these are the universal rules `design.md` must not contradict.
66
+
67
+ **Colour** — Work in OKLCH. Never `#000`/`#fff`; tint neutrals toward the brand hue (chroma 0.005–0.01). Reduce chroma at lightness extremes. Pick a strategy first: Restrained (tinted neutrals + one accent ≤10%; the product default), Committed, Full palette, or Drenched. Don't collapse everything to Restrained by reflex, and don't exceed it without reason.
68
+
69
+ **Theme** — Light vs dark is never a category default. Write one sentence of physical scene (who, where, ambient light, mood) and let it force the answer. *Note: if `design.md` mandates light-mode-only (as Xevy's app shell does), honour that.*
70
+
71
+ **Typography** — Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Body measure 65–75ch. Pick from the project's type scale; never inline one-off px sizes.
72
+
73
+ **Layout** — Vary spacing for rhythm; uniform padding everywhere is monotony. Cards are the lazy answer — use them only when they're the best affordance, and never nest them. Don't wrap everything in a container. Prefer the project's established list-row / section patterns over inventing new ones.
74
+
75
+ **Motion** — Don't animate layout properties. Ease out with exponential curves (ease-out-quart/quint/expo). No bounce, no elastic. Respect reduced motion.
76
+
77
+ **Absolute bans** (match-and-refuse; rewrite the element if you reach for one): coloured side-stripe borders (`border-left`/`right` >1px as accent); gradient text (`background-clip:text`); decorative glassmorphism by default; the hero-metric template (big number + gradient accent); identical card grids; modal as first thought (exhaust inline/progressive first).
78
+
79
+ **Copy** — Every word earns its place; no headings restated as intros. Be concrete (numbers, units) over adjectives.
80
+
81
+ **The AI-slop test** — If someone could look at the result and say "AI made that," it failed. Run the category-reflex check: if the theme + palette is guessable from the domain alone, rework the scene sentence and colour strategy until it isn't.
82
+
83
+ ## Image generation (Xevy)
84
+
85
+ Visual probes and north-star mocks use **`mcp__xevy__generate_image`** (not a local pipeline). Generated images are stored as project attachments, returned as URLs, and appear in the project Gallery — so the team can see the direction. Generation needs write access and is a paid provider call: generate once per request, don't loop on success. Pass `taskId` when the work maps to a task (resolve a task code with `find_task` first). When to generate is gated per-command in `shape.md` and `craft.md`; if it's skipped, say so in one line and proceed.
86
+
87
+ ## Commands
88
+
89
+ | Command | Description | Reference |
90
+ |---|---|---|
91
+ | `setup` | Author `./.xevy/design.md` from the project (interview + code scan) and mirror it to the database. | [reference/setup.md](reference/setup.md) |
92
+ | `shape [target]` | Plan UX/UI before code: discovery, visual probes, a confirmed design brief. | [reference/shape.md](reference/shape.md) |
93
+ | `craft [target]` | Shape, land a visual direction, build to production quality, iterate in-browser. | [reference/craft.md](reference/craft.md) |
94
+ | `critique [target]` | Heuristic UX/design review with scored findings. | [reference/critique.md](reference/critique.md) |
95
+ | `polish [target]` | Final craft pass before shipping: spacing, type, states, a11y, responsive. | [reference/polish.md](reference/polish.md) |
96
+
97
+ ### Routing
98
+
99
+ 1. **No argument** — render the command table as a menu and ask what they'd like to do.
100
+ 2. **First word matches a command** — load its reference and follow it. The rest is the target.
101
+ 3. **First word doesn't match** — freeform design invocation: apply Setup, the shared design laws, the register reference, and `design.md`, using the full argument as context.
102
+
103
+ Setup (project + design context) runs once per session before any branch.
@@ -0,0 +1,69 @@
1
+ # craft — design and build a feature end to end
2
+
3
+ Shape the design, land a visual direction, build real production code, then inspect and fix in-browser until it meets a high-end studio bar. Craft is a loop, not a first pass.
4
+
5
+ ## Build gate
6
+
7
+ Do not build until all are true:
8
+
9
+ 1. `design.md` context is loaded and current.
10
+ 2. A **user-confirmed** design brief exists for this task (run `shape` if not — its output is the blueprint).
11
+ 3. The visual-direction decision is recorded: probes/mocks generated, or skipped with a reason.
12
+
13
+ Project context and the design system do **not** satisfy the brief gate. Invalid skip reasons: "the final UI will be semantic/editable/responsive", "a raster mock won't ship". Probes and mocks are direction artifacts, not implementation assets.
14
+
15
+ ## Step 1 — Shape
16
+
17
+ Run `shape` (see [shape.md](shape.md)) unless the user already has a confirmed brief. Wait for confirmation. Every build decision traces back to the brief.
18
+
19
+ ## Step 2 — Load references & patterns
20
+
21
+ Re-read `design.md` (palette, type scale, component patterns). Open the project's reference implementations for the patterns the brief needs (list rows, section rows, forms, status pills, modals) and the nearest existing route/component — match them rather than inventing.
22
+
23
+ ## Step 3 — Land the visual direction (gated)
24
+
25
+ When the work is net-new/visually open-ended and fidelity is mid-fi+, generate **1–3** high-fidelity north-star comps with `mcp__xevy__generate_image`, building from the winning `shape` probe. Comps must differ in primary direction, look like the product, and (for multi-section surfaces) show the second fold.
26
+
27
+ Show them, ask what carries forward, revise once if weak. Before code, write the **mock fidelity inventory**: the visible ingredients that must survive into code (composition, signature motifs, nav/CTA treatment, section sequence, imagery, density, type/colour/motion cues), and for each, how it's implemented (semantic HTML/CSS/SVG, generated asset, icon set, accepted omission). Treat the mock as a north star, not a screenshot to trace — never rasterise UI text. Skip the whole step with a one-line reason for small/in-place work.
28
+
29
+ ## Step 4 — Build to production quality
30
+
31
+ Implement following the brief and `design.md`, in passes (structure → visual system → states → motion/media → responsive). Definition of done:
32
+
33
+ - Real/realistic content; no placeholder copy, dead links, or fake controls left in.
34
+ - The approved mock's major ingredients are present (missing hero objects, downgraded nav/CTA, generic swaps for distinctive motifs are blocking defects unless the user accepted them).
35
+ - Semantic first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements.
36
+ - Deliberate spacing, alignment, grid, vertical rhythm — no default gaps or optical misalignment.
37
+ - Intentional typography from the project scale; clear hierarchy; no overflow at small or large widths.
38
+ - Full state coverage: default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run.
39
+ - Finished interaction: keyboard paths, touch targets, feedback timing, no hover-only functionality.
40
+ - Icons from the project's set; optimised, alt-texted, responsive imagery; modern formats where practical.
41
+ - Premium, restrained motion that respects reduced-motion; no layout-property animation.
42
+ - Maintainable: reuse local patterns and tokens, clear component boundaries, no one-off hacks, no unjustified `any`, no silent catches.
43
+ - Fits the stack: production build passes, no console errors, no avoidable layout shift, no needless dependency.
44
+
45
+ If a discovery surfaces a question that changes the brief, stop and ask.
46
+
47
+ ## Step 5 — Browser-based iteration (critical)
48
+
49
+ Do not stop after the first pass. View the rendered result, not just the DOM/terminal.
50
+
51
+ - **Xevy apps** are served on a live dev URL (this server: `https://<container>.vyte.dev`) or via a preview deploy. Open it and inspect screenshots; if you can't reach it, ask the user for screenshots.
52
+ - Check at least three viewports: mobile narrow, tablet/small laptop, desktop wide.
53
+
54
+ After the first pass, write a short self-critique and patch. Re-inspect. Repeat until no material issue remains against:
55
+
56
+ 1. Matches the brief (every section).
57
+ 2. Matches the mock fidelity inventory (missing major ingredients are P0).
58
+ 3. Passes the AI-slop test.
59
+ 4. No absolute-ban violations (see SKILL.md).
60
+ 5. Every state is intentional (walk empty/error/loading/edge).
61
+ 6. Responsive: adapts compositionally, doesn't merely shrink.
62
+ 7. Craft details: spacing, optical alignment, hierarchy, contrast, icon coherence, feedback, motion timing, focus rings.
63
+ 8. Performance basics: no oversized images, layout thrash, or blocking animation.
64
+
65
+ Exit bar: intentional at every checked viewport, all states handled, no leftover placeholders, defensible in a studio review.
66
+
67
+ ## Step 6 — Present
68
+
69
+ Show the primary state; summarise viewports checked and the key fixes made after inspection; walk the important states; explain decisions back to the brief and the chosen mock (name any accepted deviations honestly); note remaining risks. Ask: "What's working? What isn't?" Iterate.
@@ -0,0 +1,33 @@
1
+ # critique — heuristic UX/design review
2
+
3
+ Reviews an existing surface against design heuristics and `design.md`, and returns scored, actionable findings. Read-only thinking — it diagnoses; it doesn't rewrite (hand fixes to `polish` or `craft`).
4
+
5
+ ## Inputs
6
+
7
+ The target (route, component, screenshot, or live URL) and the project's `design.md`. View the rendered result where possible (the live dev URL / preview deploy, or ask for screenshots) — critique from pixels, not just code.
8
+
9
+ ## Heuristics
10
+
11
+ Score each 1–5 (5 = excellent) with a one-line justification and a concrete fix:
12
+
13
+ 1. **Match to brief / design.md** — does it honour the project's register, palette, type scale, and patterns?
14
+ 2. **Visual hierarchy** — does the eye land on the primary action first? Is emphasis earned?
15
+ 3. **Information architecture** — is content grouped and ordered the way the user thinks?
16
+ 4. **Cognitive load** — is anything doing too much at once? What can be deferred or removed?
17
+ 5. **Layout & rhythm** — spacing variety, alignment, grid, optical balance; no nested cards or needless containers.
18
+ 6. **Typography** — scale + weight contrast, measure, no one-off sizes, no overflow.
19
+ 7. **Colour & contrast** — strategy honoured, status semantics intact, WCAG AA met.
20
+ 8. **States** — empty, loading, error, success, edge, first-run all designed (not afterthoughts).
21
+ 9. **Interaction & feedback** — keyboard, focus-visible, touch targets, timing, no hover-only.
22
+ 10. **Responsive** — adapts compositionally across viewports.
23
+ 11. **Copy** — concrete, no restated headings, clear errors and labels.
24
+ 12. **AI-slop test** — would someone immediately say "AI made this"? Run the category-reflex check.
25
+
26
+ ## Output
27
+
28
+ - A short verdict line (overall impression + the single highest-leverage fix).
29
+ - A scored table: heuristic → score → fix.
30
+ - **P0 / P1 / P2** ordered findings, each with `file:line` (or screenshot region) evidence and a specific remedy.
31
+ - Flag any absolute-ban violations (see SKILL.md) as automatic P0.
32
+
33
+ Be specific and honest. "Tighten spacing" is useless; "reduce the row gap from 24px to the 12px rhythm used in the list above" is a finding. Don't pad the review with praise.
@@ -0,0 +1,25 @@
1
+ # polish — final craft pass before shipping
2
+
3
+ Takes a working surface to a studio-quality finish. Unlike `critique` (diagnose only), `polish` makes the fixes. Smallest changes that raise quality; match existing patterns and tokens; no behaviour changes.
4
+
5
+ ## Preconditions
6
+
7
+ The surface already works and matches the brief. `design.md` is loaded. View it rendered (live dev URL / preview deploy, or screenshots) before and after.
8
+
9
+ ## Passes
10
+
11
+ Work through these, fixing as you go. Validate against the project's quality gate after changes (e.g. build + lint).
12
+
13
+ 1. **Spacing & rhythm** — snap to the project's spacing scale; vary deliberately; remove default/arbitrary gaps; fix optical misalignment. Kill nested cards and needless containers.
14
+ 2. **Typography** — every size from the project scale; tighten hierarchy via weight/scale contrast; fix wrapping, measure, and overflow at small and large widths; correct tracking on eyebrows/labels.
15
+ 3. **Colour & contrast** — honour the colour strategy; verify status semantics (success/warning/error) and WCAG AA; remove stray accents and any absolute-ban patterns.
16
+ 4. **States** — make empty, loading, error, success, disabled, and edge states feel intentional; align skeletons to the real layout.
17
+ 5. **Interaction & focus** — visible focus rings, adequate touch targets, consistent hover/active feedback and timing; no hover-only functionality.
18
+ 6. **Motion** — restrained, exponential ease-out; no layout-property animation; honour reduced-motion.
19
+ 7. **Responsive** — adapts compositionally across mobile/tablet/desktop, not just shrinking; no clipping/overlap/overflow.
20
+ 8. **Copy & icons** — concrete copy, no restated headings, clear errors; one coherent icon set; consistent sizing.
21
+ 9. **Cleanup** — remove placeholders, dead controls, unused scaffold, console noise, and avoidable layout shift.
22
+
23
+ ## Exit
24
+
25
+ Re-inspect in-browser at the three viewports. The result should read as intentional everywhere, all states handled, quality gate green. Report the most impactful fixes and any remaining limitation honestly — don't claim done without evidence.
@@ -0,0 +1,82 @@
1
+ # setup — author the design system
2
+
3
+ Produces `./.xevy/design.md` and mirrors it to a database Document. Run this once per project (or when the user wants to refresh the system). It is the prerequisite for every other command.
4
+
5
+ ## When to run
6
+
7
+ - `./.xevy/design.md` is missing, empty, or placeholder, **and** no `Design System` Document exists in the project (checked via `list_documents`).
8
+ - The user explicitly asks to (re)establish or document the design system.
9
+
10
+ If a `Design System` Document already exists but the local file doesn't, you don't need a full interview — pull `get_document` `details` into `./.xevy/design.md` (keep the pointer marker) and stop.
11
+
12
+ ## Step 1 — Scan the project
13
+
14
+ Read what the codebase already encodes before asking the user anything:
15
+
16
+ - Design/agent guides: `AGENTS.md`, `CLAUDE.md`, `README`, any `DESIGN.md`/`PRODUCT.md`.
17
+ - Token sources: the global stylesheet (e.g. `index.css` `@theme`), Tailwind config, CSS variables, theme files.
18
+ - 2–3 representative components/routes for real patterns (list rows, buttons, forms, status pills, typography).
19
+
20
+ Capture what's already decided — palette, type families + scale, spacing rhythm, component patterns, light/dark stance, register. Most of the system usually already exists in code; your job is to record it, not reinvent it.
21
+
22
+ ## Step 2 — Interview (only for the gaps)
23
+
24
+ Ask **2–3 questions per round**, then wait. Skip anything Step 1 already answered. Cover:
25
+
26
+ - **Users & JTBD** — who uses this, in what context, to do what.
27
+ - **Register** — brand or product (see SKILL.md).
28
+ - **Personality & aesthetic** — 2–3 named anchor references (real products/brands, not adjectives) and 1–2 anti-references.
29
+ - **Colour strategy** — Restrained / Committed / Full palette / Drenched, plus the theme scene sentence.
30
+ - **Hard constraints** — light/dark mandate, accessibility bar, frameworks, the component patterns that must be reused.
31
+
32
+ Don't fabricate. If the user defers, infer from Step 1 and label the inference.
33
+
34
+ ## Step 3 — Write `./.xevy/design.md`
35
+
36
+ Author a tight, decisions-only document. Suggested structure:
37
+
38
+ ```markdown
39
+ <!-- xevy:document-id: PENDING -->
40
+ # Design System — <Project>
41
+
42
+ ## Register
43
+ product | brand — one line of why.
44
+
45
+ ## Users & JTBD
46
+ Who, context, the job the UI does for them.
47
+
48
+ ## Personality & aesthetic
49
+ Tone in 3 adjectives. Anchor references. Anti-references.
50
+
51
+ ## Colour
52
+ Strategy (Restrained/Committed/Full/Drenched). Theme stance + scene sentence.
53
+ Named roles with OKLCH values: surface, text, primary, borders, status (success/warning/error).
54
+
55
+ ## Typography
56
+ Families + tokens, the type scale (token → size/line-height → use), weight rules, tracking.
57
+
58
+ ## Layout & components
59
+ Spacing rhythm, the canonical patterns to reuse (list rows, section rows, status pills,
60
+ icon buttons, modals), and what NOT to do.
61
+
62
+ ## Motion
63
+ Easing, durations, reduced-motion stance.
64
+
65
+ ## Anti-patterns (project-specific)
66
+ The absolute bans plus any project-specific "must NOT".
67
+ ```
68
+
69
+ Keep it scannable and concrete (numbers, tokens, units), not prose. This is the contract every other command reads.
70
+
71
+ ## Step 4 — Mirror to the database
72
+
73
+ 1. `create_document` with `workspaceIdentifier`, `projectIdentifier`, `title: "Design System"`, `visibility: "shared"`, and `details` = the full design.md body.
74
+ 2. Replace the marker's `PENDING` with the returned document id:
75
+ `<!-- xevy:document-id: <uuid> -->`.
76
+ 3. Confirm to the user: the local path, the Document title/visibility, and (if the doc is later made public) its `publicUrl`.
77
+
78
+ On later edits to `design.md`, `update_document` the pointered id so local and database stay in sync (see SKILL.md sync contract).
79
+
80
+ ## Report
81
+
82
+ State where the system was sourced from (code vs interview), the local path, and the linked Document. Then resume the user's original request (often `shape` or `craft`).
@@ -0,0 +1,40 @@
1
+ # shape — plan the UX/UI before any code
2
+
3
+ Produces a **design brief**: the thinking that makes the code good. This command does NOT write feature code. Most AI UIs fail from skipped thinking, not bad code — understand deeply first.
4
+
5
+ ## Phase 1 — Discovery interview
6
+
7
+ Do not design or code yet. Ask **2–3 questions per round**, then wait. Have a dialogue; don't dump every question. Skip anything `design.md` already answers — it's the anchor, but it does not replace task-specific shaping.
8
+
9
+ - **Purpose & context** — what problem this solves; who specifically uses it (role, frequency); what success looks like; the user's state of mind on arrival.
10
+ - **Content & data** — what it displays/collects; realistic ranges (0 / typical / many); edge cases (empty, error, first-run, power user); what's dynamic.
11
+ - **Direction** — colour strategy for this surface (may override the project default if it earns it); theme scene sentence; 2–3 named anchor references.
12
+ - **Scope** — fidelity (sketch / mid-fi / high-fi / production); breadth (one screen / flow / surface); interactivity; time intent. Scope is task-scoped — don't write it back to design.md.
13
+ - **Anti-goals** — what this must NOT be; the biggest risk of getting it wrong.
14
+
15
+ ## Phase 1.5 — Visual direction probes (gated)
16
+
17
+ Generate probes with `mcp__xevy__generate_image` **before** finalising the brief when all hold: the work is net-new or directionally ambiguous; fidelity is mid-fi or higher; the user has write access to the project.
18
+
19
+ - Generate **2–4** probes that differ in primary direction (hierarchy, density, typographic voice, colour strategy) — not palette tweaks.
20
+ - Base prompts on the discovery answers and `design.md` so probes look like the product, not stock UI.
21
+ - They're stored in the project Gallery and returned as URLs. Show them; ask which is closest, what's off, what carries forward. Revise brief inputs if a probe reveals a mismatch.
22
+ - Probes are direction tests, not specs. Don't treat them as final copy/UX/a11y.
23
+
24
+ Skip with a one-line reason for sketch-only work, pure refinements, or when generation is unavailable, then proceed.
25
+
26
+ ## Phase 2 — The design brief
27
+
28
+ Synthesise into a structured brief and present it for **explicit confirmation**. Stop after asking; don't roll into implementation in the same turn unless already approved.
29
+
30
+ 1. **Feature summary** (2–3 sentences) — what, who, the goal.
31
+ 2. **Primary user action** — the single most important thing the user does/understands.
32
+ 3. **Design direction** — colour strategy + theme scene sentence + anchor references; note which probe won and what changed.
33
+ 4. **Scope** — fidelity / breadth / interactivity / time intent.
34
+ 5. **Layout strategy** — what gets emphasis, what's secondary, how information flows (hierarchy & rhythm, not CSS).
35
+ 6. **Key states** — default, empty, loading, error, success, edge cases; what the user sees/feels in each.
36
+ 7. **Interaction model** — click/hover/scroll behaviour, feedback, entry-to-completion flow.
37
+ 8. **Content requirements** — copy, labels, empty/error messages, microcopy, dynamic ranges.
38
+ 9. **Open questions** — anything the build must resolve.
39
+
40
+ A shape run is incomplete until the brief is confirmed. On disagreement, revisit the relevant discovery questions. Once confirmed, hand to `craft` or to a freeform build.