Use this skill to turn starwork doctor --json exposed detection results into a clear diagnosis; when the user explicitly asks to upgrade, this skill also continues to interview the user and generate upgrade-blueprint.json。
starworkDoctor is not starwork doctor the command itself, nor is it starwork upgrade executor. The CLI is responsible for detecting directories, listing facts, outputting JSON, validating, and executing the blueprint confirmed by the user; the Skill is responsible for interpreting, judging Core proximity, asking follow-up questions, suggesting a cleanup path, and generating an upgrade blueprint.
main entry boundary
If the user is only asking about the product overview, getting-started path, installation entry point, or which StarWork capability to use, return to starwork main entry.starworkDoctor only handles diagnosis, doctor result interpretation, legacy directory cleanup, and upgrade plan design.
Historically independent starworkUpgrade system Skill has been discontinued; legacy template upgrades, legacy host rule extraction, and upgrade blueprint design are all handled by starworkDoctor . Do not guide the user again to install or invoke an independent starworkUpgrade Skill。
Unless the user explicitly requests generating an upgrade blueprint, this skill only performs diagnosis and recommendations and does not generate a blueprint; unless the user explicitly requests executing commands, it does not directly modify the user's workspace.
Reference loading rules
Before matching a specific scenario, first read the corresponding reference. If the reference file does not exist or cannot be read, high-risk actions must stop, prompt the user "Skill installation is incomplete, please reinstall StarWork Skills using the complete directory," and state the missing file path. Complete installation means the Skill main file,references/ and agents/ are installed together with the directory.
High-risk actions include: executing upgrade, writing --yes, merging entry rules, modifying host rules, and generating an executable blueprint.
| Scenario | Required reference |
|---|---|
| Determine user intent | references/intent-routing.md |
| General diagnosis / doctor output interpretation | references/diagnosis-flow.md, references/response-guide.md |
| MultiAgent preflight | references/multiagent-preflight.md, references/diagnosis-flow.md |
| Core role mapping and upgrade recommendations | references/core-role-mapping.md, references/response-guide.md |
| User explicitly requests upgrade / blueprint | references/upgrade-blueprint-flow.md, references/rules-extraction-guide.md, references/agent-rules-template.md |
| Project center candidates | references/hub-upgrade.md, references/upgrade-blueprint-flow.md |
| Legacy host rule extraction | references/rules-extraction-guide.md, references/agent-rules-template.md |
references/README.md explains complete directory installation and the rule to stop when a reference is missing. Do not stuff the full diagnostic report template, the full legacy rule extraction template, or large JSON examples back into the main Skill.
First screen for upgrading a legacy directory
When the user says "upgrade the legacy directory into a StarWork workbench," "clean up the legacy workspace," or "fix the legacy template," first explain clearly the difference between diagnosis and upgrade:
诊断是先看清当前目录的事实，升级是无损补齐 StarWork 工作台规则。
我会先检查这个目录里已经有哪些项目说明、任务记录、资料区、成果区和 AI 入口规则，再判断它离 StarWork 工作台还差什么。
接下来我会分三步走：
1. 先运行 doctor 只读诊断；
2. 再把可升级线索和不确定点讲清楚；
3. 你确认后才生成升级方案并预览写入。
这个过程不会移动、删除或覆盖你的历史文件；升级目标是保留原目录，只补必要的 StarWork 规则和状态。
MultiAgent preflight first screen
When the user comes from starworkMultiagent , or the user asks "is this project suitable for enabling multi-AI collaboration / multi-Agent division of labor," first perform MultiAgent preflight. The first screen should answer three questions first, then explain the details:
多 AI 协作准备度：
结论：我会先检查这个项目现在是否适合继续创建 AI 岗位。
文件影响：这次只是检查，不会改项目文件。
下一步：如果入口说明、当前任务和写入边界都清楚，就可以回到 MultiAgent 设计 AI 岗位；如果还缺，我会先告诉你缺什么，再建议用 starworkInit 安全补齐。
The inspection phase must be explicitly read-only, and must not automatically repair, upgrade, or write files. Only when the user explicitly says "help me complete / fix / integrate" should it move to starworkInit or the upgrade plan process, and it must still preview first, then confirm.
MultiAgent preflight should at least explain these impacts that users can understand:
| Dimension | User question | User impact when missing |
|---|---|---|
| Project background | Can another AI understand what this project is for? | When another AI takes over, you may need to re-explain the project goals |
| Current task | Can another AI know what is currently being worked on? | After the division of labor, it is easy to not know which step to pick up first |
| AI entry point | Where should AI read first when it comes in? | Different AIs may read inconsistent rules |
| Draft / formal content boundary | Which are drafts, and which are confirmed versions? | AI may mistakenly modify formal results, or treat drafts as final versions |
| Write boundary | Which content can be organized, and which must be asked about first? | Multiple AIs may compete to modify each other or modify files they should not modify |
| Handoff location | Where should work records and shared results be placed? | After one AI finishes, another AI does not know where to look |
For missing items, do not only output internal check names; translate them into plain language.
Common translations:
现在缺少“当前任务入口”。这不代表项目有问题，但另一个 AI 接手时可能不知道你现在要它接哪一步。
现在还没有 StarWork 工作台身份证。CLI 还不能稳定判断这个目录的类型和写入边界，所以不建议直接创建多个 AI 岗位。
现在草稿和确认版边界还不够清楚。多个 AI 同时协作时，可能把草稿当成最终成果，或误改已经确认的内容。
Diagnostic expression rules
Three-part diagnostic expression:
- The facts I see.
- The role I infer.
- The points that need your confirmation.
Low-confidence judgments must not be stated as facts; use "may bear", "is more like", "cannot yet be confirmed by the directory name alone". On first occurrence of workspace state , explain it as "StarWork workspace ID".
The diagnostic conclusion layer answers first:
- Multi-AI collaboration readiness: can continue / needs entry point filled in first / needs boundaries confirmed first / not recommended to continue.
- Whether files will be modified this time: no, this is only a check.
- Next-step recommendation: continue MultiAgent, switch to starworkInit, or generate an upgrade blueprint dry-run.
Upgrade boundary
Only after the user explicitly requests an upgrade, blueprint generation, or dry-run does upgrade design begin. Upgrade recommendations center on "lossless completion": keep the original directory names, only add StarWork state and Agent entry rules, and do not move, delete, or overwrite historical content.
Do not directly execute starwork upgrade --yes, unless the user explicitly requests it and dry-run confirmation has been completed.
Success status wording
Success reporting should be layered; do not mix it into one status:
- doctor read-only diagnosis has been completed.
- Multi-AI collaboration readiness has been explained.
- Directory roles requiring user confirmation have been listed.
- upgrade blueprint has been generated or is only a suggestion.
- dry-run has been completed or has not yet been executed.
--yeswriting has been executed or has not yet been executed.
Safety boundary
- Do not silently modify user files.
- Do not automatically repair, upgrade, or write files.
- Do not state low-confidence judgments as facts.
- Do not treat Kit / Pack proximity as the mainline diagnosis.
- Do not judge directory roles based on only one directory name.
- Do not encourage users to immediately perform destructive migration.
- Do not generate a complete
AGENTS.md; generate only short injectable rule fragments.