| name | onboard |
| description | Use when the user wants to onboard a company workspace from scratch, add a company, or rerun workspace setup. Primary trigger: 'onboard'. Deprecated aliases: 'init', '/init', 'initialize', 'setup workspace', '初始化'. |
| metadata | {"author":"Polaris","version":"4.0.0"} |
Onboard — Workspace Setup Wizard
互動式 wizard，負責建立或更新 company workspace config，並把 company route 登記到
root workspace-config.yaml。
init / /init / re-init 是 deprecated aliases，只作相容入口；新的 skill source、
reference loading 與文件語言都以 onboard 為主。
Contract
onboard 只負責 setup orchestration：
- 從
_template/workspace-config.yaml 建立或編輯 {company}/workspace-config.yaml。
- 在 root
workspace-config.yaml 登記 company routing。
- 從
_template/rule-examples/ scaffold company-scoped L2 rules。
- 探測 optional integrations，但 optional 系統不可阻塞 onboard 完成。
- 所有偵測值都必須先顯示給使用者確認，再寫入。
不要猜缺漏值。Auto-detection 只能提供 suggestion，必須經使用者確認。每個 optional
section 都可 skip；skip 後欄位保持空值，下游 skills graceful degrade。
Reference Loading
依使用者選到的路徑只讀需要的 references：
| Situation | Load |
|---|
Any onboard run | onboard-interaction-patterns.md, onboard-core-workflow.md, workspace-config-reader.md, workspace-language-policy.md |
| Existing company / upgrade rerun | onboard-core-workflow.md rerun section |
onboard repair / readiness check | onboard-core-workflow.md, onboard-post-setup-flow.md, workspace-config-reader.md |
| Project repo detection | onboard-interaction-patterns.md, sub-agent-roles.md |
| Dev environment setup | onboard-runtime-setup-flow.md, dependency-consent.md |
| Visual regression setup | onboard-visual-regression-setup.md, visual-regression-config.md |
| Daily learning scanner | learning-setup-flow.md, daily-learning-scan-spec.md |
| Runtime toolchain / Codex bootstrap / handbook | onboard-post-setup-flow.md, repo-handbook.md as needed |
Repo analysis 或 dev environment detection 派 sub-agent 時，必須注入
sub-agent-roles.md 的 Completion Envelope。
Flow
- 解析 workspace root，讀取 root config。
- 判斷 full onboard、edit existing company、rerun missing sections，或 cancel。
- 確認 root language preference 存在，後續 prompt 全部使用該語言。
- 依 loaded references 收集 company basics、GitHub、JIRA、Confluence、Slack、
Kibana、projects、scrum、infra、runtime、visual regression 設定。
- 寫入前顯示完整 YAML；
default_company 只能在 root config，不可進 company config。
- 寫入 company config、更新 root company routing、append audit entries。
- 執行 optional post-setup：clone missing repos、genericize maps、MCP health check、
daily learning scanner、root toolchain readiness check、Codex bootstrap、handbook generation。
- 執行
mise run onboard-doctor，回報 ready / partial / blocked、deferred empty
fields、root toolchain status、Codex bootstrap status 與建議的第一個指令。Root toolchain
repair 採 print-only，只顯示 mise run bootstrap /
mise run doctor -- --profile <profile>，不可由 onboard repair 隱性代跑。若使用者明確選擇
--execute，才可執行可自動修復且 non-interactive / CI-safe 的 repair command。
Write Rules
- Config writes 只寫 local，且必須 idempotent。
- Root config 只 append 或 update 目標 company。
- 不可因新增 company 移除或重寫既有 companies。
- Rerun 只 merge 新收集 sections，不破壞既有 user-provided fields。
- Repair mode 必須先顯示 doctor summary，再依 action class 決定是否可自動修復；預設
print-only，只有明確
--execute opt-in 才能執行 non-interactive / CI-safe command。
- Config 不可存 secrets，即使 company config 是 gitignored。
- Setup extensions 若觸及 Slack、JIRA、Confluence、GitHub external write surface，
發送 user-visible text 前必須通過
workspace-language-policy.md language gate。
Output Rules
產出的 company config 遵守 _template/workspace-config.yaml：
- YAML 使用 two-space indentation。
- Template 原本有 inline comments 的欄位保留 comments。
- Skipped optional scalar fields 使用 empty strings。
- Template 預期為 arrays 的欄位保持 arrays。
每個 user decision 與 auto-detection result 都 append 到
{company}/.onboard-audit.jsonl；re-run 時 append restart marker。
Completion
回報完成前：
- 掃描產出的 company config，列出 empty string deferred fields 與補值方式。
- 若曾提供 Codex bootstrap，顯示 bootstrap status。
- 執行
post-task-reflection-checkpoint.md checklist。
Post-Task Reflection (required)
Final response 前執行 shared reflection checkpoint。
