@xevy/skills 0.1.24 → 0.1.28
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 +23 -11
- package/bin/cli.mjs +145 -10
- package/bin/xevy-mcp-bridge.mjs +346 -0
- package/package.json +2 -2
- package/skills/analyze/SKILL.md +53 -15
- package/skills/execute/SKILL.md +59 -19
- package/skills/fix/SKILL.md +47 -15
- package/skills/generate-image/SKILL.md +46 -22
- package/skills/investigate/SKILL.md +1 -1
- package/skills/merge/SKILL.md +45 -13
- package/skills/move-to-qa/SKILL.md +45 -11
- package/skills/plan/SKILL.md +53 -14
- package/skills/xevy-setup/SKILL.md +5 -4
- package/skills/analyze-here/SKILL.md +0 -30
- package/skills/execute-here/SKILL.md +0 -36
- package/skills/fix-here/SKILL.md +0 -23
- package/skills/merge-here/SKILL.md +0 -22
- package/skills/move-to-qa-here/SKILL.md +0 -21
- package/skills/plan-here/SKILL.md +0 -26
|
@@ -10,11 +10,12 @@ allowed-tools: "Read Write Edit Bash mcp__xevy__get_current_user mcp__xevy__list
|
|
|
10
10
|
|
|
11
11
|
Bootstrap the Xevy integration for the current git repository. Work locally with the host coding agent's tools and use the Xevy MCP for all server state. Clients may display a tool as `xevy.get_current_user`, `mcp__xevy__get_current_user`, or a similar namespaced form; the short tool names below refer to that same Xevy MCP. An optional skill argument may pre-fill `workspace/project`.
|
|
12
12
|
|
|
13
|
-
## 0. Preconditions — MCP connection
|
|
13
|
+
## 0. Preconditions — MCP connection
|
|
14
14
|
If MCP is not configured yet, run `npx @xevy/skills` from the repo root first.
|
|
15
|
-
|
|
15
|
+
Codex uses the local API-key MCP bridge installed by `xevy setup`; Claude Code,
|
|
16
|
+
Cursor, and other remote MCP clients use OAuth.
|
|
16
17
|
- Call `get_current_user` to confirm the connection works.
|
|
17
|
-
- If it
|
|
18
|
+
- If it fails authentication, stop and give the recovery step for the active client: Codex → run `xevy setup --component credentials --component mcp --agent codex`, then restart Codex or start a new session; Claude Code → run `/mcp`, select `xevy`, and authenticate; Cursor → Settings → MCP → `xevy` → Connect; another client → use its MCP connect/OAuth action for `xevy`, then restart or reload that client if required. Re-run `get_current_user` after authentication. To target a non-default host, pass `--base <url>` while reinstalling the MCP configuration, then restart the client. Do not proceed until the call succeeds.
|
|
18
19
|
|
|
19
20
|
## 0.5. Agent skills (optional but recommended)
|
|
20
21
|
- Run `npx @xevy/skills check` from the repo root. If an update is available, run `npx @xevy/skills update -y` (refreshes SDLC skills; MCP tools stay live on the server).
|
|
@@ -47,7 +48,7 @@ The Xevy MCP server authenticates via **OAuth** when configured (run `npx @xevy/
|
|
|
47
48
|
- Copy any **missing** env keys from the local `.env` into the project's deploy config by running the bundled helper — it reads the file in-process and prints only key names:
|
|
48
49
|
`npx @xevy/skills sync-env --workspace <ws> --project <proj>`
|
|
49
50
|
- NEVER `cat`/read/print `.env` or any env values yourself. The helper adds only keys not already configured and never overwrites existing values. If there is no `.env`, skip this step.
|
|
50
|
-
- Auth note: the env-sync and repo-link helpers call the REST API
|
|
51
|
+
- Auth note: the env-sync and repo-link helpers call the REST API and read an API key from `~/.config/xevy/credentials` (or `XEVY_API_KEY`). Codex's local MCP bridge reads the same credential; remote MCP clients use OAuth. If none is present, tell the user to run `xevy setup --component credentials`.
|
|
51
52
|
|
|
52
53
|
## 6. Bootstrap structure
|
|
53
54
|
- Read `get_project_workbreakdown`. Only when the project has no categories, create 3–6 user/product-area categories (never technical-layer categories such as Frontend or API) and 1–3 starter epics per category for already-present capabilities. If categories exist, skip this step. Never create tasks.
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: analyze-here
|
|
3
|
-
description: Analyze a task locally in the current coding-agent session — inspect the codebase, write the Analysis section + storyPoints via MCP, then self-review. Cloud equivalent is the analyze skill.
|
|
4
|
-
argument-hint: "[task]"
|
|
5
|
-
disable-model-invocation: true
|
|
6
|
-
allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_specs mcp__xevy__list_subtasks mcp__xevy__create_task_note mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision"
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# /xevy:analyze-here — analyze locally (then review)
|
|
10
|
-
|
|
11
|
-
Run the analysis yourself in this session (no server agent). Mirror the Xevy analyze workflow.
|
|
12
|
-
|
|
13
|
-
## 1. Resolve the task
|
|
14
|
-
Resolve from `$ARGUMENTS` or context (`mcp__xevy__find_task` / `find_task`). Read existing specs, subtasks, and notes.
|
|
15
|
-
|
|
16
|
-
## 1b. Decisions gate (BEFORE the work)
|
|
17
|
-
Call `mcp__xevy__list_task_decisions`. If any decision is **open**, resolve them first — open decisions block AI actions. Present each open question through the host's user-question mechanism (using its preset choices + explanations), record the answer with `mcp__xevy__answer_decision`, and fold the answers into the analysis. Never guess or bypass an open decision.
|
|
18
|
-
|
|
19
|
-
## 2. Inspect the codebase
|
|
20
|
-
Read the relevant files (callers, callees, similar patterns). Identify whether the task involves UI changes; if so, study existing UI patterns and record a `UI/UX Flow` note (`create_task_note`). Base decisions on existing patterns — don't ask about every detail.
|
|
21
|
-
|
|
22
|
-
## 3. Write the Analysis
|
|
23
|
-
Use `mcp__xevy__update_task` to append a `## Analysis` section (do NOT replace the user's original request):
|
|
24
|
-
- **Overview:** plain-language summary, before/after behaviour, user impact, key decisions.
|
|
25
|
-
- **Technical Implementation:** affected files/modules, API/data/UI changes, assumptions, risks, verification approach.
|
|
26
|
-
- Estimate `storyPoints` (1 trivial · 2 small · 3 medium · 5 large · 8 XL · 13 epic) and set it.
|
|
27
|
-
- **Open questions:** for a genuine ambiguity a human must resolve, don't bury it as an assumption — record it with `mcp__xevy__create_decision` (preset choices + explanation, optional follow-up per choice). It will gate the next step until answered. If the user is present, use the host's user-question mechanism and persist the result with `create_decision` + `answer_decision`.
|
|
28
|
-
|
|
29
|
-
## 4. Review & correct (MANDATORY)
|
|
30
|
-
Re-read your Analysis against the actual code: is every claim accurate, are affected files real, are risks/ACs concrete? Fix any gap or inaccuracy before finishing. Then call `mcp__xevy__list_task_decisions` once more (post-check): if any decision is still open, surface it to the user. Report a PASS/PARTIAL verdict, what you corrected, any open decisions, and the task URL. Do not push the user to plan/execute next.
|
|
@@ -1,36 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: execute-here
|
|
3
|
-
description: Execute a task locally in the current coding-agent session — worktree, implement against the plan, run tests, commit, push, open a PR, deploy a preview, then review/correct. Cloud equivalent is the execute skill.
|
|
4
|
-
argument-hint: "[task]"
|
|
5
|
-
disable-model-invocation: true
|
|
6
|
-
allowed-tools: "Read Grep Edit Write Bash Agent mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__update_task_status mcp__xevy__list_specs mcp__xevy__list_subtasks mcp__xevy__update_subtask mcp__xevy__list_sprints mcp__xevy__assign_task_to_sprint mcp__xevy__deploy_preview mcp__xevy__get_deploy_status mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision set_session_task_lock"
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# /xevy:execute-here — implement locally (then review + deploy)
|
|
10
|
-
|
|
11
|
-
You are the engine: implement the task in this session, following the Xevy worktree + git protocol.
|
|
12
|
-
|
|
13
|
-
## 1. Resolve + gates
|
|
14
|
-
- Resolve the task (`$ARGUMENTS` / context). Read its `## Analysis`, plan spec, and subtasks. If none and non-trivial, suggest `/xevy:plan-here` or ask whether to plan-and-execute or execute directly.
|
|
15
|
-
- **Decisions gate (BEFORE implementing):** call `mcp__xevy__list_task_decisions`. If any decision is **open**, resolve it first — open decisions block execution. Present each through the host's user-question mechanism, record with `mcp__xevy__answer_decision`, and fold the answer into the work (if a relevant subtask is already done, the answer may warrant a new subtask). Never guess or bypass.
|
|
16
|
-
- Sprint gate: same as cloud — if an active sprint exists and the task isn't on it, require `## Analysis` + `storyPoints` > 0 then `assign_task_to_sprint`, else stop and ask.
|
|
17
|
-
|
|
18
|
-
## 2. Worktree protocol
|
|
19
|
-
- Record the current branch + dir. Derive a canonical branch `xevy/<TASK-ID>-<slug>` (task id = task code, or first 8 chars of task UUID; reuse if one already exists for this task — never create a second branch per task).
|
|
20
|
-
- Create/attach a git worktree in a sibling dir and `cd` into it; if resuming, first merge the latest source branch (e.g. `git merge origin/main`). Do ALL work in the worktree.
|
|
21
|
-
- In Pi, call `set_session_task_lock(taskCode, taskId, taskTitle, worktreePath, branch)` immediately after attaching the worktree, using its absolute `git rev-parse --show-toplevel` path. If that tool is unavailable, continue—the worktree rules still apply.
|
|
22
|
-
- NEVER commit/push on a protected branch (master/main/develop/staging) — only on `xevy/*` task branches.
|
|
23
|
-
|
|
24
|
-
## 3. Implement
|
|
25
|
-
- Move the task to `in_progress` (`update_task_status`) when implementation begins — mirrors the cloud `execute`, which flips to `in_progress` at start (and to `for_review` on success).
|
|
26
|
-
- Work the subtasks in order with the host's read/search/edit tools. When supported and useful, dispatch builder/frontend subagents with the worktree as their working directory. Keep changes surgical, match existing style, and update subtask status via MCP as you go.
|
|
27
|
-
- **Frontend/UI changes:** before editing any UI (pages, components, app shell, forms, styling), follow the `/xevy:xevy-design` skill so the change matches the project design system (`./.xevy/design.md`).
|
|
28
|
-
- If you hit a genuine ambiguity a human must resolve mid-implementation, raise it with `mcp__xevy__create_decision` (preset choices) rather than guessing — or, if the user is present, use the host's user-question mechanism and persist with `create_decision` + `answer_decision`. Open decisions block further AI steps until answered.
|
|
29
|
-
- Validate after each step (type-check → lint → targeted tests).
|
|
30
|
-
|
|
31
|
-
## 4. Review & correct (MANDATORY)
|
|
32
|
-
- Run the full project checks. Trace every requirement to code and check "must NOT" constraints. When the host supports subagents, dispatch a **reviewer** for an independent PASS/PARTIAL/FAIL with file:line evidence; otherwise perform a separate review pass yourself. Fix everything it flags and re-run until green.
|
|
33
|
-
|
|
34
|
-
## 5. Push, PR, deploy
|
|
35
|
-
- Commit + push the task branch. Open/refresh the PR and ALWAYS give the user the PR/compare link. Do NOT merge automatically.
|
|
36
|
-
- Record the branch on the task (`update_task` metadata `aiPullRequest.branch`) so deploys resolve it, then `mcp__xevy__deploy_preview({ taskId, branch })`; report the URL. Move status to `for_review` (`update_task_status`).
|
package/skills/fix-here/SKILL.md
DELETED
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: fix-here
|
|
3
|
-
description: Apply a fix/rework to a task locally in the current coding-agent session — reuse the task worktree, rework, run tests, push, refresh the PR, redeploy preview, then review. Cloud equivalent is the fix skill.
|
|
4
|
-
argument-hint: "[task]"
|
|
5
|
-
disable-model-invocation: true
|
|
6
|
-
allowed-tools: "Read Grep Edit Write Bash Agent mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_subtasks mcp__xevy__update_subtask mcp__xevy__deploy_preview mcp__xevy__get_deploy_status"
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# /xevy:fix-here — fix locally (then review + redeploy)
|
|
10
|
-
|
|
11
|
-
## 1. Resolve + locate worktree
|
|
12
|
-
Resolve the task (`$ARGUMENTS` / context). Find the EXISTING worktree/branch for it (`git worktree list`, match by task code). The worktree MUST already exist — do not create a new branch; if none, stop and ask. Merge the latest source branch into the feature branch first to avoid divergence.
|
|
13
|
-
|
|
14
|
-
## 2. Rework
|
|
15
|
-
Make the requested fix in the worktree with the host's read/search/edit tools, or use a builder subagent with the worktree as its working directory when the host supports one. Keep it surgical; root-cause the issue rather than patching symptoms. Update subtasks via MCP.
|
|
16
|
-
|
|
17
|
-
## 3. Review & correct (MANDATORY)
|
|
18
|
-
Run the full project checks. Verify the fix resolves the issue with no regressions and check "must NOT" constraints. When supported, dispatch a **reviewer** subagent (PASS/PARTIAL/FAIL + file:line); otherwise perform a separate review pass yourself. Fix anything flagged and re-run until green.
|
|
19
|
-
|
|
20
|
-
**Frontend/UI changes:** before editing any UI (pages, components, app shell, forms, styling), follow the `/xevy:xevy-design` skill so the change matches the project design system (`./.xevy/design.md`).
|
|
21
|
-
|
|
22
|
-
## 4. Push, PR, deploy
|
|
23
|
-
Commit + push the feature branch; refresh the PR and give the user the link. Do NOT merge automatically. Then `mcp__xevy__deploy_preview({ taskId, branch })`; report the URL. Ask whether to merge back via `/xevy:merge` — don't merge on your own.
|
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: merge-here
|
|
3
|
-
description: Merge a task's branch locally in the current coding-agent session — merge the feature branch into the current branch for review (no push), run tests, resolve conflicts, then review. Cloud equivalent is the merge skill.
|
|
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.
|
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: move-to-qa-here
|
|
3
|
-
description: Move a task to QA locally in the current coding-agent session — write/update non-technical, UI-verifiable QA Notes, set status for_qa, then review. Cloud equivalent is the move-to-qa skill.
|
|
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.
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: plan-here
|
|
3
|
-
description: Plan a task locally in the current coding-agent session — dispatch scout + plan-reviewer subagents when supported, write the plan spec + ordered subtasks via MCP, then review. Cloud equivalent is the plan skill.
|
|
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 mcp__xevy__get_process_owners mcp__xevy__update_task_status"
|
|
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 (otherwise suggest the `analyze-here` skill). **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 through the host's user-question mechanism, record with `mcp__xevy__answer_decision`, and reflect it in the plan. When the host supports subagents, dispatch a **scout** for codebase recon — relevant files, callers/callees, similar patterns, baseline health. Otherwise perform the same recon in the current session.
|
|
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
|
-
When the host supports subagents, dispatch a **plan-reviewer** to cross-check every matrix item vs requirements (no orphans/gaps), verify cross-flow risks and "must NOT" constraints are covered, and confirm tests hit the exact branches. Otherwise perform a separate self-review pass with the same checks. Fold the 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. Do not change task status as a side effect of local planning. Draft is preparation-only; the user explicitly submits it to Ready. When planning is performed as the configured Refine work for a Ready task, completion moves it to Planned through the normal server-owned Process Owner flow. Do not start execution as part of local planning. Report a PASS/PARTIAL verdict, the matrix summary, any open decisions, the resulting status, and the task URL.
|