AI 開發流程

owl 只管 proposal（要什麼），plan／tasks／Linear 卡由前後端各自處理（怎麼做）。依 Constitution P4：跨 repo 協調點只有兩個——owl 定義需求意圖、契約自動流動。

1 · 三個專案怎麼分工

owl（Ci）定需求 → 規格下放 → cockatiel（Claire）／raven（Pink）各自實作。契約單向流動：後端產出、前端排程拉。

flowchart TB
  subgraph HUMAN["人與觸發層"]
    LINE["LINE 群組
自然語言指令"]
    CC["本機 Claude Code
／Docker 蝦餅"]
    LINE -->|指令| CC
  end

  subgraph OWL["owl · 純規格（Ci）· owl 的工作到此結束"]
    PROP[".prospec/changes/
proposal only
REQ-OWL-*"]
    SPECS["specs/
已沉澱 Feature Spec"]
    DESIGN["designs/
M+ Admin 設計稿"]
    PROP -.歸檔.-> SPECS
    DESIGN -.對照.-> PROP
  end

  BOARD["SDD 看板
owl-sdd-board.pages.dev"]
  BRAIN[("team-brain
共享知識庫
三個 repo 都掛載")]

  subgraph IMPL["實作層（git submodule · 各自跑完整 prospec 八階段）"]
    COCK["cockatiel（Claire）
new-story → plan → tasks
→ Linear 卡 → implement
REQ-CKT-*"]
    RAVEN["raven（Pink）
new-story → plan → tasks
→ Linear 卡 → implement
REQ-RVN-*"]
  end

  OAS["openapi.yaml
唯一契約來源"]

  CC -->|寫檔 + git push| PROP
  PROP -->|board/build.mjs| BOARD
  PROP -->|"規格下放 PR（接點 ①）
scripts/sync-specs.sh"| COCK
  PROP -->|"規格下放 PR（接點 ①）"| RAVEN
  COCK -->|export_openapi
contract.yml 守門| OAS
  OAS -->|"contract-sync.yml
每天排程拉 · 自動開 PR（接點 ②）
✅ 2026-08-25 上線"| RAVEN
  BRAIN -.唯讀掛載.- OWL
  BRAIN -.唯讀掛載.- COCK
  BRAIN -.唯讀掛載.- RAVEN

  classDef owl fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#064E3B
  classDef impl fill:#FFFBEB,stroke:#D97706,stroke-width:2px,color:#78350F
  classDef infra fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#1E3A8A
  classDef gap fill:#FEE2E2,stroke:#EF4444,stroke-width:2px,color:#7F1D1D,stroke-dasharray:5 3
  class PROP,SPECS,DESIGN owl
  class COCK,RAVEN impl
  class BOARD,BRAIN infra
  class OAS gap

規格下放實際怎麼運作

owl 把 cockatiel 與 raven 掛成 submodule（apps/cockatiel、apps/raven），所以 Ci 在 owl 的工作區裡就是兩個子 repo 的完整 checkout。跑 scripts/sync-specs.sh 會自動完成：

在子 repo 開 docs/sync-specs-YYYYMMDD 分支
把 proposal 與 implementation-notes 複製進 docs/features/<change-name>/
commit、push 分支、開 PR（兩個 repo 都是「模式：product — PR 必開、一人 review」， raven 更明訂禁止直接推 main）
PR 併入後回 owl bump submodule 指標，記錄「下放到哪一版」

Pink 和 Claire 那邊只要 git pull 就拿得到，不需要在自己的 repo 掛 owl。注意 git submodule update 是把子 repo 拉進 owl 的指令，方向與下放相反—— 下放靠的是在 submodule 工作區寫檔並開 PR 進子 repo。

不下放 metadata.yaml——那是 owl 的看板狀態（status、Linear 卡號、跨 repo 進度），不是給工程看的需求內容。

2 · 一張需求的完整生命週期

owl 到 proposal 確認就結束；之後前後端各自跑完整 prospec 八階段、各自開 Linear 卡。

flowchart TB
  subgraph OWL_PHASE["owl（Ci）— 到此結束"]
    A0["① 需求進來
Jacky 口述／User Story"]
    A1["② /prospec-new-story
proposal.md · draft"]
    A2["③ 看板自動更新"]
    A3{"④ Jacky review"}
    A4["⑤ 逐題答覆"]
    A5["⑥ AI 套用決議"]
    A6{"⑦ vs 設計稿核對"}
    A7["⑧ 落差卡"]
    A8["⑨ push · owl 完成"]
  end

  SM["⑩ 規格下放 PR
scripts/sync-specs.sh 開 branch
→ 子 repo 一人 review → merge（接點 ①）"]

  subgraph BE_PHASE["cockatiel（Claire）— 完整 prospec 八階段"]
    B1["⑪ 讀 owl proposal
/prospec-new-story
工程語彙重寫"]
    B2["⑫ /prospec-plan
/prospec-tasks"]
    B3["⑬ 自己開 Linear 卡"]
    B4["⑭ implement
→ export_openapi"]
    B5{"⑮ contract.yml
守門"}
    B6["⑯ verify → archive"]
    B1 --> B2 --> B3 --> B4 --> B5 --> B6
  end

  subgraph FE_PHASE["raven（Pink）— 完整 prospec 八階段"]
    C1["⑪ 讀 owl proposal
/prospec-new-story
工程語彙重寫"]
    C2["⑫ /prospec-plan
/prospec-tasks"]
    C3["⑬ 自己開 Linear 卡"]
    C4["⑭ PR 一：假資料刻元件
不等後端"]
    C5["⑮ PR 二：換真型別"]
    C6{"⑯ ci.yml 型別 gate"}
    C7["⑰ verify → archive"]
    C1 --> C2 --> C3 --> C4 --> C5 --> C6 --> C7
  end

  SYNC{{"contract-sync.yml
排程拉契約（接點 ②）
✅ 已上線"}}

  A0 --> A1 --> A2 --> A3
  A3 -->|有疑問| A4 --> A5 --> A2
  A3 -->|通過| A6
  A6 -->|有落差| A7 --> A4
  A6 -->|一致| A8
  A8 --> SM
  SM --> B1
  SM --> C1
  B5 -->|綠燈| SYNC --> C5

  classDef owl fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#064E3B
  classDef human fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F
  classDef gate fill:#FEE2E2,stroke:#EF4444,stroke-width:2px,color:#7F1D1D
  classDef be fill:#FFF7ED,stroke:#EA580C,stroke-width:2px,color:#7C2D12
  classDef fe fill:#EFF6FF,stroke:#3B82F6,stroke-width:2px,color:#1E3A8A
  classDef gap fill:#FEE2E2,stroke:#EF4444,stroke-width:2px,color:#7F1D1D,stroke-dasharray:5 3
  classDef sm fill:#F3E8FF,stroke:#7C3AED,stroke-width:2px,color:#4C1D95
  class A0,A1,A2,A3,A4,A5,A6,A7,A8 owl
  class B1,B2,B3,B4,B6 be
  class C1,C2,C3,C4,C5,C7 fe
  class B5,C6 gate
  class SYNC gap
  class SM sm

綠＝owl 規格層｜橘＝cockatiel｜藍＝raven｜黃＝人做決定｜紅框＝檢查關卡

3 · 前後端各自怎麼開發

後端由內而外（Domain → Presentation → openapi.yaml）；前端兩段式 PR——第一段假資料刻元件不等後端，第二段換真型別。交會點是 openapi.yaml。

flowchart LR
  subgraph OWL2["owl — 已完成"]
    P["proposal
需求意圖與驗收條件"]
  end

  subgraph BE["cockatiel（Claire）— 完整 prospec"]
    B0["讀 owl proposal
/prospec-new-story"]
    B1["plan → tasks
→ 自己開 Linear 卡"]
    B2["Domain → Application
→ Infrastructure → Presentation"]
    B3["export_openapi"]
    B4{"contract.yml
freshness ＋ breaking"}
    B5["verify → archive"]
    B0 --> B1 --> B2 --> B3 --> B4 --> B5
  end

  OAS[("openapi.yaml")]

  subgraph FE["raven（Pink）— 完整 prospec"]
    F0["讀 owl proposal
/prospec-new-story"]
    F1["plan → tasks
→ 自己開 Linear 卡"]
    F2["PR 一：假資料刻元件
形狀依 owl proposal"]
    F3["PR 二：換真型別
來自 schema.d.ts"]
    F4{"ci.yml
vue-tsc 型別 gate"}
    F5["verify → archive"]
    F0 --> F1 --> F2
    F3 --> F4 --> F5
  end

  SYNC{{"contract-sync.yml
每天排程拉 · 自動開 PR
✅ 已上線"}}

  P -->|規格下放 PR| B0
  P -->|規格下放 PR| F0
  P -.owl proposal
講清楚欄位與行為
不用前後端私下對接口.-> F2
  B4 -->|綠燈才 merge| OAS
  OAS --> SYNC --> F3
  F2 -->|可獨立審合
不依賴 API| F3

  classDef owlc fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#064E3B
  classDef bec fill:#FFF7ED,stroke:#EA580C,stroke-width:1.5px,color:#7C2D12
  classDef fec fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#1E3A8A
  classDef gatec fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F
  classDef gapc fill:#FEE2E2,stroke:#EF4444,stroke-width:2px,color:#7F1D1D,stroke-dasharray:5 3
  class P owlc
  class B0,B1,B2,B3,B5 bec
  class F0,F1,F2,F3,F5 fec
  class B4,F4 gatec
  class SYNC gapc
  class OAS owlc

CI 的五個介入點

介入點	擋什麼	誰看紅燈	狀態
cockatiel PR `contract.yml`	改了 route 忘記重新匯出契約；做了 breaking change	Claire	已上線
raven 排程 `contract-sync.yml`	不擋 PR，有差異就自動開型別更新 PR	Pink	已上線 2026-08-25
raven PR `ci.yml`	lint / typecheck / test 三個 job	Pink	已上線 2026-08-26 修綠
cockatiel 的 test／lint	測試掛了、lint 不過	Claire	尚未建立
owl spec PR（選配）	`metadata.yaml` 的 stage 值不在合法枚舉內	Ci	建議但不急

4 · 誰在什麼時候做決定

AI 查證與整理、Ci 過濾與調度、Jacky 只答需要決策的問題；後端與前端第一段並行。

sequenceDiagram
  participant J as Jacky
PM／業主
  participant C as Ci
owl 規格
  participant AI as AI
蝦餅／Claude Code
  participant K as Claire
cockatiel
  participant P as Pink
raven
  participant CI as CI
GitHub Actions

  J->>C: 需求描述／User Story 文件
  C->>AI: /prospec-new-story
  AI->>AI: 讀設計稿＋既有規格＋實作現況
  AI-->>C: proposal ＋ Open Questions
  C->>J: 看板連結，請 review
  J-->>C: 逐題答覆
  C->>AI: 套用決議
  AI->>AI: 核對規格 vs 設計稿 vs 實作
  AI-->>C: 落差清單
  C->>J: 只問真的需要他決定的
  J-->>C: 拍板
  Note over C: push → owl 完成

  Note over K,P: 規格下放 PR 併入後，git pull 拿到 docs/features/

  par 後端（Claire）
    K->>K: /prospec-new-story（工程語彙重寫）
    K->>K: plan → tasks → 自己開 Linear 卡
    K->>K: implement
    K->>CI: PR ＋ export_openapi
    CI-->>K: contract.yml 綠燈
  and 前端第一段（Pink）
    P->>P: /prospec-new-story（工程語彙重寫）
    P->>P: plan → tasks → 自己開 Linear 卡
    P->>P: PR 一：假資料刻元件
    P->>CI: PR 一（不依賴 API）
  end

  CI->>P: contract-sync 拉新契約，自動開 PR
  P->>P: PR 二：換真型別
  P->>CI: ci.yml 型別 gate

  K->>K: verify → archive
  P->>P: verify → archive