軟體工廠 (Software Factory)
先消除所有範圍上的疑慮。凍結義務。將每個繁重階段委派給全新子代理。由獨立的驗證者（非程式碼作者）來證明完成。
┌──────────┐ ┌──────┐ ┌────────┐ ┌───────┐ ┌────────┐
│ DISCOVER │ → │ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────────┘ └──────┘ └────────┘ └───────┘ └────────┘
0 doubts 確認 義務 批次 作者 != 驗證者
五個步驟，三個持久化工件位於 .specs/features/<feature>/ 下，以及一個在主聊天室中永遠不會讓上下文視窗膨脹的精簡協調器。
- DISCOVER：一個唯讀的
scout子代理掃描程式碼庫，並回傳一份簡潔（約 30 行）的模糊點簡報。主聊天室以具體選項和建議預設值引導使用者提問，直到零個未確認的假設（每一行都獲得Confirmed? y）。請參閱 discovery.md。 - PLAN：一個
planner子代理撰寫.specs/features/<feature>/plan.md（問題、流程、影響、關係、表面、著陸、標準、超出範圍、假設、可觀察項、來源）並執行validate_plan.py。使用者對plan.md進行快速簽核。請參閱 plan.md。 - CHECKS：在
plan.md簽核後，自動化的計畫後循環開始。一個specifier子代理推導出.specs/features/<feature>/checks.md（斷言 + 證明、覆蓋率合併、測試政策、掃除、交接運算）並執行validate_checks.py。請參閱 checks.md。 - BUILD：每個切片/批次一個
builder子代理，嚴格根據檢查撰寫測試、實作程式碼、執行證明、更新checks.md，並使用check_commit.py進行提交。請參閱 build.md。 - VERIFY（與 FIX 循環）：一個獨立的
verifier子代理（絕非 builder）根據每一項檢查稽核<feature base>..HEAD，撰寫.specs/features/<feature>/verification.md，並執行validate_verification.py。如果有任何檢查失敗，一個fixer子代理會解決排序後的差距，然後一個全新的verifier重新驗證（最多 3 輪）。請參閱 verify.md 和 orchestration.md。
為何採用此架構
編碼代理在處理複雜功能時，會因為兩個可預測的原因而失敗：
- 上下文視窗膨脹：當單一聊天會話同時進行探索儲存庫、訪談使用者、撰寫計畫、推導檢查、撰寫測試和程式碼，以及驗證自身工作時，上下文視窗會被填滿，引發有損壓縮。
- 未確認的需求與自我審查盲點：默默地猜測產品行為（
Confirmed? n）或讓作者自我認證完成，會將作者自身的盲點帶入產品中。
software-factory 解決了這兩個問題：
- 精簡協調器（主聊天室中 < 15k 權杖）：主聊天室嚴格扮演協調者和使用者訪談者的角色。所有程式碼庫讀取、工件撰寫、編碼、測試和驗證，都在隔離的短暫子代理（
scout、planner、specifier、builder、verifier、fixer）內部執行，這些子代理僅透過磁碟上的.specs/features/<feature>/檔案和 git 提交進行通訊。完整的調度協定：orchestration.md。 - 小而凍結的義務集 + 獨立驗證者：沒有會過時的細粒度任務檢查清單或元件目錄（每個類別的
Purpose/Location/Interfaces）。單向門在Landing中獲得具體形狀；可逆的放置則在 diff 中決定。
關鍵規則
固定規則集。這些規則在所有設定檔中都成立：
- 零未確認假設（
Confirmed? y）。絕不默默地猜測產品或範圍行為。在DISCOVER階段浮現的每個灰色地帶，都必須以具體選項和建議預設值提問，或由使用者明確委託（Confirmed? y）。validate_plan.py會拒絕任何Confirmed?為n或空白的行。 - 精簡協調器與嚴格的每個階段一個子代理界限（
scout!=planner!=specifier!=builder!=verifier）。保持主聊天室約在 ~15k 權杖以下。絕不將兩個階段合併到單一子代理呼叫中：scout僅探索並回傳約 30 行的模糊點簡報。planner僅撰寫plan.md+ 執行validate_plan.py，然後停止並退出。specifier僅撰寫checks.md+ 執行validate_checks.py，然後停止並退出（它絕不能撰寫測試檔案或實作程式碼，或繼續進入BUILD）。builder僅在specifier返回後執行。對於多切片功能（S1、S2、...），依序調度一個獨立的builder子代理給每個切片，以便每個切片在全新的上下文視窗中執行，並向使用者回報進度。verifier僅在最終builder提交後，於全新的子代理中執行。
- 每個檢查都是一個帶有具體值的可觀察斷言，加上證明——即能透過其退出碼來判定結果的具體測試選擇器或命令。沒有證明，就沒有檢查。
- 測試斷言檢查所說的內容，絕非程式碼恰好做的事。 絕不透過閱讀實作來撰寫測試。
- 絕不為了讓測試套件通過而弱化斷言、刪除測試或跳過測試。 一個真正錯誤的檢查是停下來詢問，而不是編輯。
- 一旦批准，檢查和
Test policy行就固定不變。 在plan.md中，Landing、Relations和Surface是疊加的——在建置過程中發現的一扇門，會在其關閉該門的程式碼之前添加一行，而使用者批准的行絕不會被重寫。Flow和Impact在改變路徑的提交中保持真實。 - 驗證者是全新的子代理，絕非作者，絕非可選，絕非等待被詢問。協調器在功能的最後一次提交落地於
<feature base>..HEAD並包含所有檢查後，立即調度它。 - 設定檔是基礎，由
validate_verification.py強制執行。 - 完成關卡是一個腳本，而不是一種感覺：
validate_verification.py必須退出碼為 0。 - 影響範圍： 已批准的規格授權本地編輯和本地提交。
git push、部署和生產資料變更需要針對該動作獲得明確許可。
設定檔 (Profile)
專案在 AGENTS.md 或同等文件中宣告執行的規模。若無宣告：light。
## software-factory
profile: light
budget: 150k
| 設定檔 | 加入 | 無法捕捉 |
|---|---|---|
light（預設） | 證明在 HEAD 執行，每個命名測試都顯示存在且已執行，每個檢查一個定位的斷言，等級和抽樣差距，Swept existing 重新讀取 | 一個沒有證明的集合成員；一個在錯誤實作下也會通過的測試 |
standard | 重新計算的 Coverage 合併，每個都帶有判決的 Test policy 行，每個斷言表面一個錯誤 | 一個與約束來源矛盾的檢查；一個沒人建置的畫面 |
ui | 開啟並比較約束來源，每個畫面的副本和排列枚舉 | 僅限每個畫面枚舉的間距、顏色和字重 |
如果報告的設定檔與 checks.md 批准時的設定檔不同，validate_verification.py 會使報告失敗；如果 standard 報告沒有錯誤行或重新計算的覆蓋率，也會失敗；如果 ui 報告沒有約束來源章節，也會失敗。
工件 (Artifacts)
.specs/
├── STATE.md # 決策日誌 (AD-NNN) + 交接快照
├── LESSONS.md # 由 scripts/lessons.py 產生 - 絕不手動編輯
├── lessons.json # 機器擁有
└── features/<feature>/
├── plan.md # 問題、流程、影響、關係、表面、著陸、標準、假設（全部 y）、可觀察項
├── checks.md # 斷言 + 證明、覆蓋率合併、測試政策、掃除、交接批次
└── verification.md # 獨立驗證者的報告
在每個階段產生內容時建立對應的檔案。對於大約三個檔案以下、沒有單向門且無範圍模糊的變更，僅撰寫包含 ## Intent 段落的 checks.md，並跳過 plan.md。
plan.md 中的五個有限設計章節
| 章節 | 審查內容 | 排除內容 |
|---|---|---|
Flow | 路徑，每個跳躍一行 | 任何既不存在也不是由某扇門建立的模組——那些是放置問題 |
Impact | 底層變更的內容：術語和既有資料 | 風險登記簿 |
Relations | 實體、基數、單向約束 | 欄位和型別 |
Surface | 路由、輸入、輸出、狀態 | 請求本體規格和檢查 ID——那些還不存在 |
Landing | 單向門，包含具體形狀和被拒絕的替代方案 | 任何重構可以逆轉的東西 |
流程 (Flow)
- 探索 (Discover) — 調度唯讀的
scout子代理來檢查儲存庫、.specs/STATE.md和.specs/LESSONS.md，並回傳一份約 30 行的模糊點簡報。引導使用者走過真正的產品和範圍灰色地帶（每輪最多 2 個問題，提供具體選項和建議預設值），涵蓋Observable表面和 9 個隱含維度，直到零個疑慮：discovery.md。 - 計畫 (Plan) — 調度
planner子代理，使用已確認的探索決策來撰寫.specs/features/<feature>/plan.md並通過validate_plan.py。向使用者展示plan.md以進行快速簽核：plan.md。 - 檢查 (Checks) — 一旦
plan.md獲得批准，自動執行。調度一個專門的specifier子代理來推導.specs/features/<feature>/checks.md（斷言 + 證明、Coverage合併、Swept和## Handoff批次大小調整）並通過validate_checks.py，然後在撰寫任何程式碼或測試之前終止該子代理：checks.md。 - 建置 (Build) — 在
specifier完成後，依序調度一個全新的builder子代理給每個切片（S1、S2、...）。每個建置者根據檢查為其分配的切片撰寫測試、實作、執行證明、在checks.md中記錄Boundary、使用check_commit.py提交並退出：build.md。 - 驗證與修復 (Verify & Fix) — 調度一個全新的
verifier子代理，針對<feature base>..HEAD撰寫verification.md並執行validate_verification.py。如果失敗，調度一個fixer子代理並重新驗證（最多 3 輪）：verify.md。 - 協調與子代理調度 (Orchestration & Subagent Dispatch) — 精簡協調器規則、上下文視窗預算和多代理映射（
antigravity、claude、codex）：orchestration.md。 - 持久記憶 (Durable Memory) — 專案決策（
STATE.md）、會話交接和基於驗證的經驗教訓（lessons.py）：memory.md。
腳本 (Scripts)
將 <skill-dir> 解析為包含此 SKILL.md 的目錄，並執行 python3 <skill-dir>/scripts/<name>.py。當目前工作目錄與專案根目錄不同時，傳入 --root。非零退出碼表示停止並修復。
| 時機 | 命令 |
|---|---|
| 檢查管線階段與下一個子代理角色 | orchestrate.py status <feature> --root <dir> |
| 產生隔離子代理提示 | orchestrate.py prompt <feature> --role <scout|planner|specifier|builder|verifier|fixer> --root <dir> |
| 透過協調器執行階段關卡 | orchestrate.py gate <feature> --phase <plan|checks|verify> --root <dir> |
透過 CLI 調度子代理（或 --dry-run） | orchestrate.py dispatch <feature> --role <role> --agent <antigravity|claude|codex> [--dry-run] |
在呈現 plan.md 之前 | validate_plan.py <feature> |
在開始 BUILD 之前 | validate_checks.py <feature> |
| 每次提交之前 | check_commit.py --message "<msg>" |
| 在宣告完成之前 | validate_verification.py <feature> |
| 在提煉時 | lessons.py add ... |
| 在編輯驗證器、腳本或模板之後 | selftest.py |
子代理與交接 (Subagents and handoff)
每個階段嚴格在自己的子代理呼叫中隔離（scout -> planner -> specifier -> builder [S1] -> builder [S2] -> ... -> verifier -> fixer）。絕不要將 specifier（CHECKS）和 builder（BUILD）結合在同一個子代理中。在 BUILD 期間，當一個功能有多個切片（S1、S2、...）時，依序為每個切片調度一個獨立的 builder 子代理，以便每個建置者從乾淨的上下文視窗開始，快速完成，在其切片通過時提交，並向精簡協調器回報進度更新。
當最後一個建置者切片返回成功時，協調器會在同一回合中立即調度獨立的 verifier 子代理，無需詢問使用者。
知識鏈 (Knowledge chain)
嚴格按照以下順序：既有程式碼和慣例、專案文件、函式庫文件（可取得時使用 Context7）、網路搜尋，然後才標記為不確定。絕不發明 API、旗標、命令或行為。
輸出行為 (Output behaviour)
產出工件；不要敘述階段。以判決開頭。明確陳述決定。刪除填充詞和機械式迴避語。保持章節標題為英文（它們是經由關卡驗證的架構）。