Skip to content

autonomous-bootstrap.md

Latest commit

 

History

History
271 lines (191 loc) · 10.6 KB

autonomous-bootstrap.md

File metadata and controls

271 lines (191 loc) · 10.6 KB

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 develop 或 main；日常 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.ts

若 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 plan、spec validate 作為暫時 evidence，但不得宣稱已跑完整 #242 workflow-check。

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

spec init --repo .

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

不得使用 curl | bash、wget | sh、npx、pnpm 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 type Default route
GitHub issue / PR / branch / label / CI / review readback ops_spark or equivalent low-cost worker
docs / PR template / workflow regression / narrow tests GPT-5.4 worker
backend / frontend implementation GPT-5.4 domain worker, with controller review
schema / migration / auth / wallet / ledger / money / permission model GPT-5.5 controller or high-reasoning worker review
scope / architecture / review decision / merge gate GPT-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 truth、Depends on PR、本 PR 明確不做 已填。
  • autonomous PR 已填 Delegation Execution Log、Review conversation closeout、Final 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 reason 或 n/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_ref、root_cause_gate_ref、finding_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，不要開始實作。