跳至主要内容

Autonomous Bootstrap

本文件是 tachigo 的 Hybrid AWP with Explicit Fallback Gate 單一啟動入口。當使用者要求 Autonomous、AWP、Hybrid AWP、Codex autonomous workflow,或要求搭配 spec-injector 執行 issue-first work 時,AI agent 先讀本文件,再由本文件展開其餘必讀文件、spec-injector gate、routing plan 與 PR closeout。

人類只需要指定這一份文件,例如:

請讀 docs/ai/autonomous-bootstrap.md,使用 Hybrid AWP with Explicit Fallback Gate + spec-injector 處理 issue #123。

本文件只適用於明確啟動 autonomous / Codex workflow 的工作。一般 human PR 不需要填 AWP routing、worker profile、spec gate evidence 或 review-triage refs。

0. Hard Boundaries

  • 不直接 push developmain;日常 PR 目標是 develop
  • 不覆蓋 dirty worktree;若目前工作區有未提交變更,先回報並改用乾淨 worktree。
  • 不在沒有 source issue 的情況下實作;先找既有 issue,沒有才依 repo 規則請求建立 issue 的明確授權。
  • 不把 .spec-injector/、spec output、private context、task package 或工具暫存內容 commit 進 repo。
  • 不因 spec-injector output 擴張 issue scope;guardrail、classifier、auto-discovered reference 都不是擴 scope 授權。
  • 不修改遠端 issue / PR / label / review / branch,除非使用者已明確授權該公開狀態變更;授權範圍與執行結果需在回報或 PR evidence 中留痕。

1. Mandatory Read Set

讀完本文件後,AI 必須讀下列 canonical 文件,不得只靠提示詞記憶:

  • AGENTS.md
  • CLAUDE.md
  • .github/PULL_REQUEST_TEMPLATE.md
  • docs/ai/codex-autonomous-workflow.md
  • docs/ai/autonomous-pr-gates.md
  • docs/pr-scope-policy.md

若要修改 workflow / Scope Police / PR template,還要讀:

  • .github/workflows/pr-scope-police.yml
  • .github/workflows/ci.test.mjs

若 spec-injector tool behavior 本身不符合預期,先回報工具版本落差;不要在 tachigo PR 裡實作 spec-injector runtime。

2. Startup Readback

開始任何實作前,AI 必須先回報:

  • cwd
  • current branch
  • dirty state
  • target base branch, normally develop
  • source issue URL / number
  • duplicate issue / branch / PR readback
  • spec-injector availability and gate status

如果任一項無法確認,先回報風險,不要假裝已完成前置作業。

3. spec-injector Local Setup

先檢查工具是否可用:

command -v spec
spec workflow-check --help

spec workflow-check --help 必須顯示 #242 之後的 flags:

  • --finding-disposition
  • --threshold-evidence
  • --pr

若既有全域 spec 沒有這些能力,先用 canonical source 建立 local runner,不要直接改組員的全域環境:

export SPEC_INJECTOR_DIR="${SPEC_INJECTOR_DIR:-$HOME/dev/spec-injector}"

if [ ! -d "$SPEC_INJECTOR_DIR/.git" ]; then
git clone https://github.com/Erick52106/spec-injector.git "$SPEC_INJECTOR_DIR"
fi

git -C "$SPEC_INJECTOR_DIR" pull --ff-only
pnpm --dir "$SPEC_INJECTOR_DIR" install --frozen-lockfile
pnpm --dir "$SPEC_INJECTOR_DIR" build

接著用 local runner 做能力檢查:

node "$SPEC_INJECTOR_DIR/dist/cli/index.js" workflow-check --help

若 local runner 可用但全域 spec 仍是舊版,本次工作優先使用 local runner,例如:

node "$SPEC_INJECTOR_DIR/dist/cli/index.js" workflow-check --repo . --phase start --issue <issue-number-or-url>

若 clone、pull、install、build 或 capability check 失敗,先停止並回報 tool_gap=spec-injector #242 workflow-check unavailable。可以用人工 checklist、spec planspec validate 作為暫時 evidence,但不得宣稱已跑完整 #242 workflow-check。

若 repo 缺 spec-injector config,AI 可以提議本機初始化:

spec init --repo .

初始化只允許 local-only。除非 source issue 明確要求並經 human review,否則不得把 .spec-injector/ 或其輸出納入 commit / PR。

不得使用 curl | bashwget | shnpxpnpm dlx 或未經 review 的任意安裝腳本取得 spec-injector。若環境政策禁止安裝依賴,保留 blocked evidence 並改走 manual checklist,不要偷渡產物。

4. Start Gate

如果任務已提供 issue number / URL:

spec plan <issue-number-or-url> --repo . --dry-run --format prompt --verbose
spec workflow-check --repo . --phase start --issue <issue-number-or-url>

若使用 local runner,將第二行改為:

node "$SPEC_INJECTOR_DIR/dist/cli/index.js" workflow-check --repo . --phase start --issue <issue-number-or-url>

如果尚未確定 issue:

  1. 先用 GitHub metadata 搜尋既有 issue。
  2. 讀候選 issue,確認 source of truth。
  3. 若沒有合適 issue,先取得使用者對「建立 source issue」的明確授權;取得授權後再依 repo 規則建立。
  4. 再跑上面的 spec plan 與 start gate。

spec workflow-check 若不可用,記錄 tool_gap=workflow-check unavailable,並以 spec plan output + manual AWP checklist 作為 start evidence。

5. Routing Plan Gate

