交付流程導讀
這個資料夾向團隊同事說明目前以 Claude Code 為主的交付流程：從需求開單、Issue worktree 的生命週期，到 GitLab 看板的狀態對應，以及各階段使用的 skill、搭配的工具與已知的問題。讀者是同團隊的工程師；目的除了介紹，也讓你能看懂別人的 Issue 與 worktree 狀態，並在自己的機器上照做。
正式規則仍以 AGENTS.md、docs/agents/ 與 docs/issue-lifecycle.md 為準；本資料夾是導讀，不是第二份規範。
章節
| 章 | 內容 | 圖 |
|---|---|---|
| 01 工具版圖 | Claude Code、skills、scripts、Orca、GitLab、Docker、git hooks 之間的關係 | 架構圖 |
| 02 主流程 | 需求 → 開單 → 分級 → 認領 → 實作驗證 → 合入 → push → 結案；批次與 SQL Issue 兩個變體 | 泳道圖 ×3 |
| 03 worktree 生命週期 | 何時建、何時刪、命名與位置、整合分支的 lock | 狀態圖 |
| 04 GitLab label 與看板 | 七個狀態 label、看板欄位、每個 label 的下一步 | 狀態圖 |
| 05 Skills | 主路徑上的七個入口逐一說明；其餘 skill 一張總表 | — |
| 06 問題與困難 | 十項已知地雷：症狀、原因、現況、對應工具 | — |
| 07 環境建置 | 在自己機器啟用：skills、git hooks、Docker、Orca（可選）、GitLab 登入 | — |
| 08 品質校驗時間軸 | 從編輯到回歸每一道校驗：觸發點、檢查什麼、不能證明什麼、手動怎麼跑、失敗看哪裡；三種強度 | 泳道圖 |
統一入口站
site/ 是本資料夾的靜態站：左側側邊欄列出每一章、每張互動圖與正式規範的連結，章內的圖直接內嵌互動版。clone 後用瀏覽器開 site/index.html 即可，不需要任何伺服器。
- Markdown 仍是唯一來源；
site/下的 HTML 全是產物，請改 Markdown 後在 repo 根目錄重產，不要手改 HTML：
node scripts/build-workflow-site.mjscheck-contracts.sh（push 前驗收的一部分）會執行node scripts/build-workflow-site.mjs --check：重產結果與site/有差異就失敗並印出重產指令，所以忘了重產或手改 HTML 都推不出去。- 產站腳本只用 Node 內建模組、不寫時間戳，同一份 Markdown 重產永遠零 diff。新增
NN-*.md章節或diagrams/*.html互動圖後重產，側邊欄會自動列入。 - 公開版：<https://spay2-workflow-docs.pages.dev/>（Cloudflare Pages，由 Operator 在 push 後以
publish-workflow-site.py更新；見 07 環境建置）。
圖怎麼看
- 每章內嵌的 PNG 是靜態預覽；點圖下方的連結可開啟互動式 HTML（可切換主題、搜尋節點、匯出圖片）。GitLab 不會內嵌渲染 HTML，請 clone 後用瀏覽器開啟
docs/workflow/diagrams/*.html。 - 圖以 archify 製作。來源是
diagrams/src/*.json，HTML 與 PNG 都是產物；要改圖請改 JSON 重產，不要手改 HTML。 - 重產方式（在 repo 根目錄；
<archify>是 skill 安裝路徑，例如~/.claude/skills/archify）：
node <archify>/bin/archify.mjs finalize workflow docs/workflow/diagrams/src/02-main-flow.workflow.json docs/workflow/diagrams/02-main-flow.html --quality showcase --out-dir /tmp/archify-evidence --json
node <archify>/bin/archify.mjs visual-check docs/workflow/diagrams/02-main-flow.html --summary --require-provenance --out-dir /tmp/archify-evidencefinalize 需要 Chrome／Chromium（用 ARCHIFY_CHROME 指定執行檔）；在 WSL 裡截圖要先有中文字型，否則 SVG 內的中文會變方框（見 07 環境建置）。--out-dir 把收據與截圖放在 repo 外，預覽 PNG 取 *.1440x900.light.png。
本資料夾的產生方式
這個資料夾本身就是依本流程產出的：以 issue-create.mjs 開成 ready-for-agent、/issue-run 認領時建立 Issue worktree、在該 worktree 內撰寫與產圖、以 check-contracts.sh 驗證後「結案」合入整合分支、由 Operator ! git push、再「結案」一次關單。