homunculus-code 0.1.0

package/examples/reference/evolved-skills/tdd-workflow.md

@@ -0,0 +1,272 @@
+# Skill: tdd-workflow
+**Version:** 1.2
+**Icon:** poison
+**Abbr:** TDD
+**Evolved from:** (manual — 參考 Affaan/everything-claude-code TDD Guide + aihero.dev TDD Skill，適配小J環境)
+**Created:** 2026-03-16
+**Use when:** Forge 任務寫測試、AC 對應 test case、紅綠迴圈執行、quest-board endpoint 測試、habit/forge API discriminator
+
+## 概述
+
+AC-driven 開發中的自動化測試層。AC 定義「什麼算完成」，TDD 提供「自動驗證做對了沒」的紅綠迴圈。
+
+**核心立場**：AC 是主人，測試是僕人。不是所有 AC 都能自動測試。
+
+---
+
+## 適用場景
+
+- 新增 API endpoint
+- 修 bug（先寫重現測試，再修）
+- 重構（先確保測試綠，改完仍綠）
+- 任何 Forge 任務中標記為 `[testable]` 的 AC
+
+**不適用**：UI 外觀、UX 體驗、文件撰寫 — 這些用 `[manual]` AC。
+
+---
+
+## 紅綠重構迴圈
+
+### Step 1: RED — 寫失敗的測試
+
+從 `[testable]` AC 出發，為每條寫一個測試：
+
+```javascript
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { request, backupState, restoreState } = require('./helpers');
+
+describe('POST /api/forge/review', () => {
+  before(() => backupState());
+  after(() => restoreState());
+
+  it('returns verdict field in response', async () => {
+    const { status, data } = await request('POST', '/api/forge/review', {
+      id: 'r17',
+      ac_results: [{ criterion: 'test', passed: true }],
+    });
+    assert.strictEqual(status, 200);
+    assert.ok(data.verdict, 'response should contain verdict');
+  });
+
+  it('returns 400 when id is missing', async () => {
+    const { status } = await request('POST', '/api/forge/review', {
+      ac_results: [],
+    });
+    assert.strictEqual(status, 400);
+  });
+});
+```
+
+### Step 2: 確認 RED
+
+```bash
+node --test tests/<task-id>.test.js
+# 預期：全部失敗（因為功能還沒實作）
+```
+
+如果測試意外通過 → 測試寫錯了（太寬鬆），或功能已存在。
+
+### Step 3: GREEN — 最少 code 讓測試過
+
+只寫剛好能通過測試的 code。不多做。
+
+### Step 4: 確認 GREEN
+
+```bash
+node --test tests/<task-id>.test.js
+# 預期：全部通過
+```
+
+### Step 5: REFACTOR — 保持綠燈
+
+重構 code，每改一步就跑測試。測試變紅 = 改壞了，回退。
+
+---
+
+## 測試 Pattern
+
+### Pattern A：API Endpoint 測試
+
+最常用。HTTP request → assert response status + body。
+
+```javascript
+it('POST /api/quest/add creates a task', async () => {
+  const { status, data } = await request('POST', '/api/quest/add', {
+    title: 'test-quest',
+  });
+  assert.strictEqual(status, 200);
+  assert.ok(data.task, 'should return created task');
+  assert.strictEqual(data.task.title, 'test-quest');
+});
+```
+
+### Pattern B：State 持久化測試
+
+操作後直接讀 state.json 驗資料一致性。
+
+```javascript
+it('completing quest adds XP to player', async () => {
+  const before = readState();
+  await request('POST', '/api/quest/complete', { id: 'r1' });
+  const after = readState();
+  assert.ok(after.player.xp > before.player.xp, 'XP should increase');
+});
+```
+
+### Pattern C：Shell Script 測試
+
+驗 exit code + stdout，不驗內部實作。
+
+```javascript
+const { execSync } = require('child_process');
+
+it('heartbeat.sh exits 0 on success', () => {
+  const result = execSync('zsh ~/assistant/heartbeat/heartbeat.sh 2>&1', {
+    timeout: 30000,
+    encoding: 'utf8',
+  });
+  // 驗 output 格式，不驗具體內容
+  assert.ok(result.includes('[') || result.length > 0);
+});
+```
+
+### Pattern D：JSON Schema 驗證
+
+確認 state.json 必要欄位存在。
+
+```javascript
+it('state.json has required structure', () => {
+  const state = readState();
+  assert.ok(state.player, 'missing player');
+  assert.ok(Array.isArray(state.tasks), 'tasks should be array');
+  assert.ok(typeof state.player.xp === 'number', 'xp should be number');
+  assert.ok(typeof state.player.gold === 'number', 'gold should be number');
+});
+```
+
+---
+
+## State 隔離
+
+**每個 test suite 必須隔離 state**，避免互相污染：
+
+```javascript
+before(() => backupState());   // 備份
+after(() => restoreState());   // 還原
+```
+
+`helpers.js` 的 `backupState()`/`restoreState()` 用 file copy 實作，簡單可靠。
+
+**注意**：`helpers.js` 使用 pid-unique backup（`state.test-backup-<pid>.json`），多數測試可並發跑。
+但若測試需要直接寫 state.json（如 habit 測試，無對應 API），必須用 `--test-concurrency=1`：
+
+```bash
+# 一般情況（大多數 API 測試，pid-unique backup 已解決 race）：
+node --test tests/*.test.js
+
+# 含直接寫 state.json 的測試時：
+node --test --test-concurrency=1 tests/*.test.js
+```
+
+⚠️ `--concurrency=1` 不是有效的 node:test flag，正確是 `--test-concurrency=1`（Node.js v22+）。
+
+---
+
+## Session Start Pattern（既有專案）
+
+**觸發**：接手或繼續有測試基礎的既有專案（非全新 Forge 任務）。
+
+先跑現有測試，再開始任何改動：
+```bash
+node --test quest-board/tests/*.test.js  # 或對應的測試命令
+```
+
+**三個目的（Simon Willison, 2026-03）**：
+1. 確認 agent 知道如何跑測試（為後續改動建立習慣）
+2. 提供專案脈絡（測試本身就是功能規格）
+3. 建立基線 — 知道改動前幾個測試通過，才能確認改動後不退步
+
+---
+
+## Anti-Patterns
+
+### ❌ 不 mock server
+quest-board 是我們自己的服務，直接測真實 server。Mock 會隱藏真實問題。
+
+### ❌ 不測 UI render
+沒有前端框架，UI 驗證用 `[manual]` AC + Playwright 截圖。
+
+### ❌ 不追求 100% 覆蓋
+單人系統，核心 API 80% 覆蓋即可。邊界情況按風險決定。
+
+### ❌ 不改測試來通過
+RED 階段寫完的測試就是規格。如果測試過不了，改 code 不改 test。除非 AC 本身定義有誤。
+
+### ❌ 不在測試中驗內部狀態
+```javascript
+// ❌ 測內部實作
+assert.strictEqual(server._handlers.length, 5);
+
+// ✅ 測可觀察行為
+const { status } = await request('GET', '/api/health');
+assert.strictEqual(status, 200);
+```
+
+---
+
+## 測試品質標準
+
+1. **測行為不測實作** — assert response / output，不 assert internal state
+2. **每個測試獨立** — backup/restore 隔離，不依賴執行順序
+3. **測試名 = 規格** — `it('returns 400 when id is missing')` 讀起來就是需求
+4. **邊界案例** — null / empty string / invalid type / 不存在的 id
+5. **錯誤路徑** — 測 4xx 回應，不只測 happy path
+
+---
+
+## 與 forge-dev 整合
+
+```
+/forge-dev define-ac <id>
+  → AC 標記 [testable] / [manual]
+
+/forge-dev gen-tests <id>
+  → 讀 [testable] AC → 生成 tests/<id>.test.js → 跑一次確認 RED
+
+/forge-dev start <id>
+  → 紅綠迴圈：實作 → node --test → 修到全綠
+
+/forge-dev review <id>
+  → 自動跑 node --test → ac_results 自動生成
+  → [manual] AC 仍用手動驗證（Read/curl/Glob）
+  → 混合結果合併計算 pass_rate
+```
+
+---
+
+## 夜間 Backfill
+
+夜間 agent 為既有 API 補測試：
+
+1. 掃描 server.js 的 endpoint → 比對 tests/ 已有覆蓋 → 產出缺口清單
+2. 每晚補 1-2 個 endpoint，優先：forge > quest > habit > state
+3. 新測試必須全綠且不破壞舊測試
+4. Night report 追蹤：「測試覆蓋：X/Y endpoints（Z%）」
+
+**Habit 測試特殊注意**：habit API 使用 `questId`（非 `id`），且 habits 在 `state.today.habits`。
+由於沒有 add-habit API，測試 setup 需直接注入 state.json → 須搭配 `--test-concurrency=1`。
+
+---
+
+## 選擇指引
+
+| 情境 | 做法 |
+|------|------|
+| 新 API endpoint | Pattern A（endpoint 測試）+ Pattern B（state 持久化） |
+| 修改既有 endpoint 格式 | 在**同一個 module 測試檔**（如 quest-api.test.js）中新增 assert，不建新檔 |
+| 修 API bug | 先寫重現 bug 的測試（RED）→ 修復 → GREEN |
+| 重構 server.js | 先確保所有現有測試 GREEN → 重構 → 仍 GREEN |
+| Shell script 修改 | Pattern C（exit code + stdout） |
+| state.json 結構變更 | Pattern D（schema 驗證） |
+| UI 相關變更 | 不寫測試，用 `[manual]` AC |

