@xevy/skills 0.1.23 → 0.1.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,7 +2,7 @@
2
2
  "name": "xevy",
3
3
  "displayName": "Xevy",
4
4
  "description": "Native /xevy:* SDLC workflow commands driven through the Xevy MCP server. Cloud (server Web Agent) by default; '-here' variants run locally in this Claude Code session. Claude reviews and corrects the result after every action.",
5
- "version": "0.1.23",
5
+ "version": "0.1.25",
6
6
  "author": {
7
7
  "name": "Xevy"
8
8
  },
package/README.md CHANGED
@@ -5,7 +5,8 @@ Install **Xevy SDLC agent skills** and the **Xevy MCP server** for Cursor, Claud
5
5
  This package wraps:
6
6
 
7
7
  - [`npx skills`](https://github.com/vercel-labs/skills) — copies skills into `.cursor/skills/`, `.claude/skills/`, etc.
8
- - [`npx add-mcp`](https://github.com/neondatabase/add-mcp) — writes `.cursor/mcp.json`, `.mcp.json`, and other agent MCP configs
8
+ - [`npx add-mcp`](https://github.com/neondatabase/add-mcp) — writes remote OAuth MCP configs for Cursor, Claude Code, and other clients
9
+ - `codex mcp add` — registers the bundled local API-key bridge for Codex
9
10
 
10
11
  The skill files under [`skills/`](skills/) are the source of truth — edit them there directly.
11
12
 
@@ -47,8 +48,9 @@ XEVY_BASE=https://your-xevy-host.example.com npx @xevy/skills -y
47
48
 
48
49
  Then:
49
50
 
50
- 1. **OAuth** — Authorize `xevy` in every installed client:
51
- - **Codex:** `codex mcp login xevy`, then restart Codex or start a new session.
51
+ 1. **Authentication**:
52
+ - **Codex:** the installer configures a local stdio bridge that reads the API key
53
+ stored by `xevy setup`; restart Codex or start a new session. No OAuth login is needed.
52
54
  - **Claude Code:** run `/mcp`, select `xevy`, and complete authentication.
53
55
  - **Cursor:** Settings → MCP → `xevy` → Connect.
54
56
  - **Other clients:** use the client's MCP connect/OAuth action for `xevy`.
@@ -88,10 +90,16 @@ npx skills add ./node_modules/@xevy/skills -y
88
90
 
89
91
  ### Install MCP manually
90
92
 
93
+ For remote OAuth clients:
94
+
91
95
  ```bash
92
- npx add-mcp https://xevy.ai/mcp -n xevy -a cursor -a claude-code -a codex -y
96
+ npx add-mcp https://xevy.ai/mcp -n xevy -a cursor -a claude-code -y
93
97
  ```
94
98
 
99
+ For Codex, use `xevy setup --component credentials --component mcp --agent codex`.
100
+ This installs the bundled local bridge at a stable user path and registers it
101
+ with `codex mcp add`.
102
+
95
103
  ## Included skills
96
104
 
97
105
  | Skill | Purpose |
@@ -109,7 +117,9 @@ npx add-mcp https://xevy.ai/mcp -n xevy -a cursor -a claude-code -a codex -y
109
117
 
110
118
  ## Security
111
119
 
112
- - **MCP** uses OAuth in supported clients — no API key in the MCP URL.
120
+ - **Codex MCP** uses a local bridge and the mode-`600` API key stored by
121
+ `xevy setup`; the key is never placed in MCP arguments, URLs, or output.
122
+ - **Remote MCP clients** use OAuth — no API key in the MCP URL.
113
123
  - **REST helpers** (`sync-env`, `link-repo`) read `~/.config/xevy/credentials` or `XEVY_API_KEY`.
114
124
  - Env values are never printed; sync-env only reports key names.
115
125
 
package/bin/cli.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * @xevy/skills — install Xevy skills (npx skills) + MCP (npx add-mcp).
3
+ * @xevy/skills — install Xevy skills and per-agent MCP transports.
4
4
  *
5
5
  * Usage:
6
6
  * npx @xevy/skills # install skills + MCP (default)
@@ -10,6 +10,8 @@
10
10
  * npx @xevy/skills mcp # MCP only
11
11
  */
12
12
  import { spawnSync } from "node:child_process";
13
+ import fs from "node:fs";
14
+ import os from "node:os";
13
15
  import path from "node:path";
14
16
  import { fileURLToPath } from "node:url";
15
17
  import {
@@ -154,6 +156,7 @@ function parseArgv(argv) {
154
156
 
155
157
  if (opts.agents.length === 0) opts.agents = [...DEFAULT_AGENTS];
156
158
  opts.agents = [...new Set(opts.agents)];
159
+ validateBaseUrl(opts.base);
157
160
  return opts;
158
161
  }
159
162
 
@@ -162,6 +165,19 @@ function die(msg) {
162
165
  process.exit(1);
163
166
  }
164
167
 
168
+ function validateBaseUrl(base) {
169
+ let parsed;
170
+ try {
171
+ parsed = new URL(base);
172
+ } catch {
173
+ die(`Invalid Xevy base URL: ${base}`);
174
+ }
175
+ const local = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
176
+ if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
177
+ die("The Xevy base URL must use HTTPS (HTTP is allowed only for localhost).");
178
+ }
179
+ }
180
+
165
181
  const isWindows = process.platform === "win32";
166
182
 
167
183
  function quoteArg(a) {
@@ -171,7 +187,8 @@ function quoteArg(a) {
171
187
  function run(cmd, args, { label } = {}) {
172
188
  const title = label || [cmd, ...args].join(" ");
173
189
  console.log(`→ ${title}`);
174
- const command = isWindows && cmd === "npx" ? "npx.cmd" : cmd;
190
+ const command =
191
+ isWindows && (cmd === "npx" || cmd === "codex") ? `${cmd}.cmd` : cmd;
175
192
  const finalArgs = isWindows ? args.map(quoteArg) : args;
176
193
  const r = spawnSync(command, finalArgs, { stdio: "inherit", shell: isWindows, env: process.env });
177
194
  if (r.error) die(r.error.message);
@@ -179,6 +196,17 @@ function run(cmd, args, { label } = {}) {
179
196
  return r;
180
197
  }
181
198
 
199
+ function runOptional(cmd, args) {
200
+ const command =
201
+ isWindows && (cmd === "npx" || cmd === "codex") ? `${cmd}.cmd` : cmd;
202
+ const finalArgs = isWindows ? args.map(quoteArg) : args;
203
+ return spawnSync(command, finalArgs, {
204
+ stdio: "ignore",
205
+ shell: isWindows,
206
+ env: process.env,
207
+ });
208
+ }
209
+
182
210
  function installSkills(opts, skillsRoot = pkgRoot) {
183
211
  const skillArgs = ["--yes", "skills", "add", skillsRoot];
184
212
  if (opts.global) skillArgs.push("-g");
@@ -195,11 +223,66 @@ function installSkills(opts, skillsRoot = pkgRoot) {
195
223
 
196
224
  function installMcp(opts) {
197
225
  const mcpUrl = `${opts.base}/mcp`;
198
- const mcpArgs = ["--yes", "add-mcp", mcpUrl, "-n", "xevy"];
199
- if (opts.global) mcpArgs.push("-g");
200
- if (opts.yes) mcpArgs.push("-y");
201
- for (const a of opts.agents) mcpArgs.push("-a", a);
202
- run("npx", mcpArgs, { label: `npx add-mcp ${mcpUrl}` });
226
+ const remoteAgents = opts.agents.filter((agent) => agent !== "codex");
227
+
228
+ if (remoteAgents.length > 0) {
229
+ const mcpArgs = ["--yes", "add-mcp", mcpUrl, "-n", "xevy"];
230
+ if (opts.global) mcpArgs.push("-g");
231
+ if (opts.yes) mcpArgs.push("-y");
232
+ for (const agent of remoteAgents) mcpArgs.push("-a", agent);
233
+ run("npx", mcpArgs, { label: `npx add-mcp ${mcpUrl}` });
234
+ }
235
+
236
+ if (opts.agents.includes("codex")) {
237
+ installCodexMcp(opts);
238
+ }
239
+ }
240
+
241
+ function installBridge() {
242
+ const configRoot =
243
+ process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
244
+ const bridgeDir = path.join(configRoot, "xevy", "bin");
245
+ const source = path.join(pkgRoot, "bin", "xevy-mcp-bridge.mjs");
246
+ const destination = path.join(bridgeDir, "xevy-mcp-bridge.mjs");
247
+ const temporary = path.join(
248
+ bridgeDir,
249
+ `.xevy-mcp-bridge.${process.pid}.${Date.now()}.tmp`,
250
+ );
251
+
252
+ fs.mkdirSync(bridgeDir, { recursive: true });
253
+ try {
254
+ fs.copyFileSync(source, temporary);
255
+ fs.chmodSync(temporary, 0o700);
256
+ fs.renameSync(temporary, destination);
257
+ } finally {
258
+ try {
259
+ fs.unlinkSync(temporary);
260
+ } catch {
261
+ // The rename normally removes the temporary path.
262
+ }
263
+ }
264
+ return destination;
265
+ }
266
+
267
+ function installCodexMcp(opts) {
268
+ const bridge = installBridge();
269
+ // `mcp add` rejects duplicate names. Remove an old OAuth URL or bridge
270
+ // definition first, then atomically add the current stable bridge command.
271
+ runOptional("codex", ["mcp", "remove", "xevy"]);
272
+ run(
273
+ "codex",
274
+ [
275
+ "mcp",
276
+ "add",
277
+ "xevy",
278
+ "--",
279
+ process.execPath,
280
+ bridge,
281
+ "--base",
282
+ opts.base,
283
+ ],
284
+ { label: "codex mcp add xevy (local API-key bridge)" },
285
+ );
203
286
  }
204
287
 
205
288
  function recordInstallStamp(opts, version) {
@@ -220,10 +303,14 @@ function missingAgents(installedAgents, requestedAgents) {
220
303
  }
221
304
 
222
305
  function printOAuthInstructions(opts) {
223
- console.log(" • Authorize Xevy in each installed MCP client before using its tools:");
224
306
  if (opts.agents.includes("codex")) {
225
- console.log(" Codex: run `codex mcp login xevy`, then restart Codex or start a new session.");
307
+ console.log(
308
+ " • Codex uses the local Xevy bridge and your stored API key; restart Codex or start a new session.",
309
+ );
226
310
  }
311
+ const oauthAgents = opts.agents.filter((agent) => agent !== "codex");
312
+ if (oauthAgents.length === 0) return;
313
+ console.log(" • Authorize Xevy in each remote MCP client before using its tools:");
227
314
  if (opts.agents.includes("claude-code")) {
228
315
  console.log(" Claude Code: run `/mcp`, select `xevy`, and complete authentication.");
229
316
  }
@@ -231,7 +318,7 @@ function printOAuthInstructions(opts) {
231
318
  console.log(" Cursor: open Settings → MCP → `xevy` and choose Connect.");
232
319
  }
233
320
  const otherAgents = opts.agents.filter(
234
- (agent) => !DEFAULT_AGENTS.includes(agent),
321
+ (agent) => agent !== "codex" && !DEFAULT_AGENTS.includes(agent),
235
322
  );
236
323
  if (otherAgents.length > 0) {
237
324
  console.log(
@@ -0,0 +1,346 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Local stdio → Streamable HTTP bridge for Codex.
4
+ *
5
+ * Codex owns only the local stdio transport. The bridge reads the existing
6
+ * Xevy API key from ~/.config/xevy/credentials and authenticates upstream
7
+ * requests itself, avoiding Codex's cross-process OAuth refresh-token cache.
8
+ *
9
+ * stdout is reserved for newline-delimited JSON-RPC messages. Diagnostics go
10
+ * to stderr and never include credentials or upstream response bodies.
11
+ */
12
+ import fs from "node:fs";
13
+ import os from "node:os";
14
+ import path from "node:path";
15
+ import readline from "node:readline";
16
+
17
+ const DEFAULT_BASE = "https://xevy.ai";
18
+ const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
19
+ const API_KEY_PREFIX = "xevy_pk_";
20
+ const REQUEST_TIMEOUT_MS = 300_000;
21
+
22
+ function fail(message) {
23
+ process.stderr.write(`xevy-mcp: ${message}\n`);
24
+ process.exit(1);
25
+ }
26
+
27
+ function parseArgs(argv) {
28
+ let base = null;
29
+ for (let index = 0; index < argv.length; index += 1) {
30
+ const arg = argv[index];
31
+ if (arg === "--base") {
32
+ const value = argv[index + 1];
33
+ if (!value) fail("Missing value for --base");
34
+ base = value;
35
+ index += 1;
36
+ continue;
37
+ }
38
+ if (arg === "-h" || arg === "--help") {
39
+ process.stderr.write(
40
+ "Usage: node xevy-mcp-bridge.mjs [--base https://xevy.ai]\n",
41
+ );
42
+ process.exit(0);
43
+ }
44
+ fail(`Unknown option: ${arg}`);
45
+ }
46
+ return { base };
47
+ }
48
+
49
+ function credentialsPath() {
50
+ const configRoot =
51
+ process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
52
+ return path.join(configRoot, "xevy", "credentials");
53
+ }
54
+
55
+ function readCredentials(baseOverride) {
56
+ const file = credentialsPath();
57
+ let source;
58
+ try {
59
+ source = fs.readFileSync(file, "utf-8");
60
+ } catch {
61
+ fail(
62
+ `Xevy credentials not found at ${file}. Run \`xevy setup --component credentials\`.`,
63
+ );
64
+ }
65
+
66
+ let token = "";
67
+ let storedBase = "";
68
+ for (const line of source.split(/\r?\n/)) {
69
+ const trimmed = line.trim();
70
+ if (trimmed.startsWith("token=")) {
71
+ token = trimmed.slice("token=".length).trim();
72
+ } else if (trimmed.startsWith("baseUrl=")) {
73
+ storedBase = trimmed.slice("baseUrl=".length).trim();
74
+ }
75
+ }
76
+
77
+ if (!token.startsWith(API_KEY_PREFIX)) {
78
+ fail(
79
+ `A Xevy API key is required in ${file}. Run \`xevy setup --component credentials\`.`,
80
+ );
81
+ }
82
+
83
+ const base = String(
84
+ baseOverride || storedBase || process.env.XEVY_BASE || DEFAULT_BASE,
85
+ ).replace(/\/+$/, "");
86
+ let parsed;
87
+ try {
88
+ parsed = new URL(base);
89
+ } catch {
90
+ fail("The configured Xevy base URL is invalid");
91
+ }
92
+ const local = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
93
+ if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
94
+ fail("The Xevy base URL must use HTTPS (HTTP is allowed only for localhost)");
95
+ }
96
+
97
+ return { base, token };
98
+ }
99
+
100
+ function parseJsonRpcMessages(text, contentType) {
101
+ const trimmed = text.trim();
102
+ if (!trimmed) return [];
103
+
104
+ if (contentType.toLowerCase().includes("text/event-stream")) {
105
+ const messages = [];
106
+ for (const line of trimmed.split(/\r?\n/)) {
107
+ if (!line.startsWith("data:")) continue;
108
+ const data = line.slice("data:".length).trim();
109
+ if (!data || data === "[DONE]") continue;
110
+ try {
111
+ const parsed = JSON.parse(data);
112
+ if (Array.isArray(parsed)) messages.push(...parsed);
113
+ else messages.push(parsed);
114
+ } catch {
115
+ // Ignore non-JSON SSE keepalives or event metadata.
116
+ }
117
+ }
118
+ return messages;
119
+ }
120
+
121
+ try {
122
+ const parsed = JSON.parse(trimmed);
123
+ return Array.isArray(parsed) ? parsed : [parsed];
124
+ } catch {
125
+ return [];
126
+ }
127
+ }
128
+
129
+ function writeMessage(message) {
130
+ process.stdout.write(`${JSON.stringify(message)}\n`);
131
+ }
132
+
133
+ function requestId(message) {
134
+ if (!message || typeof message !== "object") return undefined;
135
+ return Object.hasOwn(message, "id") ? message.id : undefined;
136
+ }
137
+
138
+ const opts = parseArgs(process.argv.slice(2));
139
+ const credentials = readCredentials(opts.base);
140
+ const endpoint = new URL("/mcp", `${credentials.base}/`).toString();
141
+
142
+ let sessionId = null;
143
+ let protocolVersion = DEFAULT_PROTOCOL_VERSION;
144
+ let initializeMessage = null;
145
+ let initialized = false;
146
+ let recovering = null;
147
+
148
+ function headers() {
149
+ const result = {
150
+ Authorization: `Bearer ${credentials.token}`,
151
+ Accept: "application/json, text/event-stream",
152
+ "Content-Type": "application/json",
153
+ "MCP-Protocol-Version": protocolVersion,
154
+ };
155
+ if (sessionId) result["Mcp-Session-Id"] = sessionId;
156
+ return result;
157
+ }
158
+
159
+ function syntheticError(message, status, detail) {
160
+ const id = requestId(message);
161
+ if (id === undefined) return null;
162
+ return {
163
+ jsonrpc: "2.0",
164
+ id,
165
+ error: {
166
+ code: status === 401 ? -32001 : -32000,
167
+ message:
168
+ status === 401
169
+ ? "Xevy authentication failed. Run `xevy setup --component credentials`."
170
+ : detail,
171
+ },
172
+ };
173
+ }
174
+
175
+ async function recoverSession() {
176
+ if (recovering) return recovering;
177
+ if (!initializeMessage) {
178
+ throw new Error("upstream MCP session expired before initialization");
179
+ }
180
+
181
+ recovering = (async () => {
182
+ sessionId = null;
183
+ const init = await postUpstream(initializeMessage, {
184
+ forward: false,
185
+ allowRecovery: false,
186
+ });
187
+ if (!init.ok) throw new Error("upstream MCP reinitialization failed");
188
+
189
+ if (initialized) {
190
+ const notification = {
191
+ jsonrpc: "2.0",
192
+ method: "notifications/initialized",
193
+ };
194
+ const ready = await postUpstream(notification, {
195
+ forward: false,
196
+ allowRecovery: false,
197
+ });
198
+ if (!ready.ok) {
199
+ throw new Error("upstream MCP initialization notification failed");
200
+ }
201
+ }
202
+ })().finally(() => {
203
+ recovering = null;
204
+ });
205
+
206
+ return recovering;
207
+ }
208
+
209
+ async function postUpstream(
210
+ message,
211
+ { forward = true, allowRecovery = true } = {},
212
+ ) {
213
+ let response;
214
+ try {
215
+ response = await fetch(endpoint, {
216
+ method: "POST",
217
+ headers: headers(),
218
+ body: JSON.stringify(message),
219
+ signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
220
+ });
221
+ } catch {
222
+ const error = syntheticError(
223
+ message,
224
+ 0,
225
+ "Could not reach the Xevy MCP server",
226
+ );
227
+ if (forward && error) writeMessage(error);
228
+ return { ok: false, status: 0, messages: [] };
229
+ }
230
+
231
+ const returnedSessionId = response.headers.get("mcp-session-id");
232
+ if (returnedSessionId) sessionId = returnedSessionId;
233
+
234
+ const text = await response.text();
235
+ const messages = parseJsonRpcMessages(
236
+ text,
237
+ response.headers.get("content-type") || "",
238
+ );
239
+ const sessionExpired =
240
+ response.status === 404 ||
241
+ messages.some(
242
+ (entry) =>
243
+ entry &&
244
+ typeof entry === "object" &&
245
+ entry.error &&
246
+ typeof entry.error === "object" &&
247
+ entry.error.code === -32001,
248
+ );
249
+
250
+ if (
251
+ allowRecovery &&
252
+ sessionExpired &&
253
+ initializeMessage &&
254
+ message?.method !== "initialize"
255
+ ) {
256
+ try {
257
+ await recoverSession();
258
+ return postUpstream(message, { forward, allowRecovery: false });
259
+ } catch {
260
+ const error = syntheticError(
261
+ message,
262
+ response.status,
263
+ "The Xevy MCP session expired and could not be reinitialized",
264
+ );
265
+ if (forward && error) writeMessage(error);
266
+ return { ok: false, status: response.status, messages };
267
+ }
268
+ }
269
+
270
+ if (!response.ok) {
271
+ const error = syntheticError(
272
+ message,
273
+ response.status,
274
+ `Upstream Xevy MCP request failed (HTTP ${response.status})`,
275
+ );
276
+ if (forward && error) writeMessage(error);
277
+ return { ok: false, status: response.status, messages };
278
+ }
279
+
280
+ if (message?.method === "initialize") {
281
+ initializeMessage = message;
282
+ const negotiated = messages.find(
283
+ (entry) =>
284
+ entry &&
285
+ typeof entry === "object" &&
286
+ entry.result &&
287
+ typeof entry.result.protocolVersion === "string",
288
+ )?.result?.protocolVersion;
289
+ if (negotiated) protocolVersion = negotiated;
290
+ } else if (message?.method === "notifications/initialized") {
291
+ initialized = true;
292
+ }
293
+
294
+ if (forward) {
295
+ for (const entry of messages) writeMessage(entry);
296
+ }
297
+ return { ok: true, status: response.status, messages };
298
+ }
299
+
300
+ async function handleLine(line) {
301
+ const trimmed = line.trim();
302
+ if (!trimmed) return;
303
+
304
+ let message;
305
+ try {
306
+ message = JSON.parse(trimmed);
307
+ } catch {
308
+ writeMessage({
309
+ jsonrpc: "2.0",
310
+ id: null,
311
+ error: { code: -32700, message: "Parse error" },
312
+ });
313
+ return;
314
+ }
315
+
316
+ await postUpstream(message);
317
+ }
318
+
319
+ async function closeUpstreamSession() {
320
+ if (!sessionId) return;
321
+ try {
322
+ await fetch(endpoint, {
323
+ method: "DELETE",
324
+ headers: headers(),
325
+ signal: AbortSignal.timeout(2_000),
326
+ });
327
+ } catch {
328
+ // Best-effort cleanup only.
329
+ }
330
+ }
331
+
332
+ const input = readline.createInterface({
333
+ input: process.stdin,
334
+ crlfDelay: Infinity,
335
+ });
336
+
337
+ let queue = Promise.resolve();
338
+ for await (const line of input) {
339
+ queue = queue
340
+ .then(() => handleLine(line))
341
+ .catch(() => {
342
+ process.stderr.write("xevy-mcp: failed to proxy an MCP message\n");
343
+ });
344
+ }
345
+ await queue;
346
+ await closeUpstreamSession();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@xevy/skills",
3
- "version": "0.1.23",
4
- "description": "Install Xevy agent skills and MCP for Cursor, Claude Code, Codex, and other coding agents — one command via npx skills + add-mcp.",
3
+ "version": "0.1.25",
4
+ "description": "Install Xevy agent skills and secure per-agent MCP transports for Cursor, Claude Code, Codex, and other coding agents.",
5
5
  "type": "module",
6
6
  "keywords": [
7
7
  "xevy",
@@ -1,6 +1,6 @@
1
1
  ---
2
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).
3
+ description: Submit a prepared draft to refinement — answer open decisions first, then move draft → ready. Ready hands the task to the configured Refine owner and may start AI Analyze/Plan.
4
4
  argument-hint: "[task]"
5
5
  disable-model-invocation: true
6
6
  allowed-tools: "Read Bash mcp__xevy__find_task mcp__xevy__list_task_decisions mcp__xevy__answer_decision mcp__xevy__update_task_status"
@@ -8,13 +8,13 @@ allowed-tools: "Read Bash mcp__xevy__find_task mcp__xevy__list_task_decisions mc
8
8
 
9
9
  # /xevy:mark-ready — answer open questions, then mark the task ready
10
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.
11
+ This is the **human submission gate** from `draft` → `ready`. Draft is preparation-only. Ready hands the task to the configured Refine owner; when that owner is AI, server automation may start Analyze and Plan after the status change.
12
12
 
13
13
  ## 1. Resolve the task
14
14
  Resolve from `$ARGUMENTS` (`mcp__xevy__find_task` by code) or the in-context task. If ambiguous, ask which task — never guess.
15
15
 
16
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`.
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 (`planned` / `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
18
 
19
19
  ## 3. Answer open questions (MANDATORY gate)
20
20
  - Call `mcp__xevy__list_task_decisions` for the task.
@@ -23,4 +23,4 @@ When the host supports subagents, dispatch a **plan-reviewer** to cross-check ev
23
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
24
 
25
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. Then call `mcp__xevy__get_process_owners`: if the task is still `draft` and the Refine owner is `ai`, automatically call `mcp__xevy__update_task_status({ taskId, status: "ready" })`; if Refine is human-owned, leave it draft for the user to move manually. 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.
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.
@@ -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 (OAuth)
13
+ ## 0. Preconditions — MCP connection
14
14
  If MCP is not configured yet, run `npx @xevy/skills` from the repo root first.
15
- The Xevy MCP server authenticates via **OAuth** when configured (run `npx @xevy/skills` to add it) — no API key needed for MCP tools.
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 returns "OAuth authorization required" (or similar), stop and give the recovery step for the active client: Codex → run `codex mcp login xevy`, 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, set `XEVY_BASE` (for example `https://xevy.vyte.dev`), reinstall the MCP configuration, and restart the client. Do not proceed until the call succeeds.
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 (not MCP) and read an API key from `~/.config/xevy/credentials` (or `XEVY_API_KEY`). MCP itself uses OAuth; these two local helpers need a REST key. If none is present, tell the user to create one at Xevy → Settings → API keys, then re-run just these steps.
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.