跑完 start gate 後,先輸出 routing plan,等 routing 清楚後才實作。routing plan 至少包含:

  • source issue
  • 本 PR 明確不做
  • 讀資料 / GitHub metadata / CI readback 的 worker
  • 實作 worker
  • 驗證 worker
  • controller 保留的決策
  • planned validation
  • controller_fallback_reason, only if skipping worker/subagent

預設分工:

Work typeDefault route
GitHub issue / PR / branch / label / CI / review readbackops_spark or equivalent low-cost worker
docs / PR template / workflow regression / narrow testsGPT-5.4 worker
backend / frontend implementationGPT-5.4 domain worker, with controller review
schema / migration / auth / wallet / ledger / money / permission modelGPT-5.5 controller or high-reasoning worker review
scope / architecture / review decision / merge gateGPT-5.5 controller

0-3 分鐘的單一 read-only trivial check 可以由 controller 做,但必須在 routing plan 或 PR body 寫明 controller_fallback_reason

6. Implementation Rules

  • 從最新 develop 開 branch。
  • 保持 PR 對齊單一 source issue;額外想法開 follow-up issue / PR。
  • 不把 docs / research draft 當成 implementation source of truth。
  • worker 完成後,controller 必須 read back diff / tests / output,不直接相信摘要。
  • 不需要的 worker session 要 close;若 stale handle / not found,記錄原因。

7. Commit Gate

commit 前執行:

spec workflow-check --repo . --phase commit --pr-body <path-to-pr-body> \
--routing-evidence <path-to-routing-evidence.json> \
--finding-disposition <path-to-finding-disposition.json> \
--threshold-evidence <path-to-threshold-evidence.json>
git diff --check

這些 evidence JSON 是 local-only。PR body 只放 status + ref,不得把 full spec output、routing JSON、finding matrix、private context 或 task package commit 進 repo。

spec workflow-check 不可用,至少檢查:

  • PR body 已從 .github/PULL_REQUEST_TEMPLATE.md 完整填寫。
  • Source of truthDepends on PR本 PR 明確不做 已填。
  • autonomous PR 已填 Delegation Execution LogReview conversation closeoutFinal merge gate
  • 沒有 staged .spec-injector/、spec output、private context 或 task package。
  • commit message 包含 refs #<issue-number>

8. PR Gate

開 PR 時:

  • 未取得使用者對「開 PR / 公開遠端變更」的明確授權前,只能保留 local evidence / readback,不得建立 PR 或修改遠端 PR metadata。
  • PR title 使用 repo prefix,例如 [infra] ...[discussion] ...
  • PR body 必須從 .github/PULL_REQUEST_TEMPLATE.md 填,不使用自由格式。
  • Initial PR body 要完整;尚未穩定欄位可填 pending with reasonn/a
  • spec workflow-check evidence 只放 status + ref;完整三段細節放 PR comment / issue comment / local-only evidence summary。
  • normal non-autonomous PR 可填 n/a,不需要 AWP worker profile。

9. Review Triage Gate

Automated review finding 不能照單全收。每個 finding 先判斷:

  • 是否仍對 latest head 成立。
  • 是否 duplicate / outdated。
  • 是否在 source issue scope 內。
  • 是否需要 root-cause / state-model,而不是再補一個局部 patch。
  • 是否讓 follow-up patch 超過原 PR diff 約 25-30%,需要拆 PR。

Final closeout 必須把 finding 分成:

  • adopted
  • partial
  • rejected
  • deferred

並在 PR body 的 review_triage_refroot_cause_gate_reffinding_disposition_ref 留 latest-head evidence ref。

10. Merge Gate

merge 前執行:

  • 未取得使用者對「merge / 合併遠端狀態變更」的明確授權前,只能做 local evidence / readback,不得執行 merge 或替代性遠端合併操作。
spec workflow-check --repo . --phase merge --pr-body <path-to-pr-body> \
--head-sha <latest-head-sha> \
--pr <number-or-url> \
--routing-evidence <path-to-routing-evidence.json> \
--finding-disposition <path-to-finding-disposition.json> \
--threshold-evidence <path-to-threshold-evidence.json>

spec workflow-check 不可用,至少 fresh readback:

  • exact latest head SHA
  • base branch and mergeability
  • CI / required checks
  • PR Scope Police
  • review threads unresolved count
  • CodeRabbit latest-head state
  • chatgpt-codex-connector latest-head comment / review / reaction
  • PR body final closeout

final closeout 只在狀態穩定後更新一次。ready-to-merge closeout 不可留下裸 pending 或 unresolved actionable finding。

11. Post-merge Closeout

merge 後:

  • 若使用者已明確授權 closeout 公開狀態變更,在 source issue 留 proof comment。
  • 若使用者已明確授權 closeout 公開狀態變更,close source issue as completed, unless it is intentionally long-lived tracking / ledger.
  • 若本 PR 是 autonomous workflow dogfood,將 threshold calibration 短紀錄留在 #664 ledger issue comment;不要把 metrics 展開進 PR body 或專案檔案。
  • 不刪 branch / worktree,除非使用者明確要求 cleanup。

12. First Reply Template

AI 讀完本文件後,第一輪回覆應包含:

我已讀 docs/ai/autonomous-bootstrap.md,接下來會讀 mandatory read set、確認 repo 狀態、跑 spec-injector start gate,然後輸出 routing plan。

目前先做 read-only preflight:
- cwd:
- branch:
- dirty state:
- target base:
- source issue:
- duplicate PR / branch:
- spec-injector:
- controller_fallback_reason: <只有不派 worker 時才填>

如果任一必要資訊缺失,先補 readback 或回報 blocker,不要開始實作。