homunculus-code 0.1.0

package/examples/reference/evolved-skills/multi-agent-design-patterns.md

@@ -0,0 +1,259 @@
+# Skill: Multi-Agent Design Patterns
+
+**Version:** 1.2
+**Evolved from:** 6 instincts (parallel-agent-task-distribution-2026, parallel-agents-git-coordination-2026, direnv-worktrees-parallel-agents-2026, mechanical-agent-responsibility-isolation-2026, agentic-engineering-patterns-2026, autonomous-agent-reliability-2026)
+**Confidence threshold:** 0.75–0.92
+**Created:** 2026-03-19
+**Use when:** 設計多 agent 架構：平行任務分配、subagent dispatch 條件、worktree 隔離、orchestration 反模式識別
+
+## 目的
+
+設計、協調多 agent 系統的通用指引。適用於：平行 agent 任務分配、長時間自主 agent 可靠性、agent 職責隔離、多 agent 環境配置。
+
+---
+
+## Pattern 1：去中心化任務分配（Parallel Agents）
+
+**問題**：多個 agent 同時執行時，如何避免重複認領同一任務？
+
+### 方案：File Lock + Git Push
+```
+任務宣告流程：
+1. agent 寫檔案到 current_tasks/<task-id>.lock（含 agent_id + timestamp）
+2. git add + commit + push
+3. 若 push 失敗（競爭衝突）→ git pull → 檢查 current_tasks/ → 換選下一個任務
+4. 任務完成 → 刪除 lock 檔 + commit
+```
+
+### 有機專業化（Emergent Specialization）
+- **不要預先指定分工**，讓 agent 依 repo 狀態自然分化
+- 16 agent 建 C compiler 案例：自然出現「實作者、去重者、效能優化者、文件維護者」角色
+- 強制指定分工反而降低彈性
+
+### Oracle-driven 解除卡頓
+當所有 agent 被同一個 bug 卡住時：
+1. 引入外部 oracle（如 GCC 編譯結果、CI 測試輸出）
+2. 把 oracle 輸出拆分為 per-agent 的獨立子任務
+3. 恢復平行性
+
+---
+
+## Pattern 2：Git-Based 任務協調細節
+
+```bash
+# Agent 認領任務
+TASK_ID="fix-memory-leak-str.c"
+AGENT_ID="agent-$(uuidgen | head -c 8)"
+
+# 宣告認領
+echo "{\"agent\":\"$AGENT_ID\",\"started\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
+  > current_tasks/${TASK_ID}.lock
+git add current_tasks/ && git commit -m "claim: $TASK_ID by $AGENT_ID" && git push
+
+# 若 push 失敗（conflict）
+if git pull --rebase; then
+  # 檢查是否被搶先
+  if [ -f "current_tasks/${TASK_ID}.lock" ]; then
+    # 已被其他 agent 認領，選下一個任務
+    select_next_task
+  fi
+fi
+
+# 任務完成
+rm current_tasks/${TASK_ID}.lock
+git commit -am "done: $TASK_ID" && git push
+```
+
+**適用場景**：多個 Claude Code agent 在不同 worktree 並行工作、夜間批量任務分配。
+
+---
+
+## Pattern 3：平行 Agent 環境配置（direnv + Worktrees）
+
+**問題**：`git worktree add` 新 worktree 後，`.env` / API keys / local config 遺失。
+
+### 解法：direnv `.envrc` 共享引用
+
+在 repo 根目錄建立 `.envrc`（加入 `.gitignore`）：
+```bash
+# .envrc（不 commit）
+export ANTHROPIC_API_KEY="sk-ant-..."
+export DATABASE_URL="postgresql://localhost:5432/mydb"
+
+# 讓所有 worktree 共用同一個 .venv
+export VIRTUAL_ENV="$(git rev-parse --show-toplevel)/.venv"
+export PATH="$VIRTUAL_ENV/bin:$PATH"
+```
+
+每個 `git worktree add` 後，`.envrc` 自動生效（direnv hook）：
+- worktree 繼承主 repo 的環境變數
+- 無需手動複製 `.env` 檔案
+
+**搭配 CC v2.1.76 的 `worktree.sparsePaths`**（monorepo 優化）：
+```json
+// .claude/settings.json
+{
+  "worktree": {
+    "sparsePaths": ["src/", "tests/", "package.json"]
+  }
+}
+```
+
+---
+
+## Pattern 4：Agent 職責隔離原則
+
+### 機械式 Agent vs 決策 Agent
+
+| 類型 | 職責 | 典型任務 |
+|------|------|---------|
+| **機械式 Agent** | 確定性轉換 | JSON 格式轉換、schema 驗證、markdown 提取 |
+| **決策 Agent** | 判斷與過濾 | 優先級排序、合理性評估、去重 |
+
+**關鍵原則**：機械式 agent 不應包含任何決策邏輯。
+
+```
+❌ 錯誤設計：summarizer agent 同時負責「提取 + 去重 + 優先排序」
+✅ 正確設計：
+  - summarizer（機械式）：提取所有 JSON → 輸出完整列表
+  - reviewer（決策）：由人工或決策 agent 過濾
+```
+
+**為什麼重要**：混入決策邏輯的機械式 agent 難以 debug（「它為什麼漏掉這條」），且無法在不同 context 下重用。
+
+---
+
+## Pattern 5：自主 Agent 可靠性
+
+### 模型選擇（長時間 Loop）
+- **Opus 4.6**：✅ 穩定遵守「LOOP FOREVER」指令（Karpathy 118 次實驗驗證）
+- **較弱模型**：❌ 長時間後可能無法維持指令遵循
+
+→ 長時間夜間 agent 應使用 Opus/Sonnet，不用 Haiku
+
+### Context Compression 邊界
+在自然任務邊界點做 compact，不要等到 token 耗盡：
+```
+一個里程碑完成 → compact → 繼續下一個
+（不要連續跑直到 context 爆掉）
+```
+
+### 外部記憶持久化（SHARED_TASK_NOTES 模式）
+長時間 agent 必須維護外部狀態檔案（不只依賴對話記憶）：
+
+```markdown
+# TASK_PROGRESS.md（agent 每輪更新）
+
+## 已完成
+- [x] 分析 9 個 API instincts → 提煉為 skill
+- [x] 執行 eval：3/3 PASS
+
+## 當前狀態
+研究 multi-agent patterns 中...
+
+## 下一步
+1. 寫 skill 檔案
+2. 建立 eval spec
+3. 更新 MEMORY.md
+```
+
+**量化依據**：IBM 研究（2026）：agent 記憶萃取讓任務完成率 69.6% → 73.2%（+3.6%）
+
+### Tool 描述品質 = 可靠性槓桿
+- Tool 文件越精確，agent 成功率越高（Trace-Free+ 100+ tools 研究）
+- 定期審查 instinct 的「觸發條件」，確保描述精準
+- 考慮讓 agent 自動重寫/改進 tool 文件
+
+---
+
+## Pattern 6：Agentic Engineering 最佳實踐
+
+### Simon Willison 三原則（2026 現場驗證）
+
+1. **先讓 agent 探索工具**：
+   ```
+   Use `uvx my-tool --help` to learn about these tools first.
+   ```
+   - 不要假設 agent 知道私有/新工具的用法
+
+2. **TDD + Agent = 最佳組合**（Pragmatic Summit 2026）：
+   - 「Tests are no longer even remotely optional」
+   - 先要求 agent 寫 failing tests → 再實作 → red-green
+   - Tests 讓 agent 保持正確方向，成本接近零
+
+3. **複合工程迴圈（Compound Engineering Loop）**：
+   ```
+   任務完成 → retrospective → 文件「什麼有效」
+                                   ↓
+                              注入未來 agent 指令（instincts/skills）
+   ```
+   - 每次互動都累積在 knowledge base 中
+   - J-Assistant 的 nightly instinct evolve 是這個原則的系統化實作
+
+### Agent-friendly 輸出格式
+多 agent 協作時，log 格式很重要：
+```bash
+# ✅ Agent 可自動解析
+ERROR: file.c:42: undefined variable 'foo'
+TASK_COMPLETE: fix-memory-leak-str.c
+
+# ❌ Agent 難以處理
+Something went wrong somewhere in the file maybe around line 40ish
+```
+
+---
+
+## Pattern 7：Writer/Reviewer 雙 Session
+
+降低自我確認偏誤（confirmation bias）的核心模式。
+
+### 方案：Session A 實作 → Session B 全新 context 做 review
+
+```
+Session A（Writer）：
+  claude -p "Implement feature X" --allowedTools "Edit,Write,Bash"
+  → 產出 code changes
+
+Session B（Reviewer）：
+  claude -p "Review the changes in @src/feature.ts" --allowedTools "Read,Grep,Glob"
+  → 全新 context，不帶 Session A 的決策偏見
+```
+
+### 為什麼有效
+- Session A 做完決策後，會傾向「確認自己的選擇是對的」
+- Session B 從零開始看 code，更容易發現 A 忽略的問題
+- Claude Code 官方最佳實踐（Section 16: Advanced Workflows）
+
+### 使用時機
+- 重要功能的 code review（不是 typo fix）
+- 涉及安全、認證、資料庫 schema 等高風險改動
+- forge-dev review 階段可考慮用獨立 session 驗證
+
+### 注意事項
+- Reviewer session 應**只有唯讀工具**（Read/Grep/Glob），不改 code
+- 也可以反過來：A 寫測試 → B 寫實作（TDD 變體）
+
+---
+
+## 設計反模式
+
+- ❌ **過度中心化**：用一個 orchestrator 管理所有 agent 任務（bottleneck + single point of failure）
+- ❌ **硬編碼分工**：預先指定每個 agent 的角色（限制有機專業化）
+- ❌ **機械式 agent 加入決策邏輯**（難以 debug 和重用）
+- ❌ **不維護外部記憶**：只依賴對話歷史（compact 後遺失上下文）
+- ❌ **跳過 tool 探索**：假設 agent 知道所有工具的用法
+- ❌ **過度分派 subagent**：root agent 有足夠 token 時仍強制 dispatch subagent。
+  Subagent 的核心價值是「保護 root context window」，不是分工。
+  判斷準則：root agent 仍有 >40% context 空間 → 直接處理；
+  否 → 考慮 dispatch（新 context window + 隔離 token 預算）。
+  （Simon Willison，2026-03-17：「The main value of subagents is preserving the root context, not specialization」）
+
+---
+
+## 觸發場景
+
+- 設計多個 Claude agent 並行工作的架構
+- 夜間 batch 任務需要平行化
+- 長時間自主 agent 出現可靠性問題
+- 機械式 agent（summarizer/extractor）需要與決策 agent 分離
+- 新專案引入 agent 輔助開發，選擇合適的 TDD 和 review 流程

