rush-ai 0.6.0 → 0.7.0

package/skills/hand-off.md

@@ -0,0 +1,163 @@
+# Skill: Hand off the task to Rush
+
+Use this skill when the user is talking to you inside an IDE (Cursor, Claude Code, or similar) and the next step belongs on the Rush platform. You already have full context from the conversation — `rush-ai` exists so you can relay that context to Rush's cloud agents without making the user summarize it again.
+
+## When this skill applies
+
+Triggers (not exhaustive — use judgement):
+
+- "Build me a landing page / product site / marketing page."
+- "Turn this spec / sketch / Figma link into a site."
+- "Spin up a demo site for X."
+- Any time the conversation points at producing a running web artifact the user will want to **share a link** for.
+
+Do NOT use this skill for:
+
+- Small local edits the user wants you to apply directly in the current repo.
+- Questions about Rush itself ("what is rush-ai", "how do I log in") — answer those from docs instead of creating a task.
+
+## Decision: which agent?
+
+| Situation | Agent to pass to `-a` |
+|---|---|
+| Build a website, landing page, marketing page, or anything that should render as a live preview URL | `web-builder` |
+| General-purpose conversation / analysis / generation the user would have asked a chat agent for | `rush` (the platform default) |
+| User named a specific specialist agent (e.g. "use the HR analytics agent") | that agent name verbatim |
+
+If you are unsure, start with `npx rush-ai agent list --default` — that shows just the built-in defaults (`web-builder`, `rush`, `skill-publisher`, ...), which is usually all you need for a hand-off. Widen with `--search <keyword>` or `--all` only when the user clearly asked for a specialist. When in doubt between `rush` and `web-builder`, ask the user — but if the output is going to be a URL, default to `web-builder`.
+
+## Playbook
+
+### 1. Verify auth (once per session)
+
+```bash
+npx rush-ai auth status --json
+```
+
+The response includes a boolean `authenticated` (or equivalent) plus an auth method. **Read it before you do anything else.** There are only two cases — no third case, no "maybe":
+
+- **Authenticated** → proceed to step 2.
+- **Not authenticated** → STOP. Print this exact message to the user and wait:
+
+  > Rush 还没登录。请在终端里跑 `npx rush-ai auth login`（会打开浏览器完成 CAS 登录），登录成功后告诉我一声。
+
+  Do NOT run `auth login` yourself — it opens a browser and waits for human interaction.
+  Do NOT invent workarounds (don't try API keys, don't edit `~/.rush/auth.json`).
+  Do NOT fall through to `task create` anyway — it will return 401 and confuse the user.
+
+When the user returns, re-run `auth status --json` to confirm before continuing.
+
+### 2. Create the task, carrying the context you already have
+
+Write the prompt from the conversation. Do **not** ask the user to restate requirements you already know. Include any constraints they have already mentioned (brand, style, pages, copy).
+
+```bash
+npx rush-ai task create \
+  -a web-builder \
+  -p "<prompt synthesized from the conversation>" \
+  --json
+```
+
+The JSON response contains `id`. Keep it; you'll need it for every follow-up.
+
+### 3. Report the handoff to the user
+
+Tell the user, in one line:
+
+- the task id
+- that it's running on Rush
+- how they can watch (either "I'll poll for you" or "open the Rush web UI")
+
+Don't dump the full JSON unless they ask.
+
+### 4. Poll status until ready
+
+```bash
+npx rush-ai task status <id> --json | jq -r '.status'
+```
+
+Terminal states: `completed`, `failed`, `cancelled`. Poll every ~15–30s; don't hammer it.
+
+**Pipe directly** — don't round-trip the JSON through a shell variable:
+
+```bash
+# good — JSON stays as raw bytes, no shell re-interpretation
+npx rush-ai task status <id> --json | jq -r '.status'
+
+# bad — zsh's builtin `echo` re-interprets \n as a real newline;
+#       jq then rejects the result with "control characters must be escaped".
+#       (bash's echo usually doesn't, but behavior is shell-dependent.)
+STATUS=$(npx rush-ai task status <id> --json)
+echo "$STATUS" | jq .     # ← breaks in zsh once the JSON contains \n
+
+# acceptable alternatives when you really need the variable:
+printf '%s' "$STATUS" | jq .   # portable — printf never re-interprets escapes
+jq . <<< "$STATUS"             # here-string — does not re-interpret backslash escapes
+```
+
+When `status == completed`, the response contains (for `web-builder`):
+
+- `previewUrl` — shareable live preview (e.g. `https://<id>-preview.rush.zhenguanyu.com/`)
+- `gitRepoUrl` — cloneable repo (e.g. `https://gitlab-ee.zhenguanyu.com/rush/online/<id>`)
+
+Present both to the user. The preview URL is the primary artifact they care about.
+
+### 5. Iterate via `task send`, not by creating new tasks
+
+If the user says "change the button color" / "add a testimonials section" / "make the hero bigger", **do not create a new task** — send a follow-up to the existing one:
+
+```bash
+npx rush-ai task send <id> -p "<the change they asked for>" --json
+```
+
+The preview URL stays the same; it will refresh after the send completes. Poll `task status <id>` again.
+
+Only create a fresh task if the user explicitly starts a new, unrelated project.
+
+### 6. Failure handling
+
+If `status == failed`, the response has an `error` field. Surface it to the user verbatim and ask whether to:
+
+1. retry with a revised prompt via `task send`,
+2. cancel and start over, or
+3. dig in themselves (give them the task id so they can look it up).
+
+Do not silently retry.
+
+## Example end-to-end
+
+User (in Cursor): "帮我做个公司官网首页，风格大气专业。"
+
+Your actions:
+
+```bash
+# 1. check auth (assume ok)
+npx rush-ai auth status --json
+
+# 2. create (prompt synthesized from the prior conversation — brand, tone, pages)
+npx rush-ai task create -a web-builder \
+  -p "做一个公司官网首页，包含导航、Hero、核心特性、客户评价和底部联系信息，风格大气专业。" \
+  --json
+# → {"id": "lodig8oknq0r", "status": "pending", ...}
+
+# 3. tell the user
+# "已经派到 Rush 的 web-builder，任务 id lodig8oknq0r，我帮你盯着。"
+
+# 4. poll
+npx rush-ai task status lodig8oknq0r --json
+# ...wait...
+# → {"status": "completed", "previewUrl": "https://lodig8oknq0r-preview.rush.zhenguanyu.com/", "gitRepoUrl": "..."}
+
+# 5. present
+# "跑完了：
+#    预览: https://lodig8oknq0r-preview.rush.zhenguanyu.com/
+#    代码: https://gitlab-ee.zhenguanyu.com/rush/online/lodig8oknq0r
+#  要改哪儿继续说，我走 task send 不新起任务。"
+```
+
+## Anti-patterns
+
+- ❌ Asking the user to re-describe requirements they already told you in-thread.
+- ❌ Creating a new task for every tweak — use `task send`.
+- ❌ Hiding the task id from the user (they may want to reopen the Rush UI later).
+- ❌ Running `task watch` when all you need is final status — it streams verbosely, use `task status` for quick polls.