package/examples/reference/evolved-skills/workflows.md

@@ -0,0 +1,237 @@
+# Skill: Workflows
+
+**Version:** 1.2
+**Icon:** wind-1
+**Abbr:** Workflows
+**Evolved from:** Phase 1 Discord Bridge 開發中的架構領悟 — 「流程是知識，不是基礎設施」
+**Evolved:** 2026-03-14
+**Use when:** 判斷該用哪個標準 workflow：forge-dev 開發流、研究任務、skill evolution、系統性 debug vs 孤立 bug
+
+## 用途
+
+定義小J助理的常用工作流模板。當用戶觸發對應情境時，自動依循流程執行。
+Workflow 只定義**重複性流程**，一次性或高度隨機的互動不套用。
+
+---
+
+## 核心原則
+
+1. **流程是知識，不是程式碼**：不需要 workflow engine，agent 讀到就會做
+2. **只管步驟，不限細節**：每個步驟怎麼做由 agent 當下判斷
+3. **可跳步**：用戶明確說「不用 X」就跳過，不死板
+4. **自然演化**：用了幾次發現缺步驟或多餘步驟，直接更新此 skill
+
+## 使用追蹤
+
+**[MUST]** 完成任何 workflow 後，**靜默** POST 記錄（不需要告訴用戶）。這是數據驅動演化的基礎 — 沒有記錄就無法分析哪些 workflow 需要改進。
+
+```bash
+curl -sf http://localhost:3000/api/workflow/log -X POST -H 'Content-Type: application/json' -d '{
+  "workflow": "<workflow-id>",
+  "steps_completed": ["step1", "step2"],
+  "steps_skipped": ["step3"],
+  "outcome": "success|partial|failure|aborted"
+}' > /dev/null 2>&1
+```
+
+Workflow ID 對應：`research` / `study` / `feature-dev` / `project-init` / `learning-path` / `tech-eval` / `debug` / `daily-review`
+
+**Subagent tracking 已自動化**：observe.sh hook 在每次 Agent tool 呼叫後自動 POST `/api/subagent/log`，不需要手動記錄。
+
+---
+
+## Workflow 1：技術研究（Research）
+
+**觸發**：收到 URL、「研究 X」、「X 是什麼」、「幫我看看這個」
+
+**步驟**：
+1. 抓取/搜尋內容（WebFetch / WebSearch）
+2. 摘要：主題（1-2 句）+ 關鍵要點（3-5 點）+ 來源
+3. **Goal 適用性評估**：對照 `architecture.yaml` 目標樹，分類為：
+   - `[informational]` — 有趣但不直接影響系統
+   - `[adoptable]` — 可直接納入，標記 `affected_goals: [goal.path]`
+   - `[testable]` — 需實驗驗證，標記 `affected_goals` + 建議實驗
+   - `[irrelevant]` — 與系統目標無關
+4. 如果值得記住 → 更新 research-notes memory
+5. 如果 adoptable → 建議開 Forge（標明服務哪個 goal）
+6. 如果 testable → 建議實驗（寫入 experiments/queue.jsonl）
+7. **如果值得沉澱為知識** → 產出知識卡片到 `knowledge-cards/candidates/`（或用 `/study` 深度研究）
+
+**產出**：摘要回覆 + 分類標記 + 可選的 memory 更新 + 可選的行動建議 + 可選的知識卡片
+
+**判斷是否產出知識卡片**：
+- 有具體案例、數據、機制可拆解 → 產出卡片
+- 純概念問答或與 Javan 領域無關 → 不產出
+
+**不套用**：單純的「X 是什麼」知識問答（直接回答就好）
+
+---
+
+## Workflow 2：功能開發（Feature Dev）
+
+**觸發**：「做 X 功能」、「修這個 bug」、「加一個 API」、Forge 任務開發
+
+**步驟**：
+1. 讀取相關檔案，確認現有架構
+2. **前置評估** → `/forge-dev evaluate`（goal 定位 + impact 預判 + 成本合理性 → proceed/defer/reject）
+3. 如果是 Forge 且沒有 AC → `/forge-dev define-ac`（參考 evaluate 的預期變更清單，標記 `[testable]`/`[manual]`）
+4. **[optional]** 如果有 `[testable]` AC → `/forge-dev gen-tests`（生成測試，確認 RED）— 實際多數情況直接在紅綠迴圈中寫測試
+5. 實作改動（有測試 → 紅綠迴圈；無測試 → 直接實作）
+6. 語法預檢（`node -c`、`zsh -n`、`jq empty` 等）
+7. 服務重啟（如果改了跑中的服務）
+8. 端點/功能驗證：`[testable]` AC 跑 `node --test`、`[manual]` AC 手動驗證
+9. **系統整合** → `/forge-dev complete`（architecture.yaml + CLAUDE.md + health_check + test 指標同步）
+10. 回報結果
+
+**產出**：可用功能 + 測試通過 + 驗證結果 + 系統一致性確認
+
+**已有支撐**：`/forge-dev` command、`development-verification-patterns` skill、`tdd-workflow` skill
+
+---
+
+## Workflow 3：開啟項目（Project Init）
+
+**觸發**：「開個項目追蹤 X」、「我想長期做 X」、「這個值得開項目」
+
+**步驟**：
+1. 建立 `~/assistant/projects/{slug}/README.md`（目標、背景、里程碑）
+2. 建立 Forge 任務（或多個，依規模拆分）
+3. 問用戶要不要在 Discord 開 thread 做長期討論
+4. 更新 memory 索引（如果是重要項目）
+
+**產出**：項目目錄 + Forge 任務 + 可選的 Discord thread
+
+---
+
+## Workflow 4：學習計劃（Learning Path）
+
+**觸發**：「我想學 X」、「幫我規劃學 X」
+
+**步驟**：
+1. 快速研究 X 的學習路徑（搜尋 + 自身知識）
+2. 依照 Project Init workflow 建立項目
+3. 拆成 3-5 個里程碑（由淺到深）
+4. 建議第一步（具體、可執行）
+5. 設定 check-in 頻率（每週？每天？）
+
+**產出**：學習項目 + 里程碑 Forge + 第一步行動
+
+---
+
+## Workflow 5：技術評估（Tech Eval）
+
+**觸發**：「X 值得用嗎」、「X 跟 Y 比哪個好」、「要不要換成 X」
+
+**步驟**：
+1. 快速研究 X（官方文檔 + 社群評價）
+2. 跟現有系統/方案比較（功能、成本、複雜度）
+3. **Goal 適用性評估**：標記 `affected_goals` + 分類（adoptable/testable/informational）
+4. 明確結論：採用 / 不採用 / 觀望
+5. 如果採用 → 建議具體行動（Forge，標明服務哪個 goal）
+6. 記入 research-notes（不論結論，留作知識儲備）
+
+**產出**：評估結論 + 分類標記 + 行動建議 + memory 更新
+
+---
+
+## Workflow 6：系統除錯（Debug）
+
+**觸發**：「X 壞了」、「這個 error 怎麼回事」、服務異常
+
+**步驟**：
+1. 查看相關 log（`/tmp/*.log`、`heartbeat/logs/`）
+2. 定位根因（不要急著修，先理解）
+3. 修復
+4. 驗證修復有效
+5. 判斷是否系統性問題 → 決定是否加防護：
+
+   **系統性問題（應加防護）**：
+   - 邊界條件可重現：空檔案、null 值、網路逾時、並發衝突
+   - 根因是外部輸入或環境不確定性（非 typo）
+   - 影響多個呼叫路徑或會反覆觸發
+   - 例：空 state.json → `jq '.x // []'`；API timeout → retry + fallback
+
+   **孤立 bug（修完即可）**：
+   - 邏輯錯誤、typo、hardcoded 值錯誤
+   - 有明確的「不應該發生這種情況」的前提
+   - 修完後不會在正常使用中再次出現
+   - 例：API path 拼錯、filter 條件相反
+
+**產出**：問題修復 + 根因說明 + 可選的防護措施
+
+---
+
+## Workflow 7：每日回顧（Daily Review）
+
+**觸發**：夜間 heartbeat P1 / 用戶問「今天做了什麼」
+
+**步驟**：
+1. 讀取當天 session summaries
+2. 統計：sessions 數、工具使用、主要工作項目
+3. 評估未完成的任務，標記需延續的
+4. 識別可擷取的 instinct（信心 > 0.7）
+5. 寫入 night report 或直接回覆
+
+**產出**：回顧摘要 + instinct 候選
+
+---
+
+## 不適合 Workflow 的場景
+
+以下情境**不要套用 workflow**，直接靈活回應：
+- 一般閒聊、腦力激盪（`#general` 頻道日常）
+- 一次性快問快答（「X 多少錢」「翻譯這句」）
+- 大型架構決策（需要深度推理，固定步驟反而限制思考）
+- 跨 session 的開放式探索（沒有明確完成標準）
+
+---
+
+## Eval Spec
+
+### Scenario 1: URL 研究觸發
+**Input:** 用戶貼了一個技術文章 URL
+**Expected:** 依循 Workflow 1 — 摘要 + 關聯性評估 + 必要時更新 memory
+**Criteria:** 有摘要、有與系統關聯的評估、不做無謂的 Forge 建議
+**Rating:** ⭐ 完整流程 / ✅ 有摘要但缺評估 / ❌ 只貼連結內容
+
+### Scenario 2: 開項目請求
+**Input:** 「幫我開個項目追蹤 Rust 學習」
+**Expected:** 依循 Workflow 3+4 — 建目錄 + README + Forge + 里程碑 + 建議第一步
+**Criteria:** 有 projects/ 目錄、有 Forge 任務、有具體下一步
+**Rating:** ⭐ 完整 / ✅ 有目錄但缺里程碑 / ❌ 只回覆「好的」
+
+### Scenario 3: 技術評估
+**Input:** 「Bun 值得用來替換 Node 嗎？」
+**Expected:** 依循 Workflow 5 — 研究 + 比較 + 明確結論 + 行動建議
+**Criteria:** 有對比表、有結論、結論有理由支撐
+**Rating:** ⭐ 完整 / ✅ 有結論但缺比較 / ❌ 模糊回覆
+
+### Scenario 4: 不該套用 workflow
+**Input:** 「今天晚餐吃什麼好？」
+**Expected:** 直接輕鬆回答，不套用任何 workflow
+**Criteria:** 自然回覆、不出現「步驟 1」之類的結構
+**Rating:** ⭐ 自然回覆 / ❌ 硬套 workflow
+
+### Scenario 5: Debug 流程
+**Input:** 「heartbeat 好像沒有跑，幫我看看」
+**Expected:** 依循 Workflow 6 — 查 log → 定位 → 修復 → 驗證
+**Criteria:** 先查 log 不急著猜、修完有驗證
+**Rating:** ⭐ 完整 / ✅ 有修但沒驗證 / ❌ 盲猜修改
+
+### Scenario 6: 功能開發
+**Input:** 「在 Quest Board 加一個 /api/stats endpoint」
+**Expected:** 依循 Workflow 2 — 讀架構 → 實作 → 預檢 → 重啟 → 驗證
+**Criteria:** 有語法檢查、有服務重啟、有端點測試
+**Rating:** ⭐ 完整 / ✅ 能用但跳過驗證 / ❌ 寫完就走
+
+### Scenario 7: 案例研究產出知識卡片 (boundary)
+**Input:** 「研究這個：<URL to a detailed Stripe Agent Toolkit article>」
+**Expected:** 依循 Workflow 1 步驟 1-7 — 摘要 + 評估 + 產出知識卡片到 candidates/
+**Criteria:** 有卡片（正確 frontmatter + connections）、有確認摘要、卡片在 candidates/ 不在 cards/
+**Rating:** ⭐ 完整卡片+摘要 / ✅ 有摘要但沒產卡片 / ❌ 只貼內容
+
+### Scenario 8: 一般研究不產卡片 (boundary)
+**Input:** 「台灣明天天氣怎樣」
+**Expected:** 直接回答，不產出知識卡片
+**Criteria:** 不產出卡片、不走完整 research workflow
+**Rating:** ⭐ 直接回答 / ❌ 硬產卡片

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "homunculus-code",
+  "version": "0.1.0",
+  "description": "A self-evolving AI assistant that grows smarter every night",
+  "bin": {
+    "homunculus": "./bin/init.js"
+  },
+  "keywords": [
+    "ai",
+    "claude-code",
+    "self-evolving",
+    "ai-assistant",
+    "goal-tree",
+    "evolution"
+  ],
+  "author": "Javan <https://github.com/JavanC>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JavanC/Homunculus.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/CLAUDE.md.template

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}} — Homunculus-Powered AI Assistant
+
+You are an evolving AI assistant. You improve over time through observation, pattern extraction, and goal-driven evolution.
+
+---
+
+## Evolution System
+
+- **Goal Tree**: `architecture.yaml` defines what matters — all evolution decisions align with goals
+- **Instincts**: Auto-extracted behavioral patterns in `homunculus/instincts/personal/`
+- **Skills**: Tested, versioned knowledge in `homunculus/evolved/skills/`
+- **Eval Specs**: Scenario tests in `homunculus/evolved/evals/`
+
+### Memory Hierarchy (most to least persistent)
+1. `CLAUDE.md` + `rules/` — Always loaded, most authoritative
+2. `homunculus/evolved/skills/` — Loaded when relevant
+3. `homunculus/instincts/personal/` — Selected at session start
+
+### Evolution Commands
+- `/eval-skill` — Run scenario tests on a skill
+- `/improve-skill` — Auto-improve until eval passes
+- `/evolve` — Aggregate instincts into a skill
+
+---
+
+## Goals
+
+See `architecture.yaml` for the complete goal tree.
+
+---
+
+## Verification
+
+- Validate before committing: run tests, check syntax
+- Prefer fixing root causes over workarounds
+- When blocked, try alternative approaches before retrying