package/examples/reference/evolved-skills/shell-automation-patterns.md

@@ -0,0 +1,347 @@
+# Skill: Shell Automation Patterns
+
+**Version:** 1.6
+**Icon:** lightning
+**Abbr:** Shell
+**Evolved from:**
+- `discord-as-primary-output.md` (0.95)
+- `claude-print-in-shell-scripts.md` (0.85)
+- `jq-state-management.md` (0.85)
+- `gog-for-google-workspace.md` (0.90)
+- `playwright-usage-check.md` (0.88)
+- `modular-autodiscovery-pattern.md` (0.80)
+- `jq-jsonl-stream-parsing.md` (0.90)
+- `jq-null-safety-diagnostic-cycle.md` (0.85)
+- `jq-reduce-scope-trap.md` (0.85)
+**Evolved:** 2026-03-14 night agent (v1.4)
+**Use when:** 撰寫 shell 自動化腳本：launchd plist、jq 狀態管理、Claude CLI headless、Discord webhook、JSONL 串流解析、macOS zsh 模式
+
+## 用途
+
+這個 skill 涵蓋 Javan 在 shell script 自動化中反覆使用的核心模式。
+適用於設計或擴充 cron job、heartbeat checks、daily-news 等系統。
+
+---
+
+## 模式 1：Discord Webhook 輸出
+
+```bash
+WEBHOOK_URL="$DISCORD_WEBHOOK"  # 從環境變數取得
+
+send_discord() {
+  local msg="$1"
+  # 分塊處理（2000 字元限制）
+  while [[ ${#msg} -gt 1900 ]]; do
+    chunk="${msg:0:1900}"
+    msg="${msg:1900}"
+    curl -s -X POST "$WEBHOOK_URL" \
+      -H "Content-Type: application/json" \
+      -d "{\"content\": $(echo "$chunk" | jq -Rs .)}"
+  done
+  curl -s -X POST "$WEBHOOK_URL" \
+    -H "Content-Type: application/json" \
+    -d "{\"content\": $(echo "$msg" | jq -Rs .)}"
+}
+```
+
+**規則：**
+- 夜間（01:00-07:00）不推送 Discord
+- 錯誤 log 寫入檔案，不推 Discord
+- 2000 字元需分塊
+
+---
+
+## 模式 2：Claude --print AI 處理
+
+```bash
+process_with_claude() {
+  local input_file="$1"
+  local prompt_file="$2"
+  local log_file="$3"
+
+  RESULT=$(unset CLAUDECODE; claude --print \
+    --system-prompt "$(cat "$prompt_file")" \
+    --model claude-sonnet-4-6 \
+    < "$input_file" \
+    2>>"$log_file")
+
+  echo "$RESULT"
+}
+```
+
+**規則：**
+- 必須 `unset CLAUDECODE`
+- stdin 傳入（`< file`）
+- 模型固定 `claude-sonnet-4-6`
+- 檢查 exit code：`|| { log "claude --print failed"; return 1; }`
+- 長時間呼叫加 timeout：`timeout 300 claude --print ...`
+- 輸出可能為空，使用前先檢查 `[[ -n "$RESULT" ]]`
+
+---
+
+## 模式 3：jq JSON 狀態管理
+
+```bash
+STATE_FILE="path/to/state.json"
+
+# 讀取
+VALUE=$(jq -r '.key // empty' "$STATE_FILE")
+
+# 原子更新（含 trap EXIT 清理）
+TMPFILE=$(mktemp)
+trap "rm -f $TMPFILE" EXIT  # 必須在 mktemp 後立即設！確保中斷時 tmpfile 被清理
+jq --arg val "$VALUE" '.key = $val' "$STATE_FILE" > "$TMPFILE" \
+  && mv "$TMPFILE" "$STATE_FILE"
+```
+
+**規則：**
+- 永遠用 tmpfile 做原子更新
+- **mktemp 後立即加 `trap "rm -f $TMPFILE" EXIT`**（不然 script 中斷會留下 /tmp/ 殘留）
+- trap 放在 mktemp 之後（mktemp 之前 $TMPFILE 未定義，trap 觸發會報錯）
+- `EXIT` 比 `ERR` 更完整：ERR 不捕捉 kill 信號，EXIT 涵蓋所有結束情況
+- 讀取時用 `// empty` 設預設值
+
+---
+
+## 模式 4：gog CLI 操作 Gmail
+
+```bash
+# 搜尋
+gog gmail search "is:unread" --account starpincer@gmail.com
+
+# 讀取
+gog gmail message get "$MSG_ID" --account starpincer@gmail.com
+
+# 標記已讀
+gog gmail message modify "$MSG_ID" \
+  --remove UNREAD \
+  --account starpincer@gmail.com \
+  --no-input
+```
+
+**規則：**
+- Gmail 帳號固定 `starpincer@gmail.com`
+- cron job 中不用 MCP，用 gog
+
+---
+
+## 模式 5：模組化自動發現
+
+```bash
+MODULES_DIR="$SCRIPT_DIR/checks"
+
+for module in "$MODULES_DIR"/*.sh; do
+  [[ -f "$module" ]] || continue
+  # 透過環境變數傳遞 context
+  export CONTEXT_VAR="$value"
+  result=$(zsh "$module" 2>/dev/null) || continue
+  # 處理 JSON 輸出
+  echo "$result" | jq -r '.key // empty'
+done
+```
+
+**規則：**
+- 每個模組透過環境變數接收輸入
+- 透過 stdout 輸出 JSON
+- 模組失敗不中斷整體流程（`|| continue`）
+- 錯誤輸出導向 log：`2>>"$LOG_FILE"`
+- 失敗時記錄哪個模組失敗：`log "WARN: $module_name failed"`
+
+---
+
+## 模式 6：Playwright 使用量監控
+
+```bash
+# 取得使用率
+USAGE_RESULT=$(cd ~/assistant/heartbeat && node check-usage.js 2>/dev/null)
+USAGE_PCT=$(echo "$USAGE_RESULT" | jq -r '.percentage // empty')
+USAGE_DAY=$(echo "$USAGE_RESULT" | jq -r '.days_into_week // empty')
+
+# 計算預算（線性增長，週限額 80%）
+USAGE_BUDGET=$(awk "BEGIN {printf \"%.1f\", ($USAGE_DAY / 7) * 80}")
+
+# 判斷是否超預算
+if (( $(echo "$USAGE_PCT > $USAGE_BUDGET" | bc -l) )); then
+  echo "Over budget"
+fi
+```
+
+---
+
+---
+
+## 模式 7：JSONL 事件流解析
+
+Claude SDK session log 是 JSONL 格式，用 `select()` 過濾事件：
+
+```bash
+SESSION_LOG="path/to/session.jsonl"
+
+# 從 session 結果中提取統計
+CLAUDE_COST=$(jq -r 'select(.type=="result") | .total_cost_usd // 0' "$SESSION_LOG" 2>/dev/null | tail -1)
+CLAUDE_TURNS=$(jq -r 'select(.type=="result") | .num_turns // "?"' "$SESSION_LOG" 2>/dev/null | tail -1)
+CLAUDE_STOP_REASON=$(jq -r 'select(.type=="result") | .subtype // .stop_reason // "unknown"' "$SESSION_LOG" 2>/dev/null | tail -1)
+
+# 監控 session 進度
+LAST_TOOL=$(jq -r 'select(.type=="tool_use") | .tool_name // empty' "$SESSION_LOG" 2>/dev/null | tail -1)
+```
+
+**規則：**
+- `2>/dev/null` 避免解析錯誤的行產生 stderr
+- `tail -1` 取最後一個 result 事件
+- `// fallback` 處理 null/missing 欄位
+
+**常見 JSONL 事件類型：**
+- `tool_use` — Claude 呼叫工具
+- `tool_result` — 工具回傳結果
+- `result` — session 結束摘要（cost、turns、stop_reason）
+
+---
+
+---
+
+## 模式 8：多步驟 Claude 腳本（--resume + --json-schema）
+
+多個 claude 呼叫共用 session context，或要求結構化輸出：
+
+```bash
+# 步驟 1：分析 + 取得 session_id
+SESSION=$(unset CLAUDECODE; claude --print \
+  --output-format json \
+  --model claude-haiku \
+  --no-session-persistence \
+  "分析以下代碼並找出 TODO 列表：$(cat src/main.go)" \
+  | jq -r '.session_id')
+
+# 步驟 2：接續 session context 做後續處理
+RESULT=$(unset CLAUDECODE; claude --print \
+  --output-format json \
+  --resume "$SESSION" \
+  "根據剛才的 TODO 列表，產出優先級排序的 JSON" \
+  | jq -r '.result')
+```
+
+**結構化輸出（--json-schema）：**
+```bash
+STRUCTURED=$(unset CLAUDECODE; claude --print \
+  --output-format json \
+  --json-schema '{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}}}' \
+  "列出前 5 個最重要的安全漏洞" \
+  | jq '.structured_output.items[]')
+```
+
+**工具限制（fan-out 安全模式）：**
+```bash
+for file in $(cat files.txt); do
+  unset CLAUDECODE
+  claude --print \
+    --allowedTools "Edit,Bash(git add *),Bash(git commit *)" \
+    "遷移 $file 到新架構" &   # 平行執行
+done
+wait
+```
+
+**規則：**
+- `--no-session-persistence` 用於 CI/CD（不存 session 記錄）
+- `--resume` 需要 session_id，從 `jq -r '.session_id'` 取得
+- `--allowedTools` 比 `--disallowedTools` 更嚴格（白名單優先）
+- 平行 fan-out 時每個 claude 呼叫要 `unset CLAUDECODE`
+
+---
+
+## 決策樹：選擇輸出方式
+
+```
+需要輸出給用戶？
+├── 白天（07:00-01:00）→ Discord webhook
+├── 夜間（01:00-07:00）→ 寫入 night-report.md，等早上
+└── 錯誤訊息 → 寫入 log 檔
+```
+
+## 決策樹：選擇工具
+
+```
+需要 AI 處理？
+├── 在 session 內 → 直接使用 Claude Code
+└── 在 cron/shell script 中 → claude --print (unset CLAUDECODE)
+
+需要操作 Gmail？
+├── 在 session 內（互動） → Gmail MCP
+└── 在 cron/shell script 中 → gog CLI
+
+需要處理 JSON？
+├── 簡單讀寫 → jq
+└── 複雜轉換 → Python
+```
+
+---
+
+## Pattern 9：jq 錯誤防護與除錯迴圈
+
+**來源：** `jq-null-safety-diagnostic-cycle.md` + `jq-reduce-scope-trap.md`
+
+### Null Safety（最常見錯誤）
+
+```bash
+# ❌ .history 為 null 時崩潰
+jq '.history[] | .value' state.json
+
+# ✅ 加 ? 運算符，null 時跳過
+jq '.history[]? | .value' state.json
+
+# ✅ 讀取帶預設值（避免 null 傳播）
+VALUE=$(jq -r '.key // "default"' state.json)
+COUNT=$(jq '.items // [] | length' state.json)
+```
+
+### reduce 作用域陷阱
+
+```bash
+# ❌ reduce 內部 . 是 accumulator，不是原始 input
+reduce .goals[] as $goal ({}; .result = (.history[] | ...))
+
+# ✅ 先捕捉原始 input 為 $root
+. as $root |
+reduce .goals[] as $goal ({}; .result = ($root.history[] | ...))
+
+# ✅ 或改用 map + group_by 迴避 reduce
+jq '[.goals[] | {id: .id, value: .value}] | group_by(.id)' state.json
+```
+
+### 除錯迴圈
+
+jq 報錯時的標準步驟：
+1. 從錯誤訊息（`Cannot iterate over null`、`compile error`）定位代碼行
+2. 提取 jq 表達式，**單獨在 CLI 測試**：`echo '{"key":null}' | jq '.key[]?'`
+3. 識別問題類型：null context / macOS jq 版本限制 / reduce scope
+4. 修復 + 驗證整個 script 輸出結構
+
+### Pipe + Alternative 優先順序陷阱（`//` 陷阱）
+
+jq 的 `|` 和 `//` 優先順序容易誤判，導致靜默錯誤：
+
+```bash
+# ❌ 看起來是 "context 或 task"，實際解析卻不同：
+jq '.actions | map(...)[$i].context // .actions | map(...)[$i].task' f.json
+# 真實解析：.actions | (.context // .actions) | .task
+# 當 .context 非 null 字串時：後段 | map(...) 試圖 iterate 字串 → "Cannot iterate over string" 錯誤
+# 當 .context 為 null 時：返回整個 .actions 陣列，.task 取不到 → 空字串
+
+# ✅ 括號明確指定 alternative 範圍：
+jq '.actions | map(...)[$i] | (.context // .task)' f.json
+
+# ✅ 規則：// 兩側都要用括號保護，特別是左側含 | 的表達式
+VALUE=$(jq -r '.items[$i] | (.name // .id // empty)' state.json)
+```
+
+**實例（heartbeat.sh Bug C，2026-03-15）：** `system-maintenance.sh` 寫入 context 為 `"Trimmed observations.jsonl from 1146 to 500 lines"` 的 TODO action，heartbeat.sh 解析時觸發 `Cannot iterate over string ("Trimmed ob...")` jq error，在 launchd.err.log 持續出現。
+
+### macOS jq 版本注意
+
+```bash
+# macOS jq 1.7.1 不支援 try...catch，改用：
+jq '.field // empty' file.json 2>/dev/null || echo "fallback"
+
+# 安全讀取 JSONL（忽略解析失敗的行）
+jq -r 'select(.type=="result") | .value' log.jsonl 2>/dev/null | tail -1
+```