package/templates/architecture.template.yaml

@@ -0,0 +1,41 @@
+# architecture.yaml — Your goal tree
+# Each node is a GOAL, not a system. Systems are means to achieve goals.
+# The evolution system uses this to decide what to improve.
+#
+# Node schema:
+#   purpose:      Why this goal exists
+#   realized_by:  What implements it (file path, system, or description)
+#   metrics:      How to measure success [{name, source, healthy}]
+#   goals:        Sub-goals (recursive)
+#   health_check: Machine-executable check
+#                 - command:  shell command (exit 0 = healthy)
+#                 - expected: human-readable description
+
+version: "1.0"
+
+root:
+  purpose: "{{PROJECT_PURPOSE}}"
+
+  goals:
+    # === Add your goals below ===
+    # Example:
+    #
+    # code_quality:
+    #   purpose: "Write better, more maintainable code"
+    #   metrics:
+    #     - name: test_coverage
+    #       source: coverage report
+    #       healthy: "> 80%"
+    #   health_check:
+    #     command: "npm test 2>/dev/null; echo $?"
+    #     expected: "all tests pass"
+    #
+    # productivity:
+    #   purpose: "Complete tasks faster with fewer iterations"
+    #   goals:
+    #     task_completion:
+    #       purpose: "Finish tasks in fewer back-and-forth cycles"
+    #     tool_mastery:
+    #       purpose: "Use the right tool for the job on first try"
+
+    # Your goals here:

package/templates/rules/evolution-system.md

@@ -0,0 +1,29 @@
+# Evolution System (Homunculus)
+
+## Evolution Artifacts (all in `homunculus/evolved/`)
+
+| Artifact | Location | Evolution Method |
+|----------|----------|-----------------|
+| **Skills** | `evolved/skills/` | Instinct aggregation (`/evolve`), eval→improve loop |
+| **Agents** | `evolved/agents/` | Extract repetitive main-thread patterns into subagents |
+| **Evals** | `evolved/evals/` | Accompany each skill, scenario-based testing |
+
+## Evolution Flow
+
+```
+Observe (observations.jsonl) → Pattern detection (confidence > 0.7) → instincts/personal/*.md
+                                                                            ↓
+                                                               /evolve → evolved/skills/*.md
+                                                                            ↓
+                                                               eval → improve loop → 100% pass
+```
+
+## Manual Triggers
+- `/evolve` — Aggregate instincts into a skill
+- `/eval-skill` — Test a skill against its eval spec
+- `/improve-skill` — Auto-improve until eval passes
+
+## Automatic Maintenance
+- Instinct extraction from session observations
+- Instinct pruning (confidence decay, skill coverage check)
+- Skill eval → improve pipeline