@moon791017/neo-skills 1.1.8 → 1.1.10

package/README.md

@@ -11,7 +11,7 @@
 
 目前專案提供：
 
-- `skills/`：23 個內建專家技能。
+- `skills/`：內建多個專家技能。
 - `bin/install-skills.js`：同步技能到 Antigravity CLI 全域技能目錄。
 - `bin/install-system-instructions.js`：把系統提示詞安裝到 Claude Code、Copilot CLI、Codex 或 Antigravity 的指導檔。
 - `scripts/check-skills-syntax.py`：非互動式技能結構驗證工具。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "type": "module",
   "description": "Neo Skills: A Universal AI Agent Skills Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-agent-harness/SKILL.md

@@ -2,9 +2,11 @@
 name: neo-agent-harness
 description: >
   Use this skill when the user asks to improve AI-assisted development reliability,
-  AGENTS.md, skills, tests, CI, hooks, review loops, or agent workflow governance.
-  It designs feedforward guides, feedback sensors, verification gates, and human
-  decision points from repository evidence.
+  AGENTS.md, skills, tests, CI, hooks, review loops, agent workflow governance,
+  loop engineering, agent automations, worktree isolation, maker/checker separation,
+  or external state design for long-running agents.
+  It designs feedforward guides, feedback sensors, verification gates, human
+  decision points, and loop architectures from repository evidence.
 ---
 
 # Agent Harness Architect Skill
@@ -14,10 +16,17 @@ description: >
 - The user wants coding agents to be more reliable, safer, or easier to supervise.
 - The user asks for AGENTS.md, skills, tests, CI, hooks, review loops, or project rules to be planned together.
 - The task is about harness engineering, agent harnessability, feedback loops, or "humans on the loop".
+- The user wants to design scheduled automations, cron-driven agent loops, or recurring agent tasks.
+- The user wants multiple agents to work in parallel and needs an isolation strategy (worktree isolation).
+- The user wants to design maker/checker separation (generation and verification by different agents).
+- The user wants to design external memory or cross-conversation state persistence for agents.
+- The user asks how to evolve from a harness to loop-driven development.
 
 ## Core Principle
 Treat agent-assisted development as a controlled engineering system. Do not only improve prompts; design the guides, sensors, verification steps, and human decision points that let agents work with higher confidence.
 
+When the task involves automations, parallel agents, or continuous loops, extend the design to cover loop architecture: the scheduling, isolation, separation, integration, and state layers that let the harness run itself.
+
 Use this skill for planning first. Do not modify files unless the user explicitly asks for implementation after the harness plan is clear.
 
 ## Perceive
@@ -27,6 +36,9 @@ Use this skill for planning first. Do not modify files unless the user explicitl
    - Validation commands: `package.json`, `pyproject.toml`, `Makefile`, CI workflow files, build scripts.
    - Safety and governance: hooks, linters, formatters, secret scanners, dependency scanners.
    - Existing documentation: README, architecture docs, ADRs, testing docs, contribution docs.
+   - Agent definitions: `.codex/agents/`, `.claude/agents/`, subagent configs, agent team definitions.
+   - Automation and scheduling: cron configs, GitHub Actions workflows, hooks, `/loop` or `/goal` usage.
+   - State files: progress markdown, task boards, Linear integrations, cross-conversation state.
 2. Identify the project type, primary languages, current test surface, CI status, and release/deploy path.
 3. Separate discoverable repository facts from product or team preferences that require user confirmation.
 
@@ -48,8 +60,15 @@ Analyze the project through these dimensions:
    - Behaviour: requirements, acceptance criteria, user journeys, fixtures, manual test points.
 5. **Human role**
    - Move human effort from repeated low-level correction to high-value decisions: scope, product fit, risk acceptance, architectural tradeoffs, and harness evolution.
+6. **Loop design** (conditional: activate only when the task involves scheduled automations, parallel agents, or continuous loops)
+   - **Automations**: which tasks suit scheduled triggers? Frequency, trigger conditions, result routing (triage inbox vs auto-process).
+   - **Worktrees**: how to isolate parallel agents? Independent branches and working directories needed?
+   - **Maker/checker separation**: which steps need generation and verification by different agents? (For sub-agent definition and implementation, use the neo-sub-agent skill.)
+   - **Connectors**: which external tools does the loop need to reach? (issue tracker, CI, Slack, staging API, database)
+   - **State**: how to persist cross-conversation progress? Format (markdown / board / Linear)? Who updates it?
+   - **Loop risks**: assess comprehension debt, cognitive surrender, and unattended verification risk levels.
 
-For detailed patterns and examples, read [reference/harness-patterns.md](reference/harness-patterns.md) when the task needs a full harness design, maturity model, or improvement roadmap. For the complete source article synthesis behind this skill, read [reference/agent-harness-engineering.md](reference/agent-harness-engineering.md) only when deeper conceptual background is needed.
+For detailed patterns and examples, read [reference/harness-patterns.md](reference/harness-patterns.md) when the task needs a full harness design, maturity model, or improvement roadmap. For the complete source article synthesis behind this skill, read [reference/agent-harness-engineering.md](reference/agent-harness-engineering.md) only when deeper conceptual background is needed. For loop engineering patterns, the five loop primitives, risk model, and maturity guidance, read [reference/loop-engineering.md](reference/loop-engineering.md) when the task involves automations, parallel agents, maker/checker separation, or loop-driven development.
 
 ## Act
 Output in Traditional Chinese (Taiwan). Use this structure:
@@ -57,6 +76,7 @@ Output in Traditional Chinese (Taiwan). Use this structure:
 ### 1. 現況盤點
 - Summarize the repository facts discovered.
 - Mention the current guides, sensors, and missing signals.
+- If loop-relevant infrastructure exists (automations, agent definitions, state files), include it here.
 
 ### 2. Harnessability 評估
 - Rate the current harnessability as `低`, `中`, or `高`.
@@ -74,9 +94,22 @@ Output in Traditional Chinese (Taiwan). Use this structure:
 - Prioritize improvements as P0, P1, and P2.
 - P0 must focus on changes that reduce repeated agent mistakes or prevent high-risk failures.
 
+### 5.5 Loop 設計（條件式：僅當任務涉及 loop 時輸出）
+- List tasks suited for scheduled automation, with suggested frequency.
+- Describe the isolation strategy for parallel agents (worktree / branch / container).
+- Identify which steps need maker/checker separation and their verification criteria.
+- List required connectors and external integrations.
+- Design the state persistence scheme and update responsibilities.
+- Assess loop risks: comprehension debt, cognitive surrender, unattended verification, and propose safeguards.
+
 ### 6. 人類決策點
 - State where humans should stay on the loop.
 - Identify decisions that should not be delegated fully to agents.
+- When loop design is involved, assess these three specific risks:
+  - **Verification responsibility**: error accumulation when the loop runs unattended.
+  - **Comprehension debt**: the faster the loop produces code, the wider the understanding gap.
+  - **Cognitive surrender**: tendency to stop having opinions when the loop runs itself.
+- Clearly mark which loop stages still require human intervention (scope decisions, risk acceptance, architectural tradeoffs).
 
 ### 7. 驗證方式
 - Provide exact commands or review steps when discoverable.
@@ -88,3 +121,7 @@ Output in Traditional Chinese (Taiwan). Use this structure:
 - Do not recommend broad automation before the project has reliable local validation commands.
 - Do not propose fully autonomous changes for security, compliance, production deploys, or product-scope decisions.
 - Keep the output actionable and tied to repository evidence.
+- Do not recommend loop-driven automations for projects that lack reliable local validation commands and stable CI.
+- When designing loops, explicitly assess comprehension debt, cognitive surrender, and unattended verification risks.
+- For sub-agent design and implementation details, defer to the neo-sub-agent skill to avoid responsibility overlap.
+- Mark loop engineering concepts as emerging practice, not established best practice.

package/skills/neo-agent-harness/reference/harness-patterns.md

@@ -178,3 +178,17 @@ Common improvement sequence:
 - Humans prioritize and approve harness changes.
 - Low-risk improvements can be automated after repeated success.
 - Harness quality itself is reviewed regularly.
+
+### Level 5: Loop-Driven Development
+
+- Harness is driven by scheduled automations, no longer relying on manual triggers.
+- Multiple agents work in parallel across isolated worktrees.
+- Generation and verification are handled by separate agents (maker/checker separation).
+- Connectors let the loop directly operate issue trackers, PRs, CI, and notification channels.
+- A state file persists progress across conversations; each run resumes from where the last one stopped.
+- The human role shifts from in-the-loop line-by-line review to on-the-loop supervision: designing loops, sampling outputs, and evolving the harness.
+- Comprehension debt, cognitive surrender, and unattended verification risks are explicitly assessed and managed.
+- High-risk changes are forced out of the loop to await human decisions.
+
+Prerequisites: Level 4 harness improvement loop is running stably, CI is reliable, and review processes are mature.
+Note: Loop engineering is still an emerging practice. Start with low-risk, repetitive tasks.

package/skills/neo-agent-harness/reference/loop-engineering.md

@@ -0,0 +1,149 @@
+# Loop Engineering
+
+Use this reference when designing loop architectures that automate agent-driven workflows beyond a single session.
+
+## Loop 與 Harness 的關係
+
+- Harness = 單一 agent 的工作環境（guides + sensors + gates）
+- Loop = harness 之上的排程驅動層，讓 harness 自己跑
+- 設計 loop 不是取代 prompt，而是把反覆的 prompt 動作系統化
+
+```text
+Loop = Automations + Worktrees + Skills + Connectors + Sub-agents + State
+       ─────────────────────────────────────────────────────────────────
+                          running on top of the Harness
+```
+
+## 五個基本原件 + State
+
+### 1. Automations（心跳）
+
+沒有 automations 的 loop 只跑一次；有了它才會重複。
+
+- 排程式觸發，定時執行探索與分類。
+- 找到問題的送 triage inbox，沒發現的自動歸檔。
+- 可搭配 skills 維護排程任務的可維護性——呼叫 `$skill-name` 而非貼一大段指令。
+- `/loop` 按頻率重複執行；`/goal` 持續執行直到停止條件成立，且由獨立模型判斷是否完成。
+
+工具對應：
+
+- Codex：Automations tab（選專案、prompt、頻率、環境），結果進 Triage inbox；`/goal` run-until-done。
+- Claude Code：`/loop`、`/goal`、hooks、cron、GitHub Actions。
+
+### 2. Worktrees（隔離）
+
+多 agent 並行時避免檔案衝突。
+
+- 每個 agent 在獨立的 git worktree 工作，共享 repo history。
+- 一個 agent 的編輯不會碰到另一個的 checkout。
+- 人的 review bandwidth 仍是瓶頸——worktree 解決機械衝突，但你能同時審幾條線決定了你能跑幾個 agent（orchestration tax）。
+
+工具對應：
+
+- Codex：內建 worktree per thread。
+- Claude Code：`git worktree`、`--worktree` flag、subagent 的 `isolation: worktree` 設定。
+
+### 3. Skills（知識固化）
+
+把反覆解釋的專案上下文寫成 SKILL.md。
+
+- 消除 intent debt：每次冷啟動，agent 會用自信的猜測填補意圖缺口。Skill 把意圖寫在外面，agent 每次讀取，不需重建。
+- 沒有 skills 的 loop 每個 cycle 從零推導你的整個專案；有 skills 的 loop 每次都帶著上次的知識跑。
+- Skill 是創作格式，Plugin 是發布格式——跨 repo 分享時打包成 plugin。
+
+工具對應：
+
+- Codex：Agent Skills (`SKILL.md`)，用 `$name` 或 `/skills` 呼叫，或由 description 自動觸發。
+- Claude Code：Agent Skills (`SKILL.md`)。
+
+### 4. Plugins / Connectors（外部整合）
+
+透過 MCP 連接外部工具，讓 loop 能在真實環境中行動。
+
+- 可連接 issue tracker、database、staging API、Slack。
+- Codex 和 Claude Code 都用 MCP，connector 通常跨工具可用。
+- Plugins 把 connectors 和 skills 打包在一起，方便團隊成員一次安裝。
+
+沒有 connectors 的 loop 只能輸出建議；有 connectors 的 loop 能直接開 PR、連 ticket、ping channel。
+
+### 5. Sub-agents（生成與驗證分離）
+
+Loop 的結構性前提是把 maker 和 checker 分開。
+
+- 寫程式碼的 model 對自己的作業打分數太寬容。第二個 agent 用不同指令（有時不同 model）才能抓到第一個說服自己接受的問題。
+- `/goal` 底層也是 maker/checker 分離——用獨立的小模型判斷 loop 是否完成，而不是讓做事的 agent 自己說完成了。
+- 常見分工：一個 explore、一個 implement、一個 verify against spec。
+- Sub-agents 會燒更多 token，花在值得第二意見的地方。
+
+> **職責邊界**：本段只講「為什麼 loop 需要 maker/checker 分離」這個設計決策。具體 sub-agent 的定義格式、指令撰寫、model 選擇等實作細節，請使用 `neo-sub-agent` 技能。
+
+工具對應：
+
+- Codex：`.codex/agents/` 下的 TOML 定義檔，每個有 name、description、instructions、optional model 和 reasoning effort。
+- Claude Code：`.claude/agents/` 下的 subagent 定義 + agent teams。
+
+### 6. State（外部記憶）
+
+模型在對話之間會遺忘，進度必須寫在 repo 裡。
+
+- 格式：markdown 檔、Linear board、或任何對話外的持久化儲存。
+- State 負責記住做過什麼、通過什麼、還剩什麼。每個 long-running agent 都依賴它：agent 會忘，repo 不會。
+
+## 原件對照表
+
+| 原件 | Loop 中的職責 | Codex | Claude Code |
+|:--|:--|:--|:--|
+| Automations | 排程探索與分類 | Automations tab, `/goal` | `/loop`, `/goal`, hooks, cron, GitHub Actions |
+| Worktrees | 隔離並行 | 內建 worktree per thread | `git worktree`, `--worktree`, `isolation: worktree` |
+| Skills | 固化專案知識 | Agent Skills (`SKILL.md`), `$name` | Agent Skills (`SKILL.md`) |
+| Plugins / Connectors | 外部工具整合 | Connectors (MCP) + Plugins | MCP servers + Plugins |
+| Sub-agents | 生成與驗證分離 | `.codex/agents/` TOML | `.claude/agents/` + agent teams |
+| State | 跨對話進度 | Markdown / Linear connector | Markdown (`AGENTS.md`, progress files) / Linear MCP |
+
+## 範例：一個完整 loop 的流程
+
+1. **Automation** 每天早上在 repo 上執行，prompt 呼叫 triage skill。
+2. Triage skill 讀取昨天的 CI failures、open issues、recent commits。
+3. 發現值得處理的 findings，寫入 **state file** 或 Linear board。
+4. 對每個 finding，開一個隔離的 **worktree**。
+5. 送一個 **sub-agent**（maker）進 worktree 草擬修復。
+6. 送第二個 **sub-agent**（checker）用專案 **skills** 和現有 tests 審查草稿。
+7. **Connectors** 開 PR、更新 ticket、CI 通過後 ping channel。
+8. 無法處理的 finding 送到 triage inbox 給人。
+9. **State file** 記錄什麼被嘗試了、什麼通過了、什麼還開著。
+10. 明天早上的 run 從 state 接續。
+
+你設計了一次，之後不再手動 prompt 任何步驟。
+
+## Loop 三大風險
+
+### 1. 驗證仍在你身上
+
+Loop 無人值守時也會無人值守地犯錯。Maker/checker 分離是必要但不充分的——「done」是一個 claim，不是 proof。你的工作是 ship 你確認有效的程式碼。
+
+### 2. 理解債（Comprehension Debt）
+
+Loop 越快產出你沒寫的程式碼，你對系統的理解缺口越大。除非你讀 loop 產出的東西，否則理解債只會加速累積。
+
+### 3. 認知投降（Cognitive Surrender）
+
+當 loop 自己跑，人很容易停止有主見、照單全收。同一個 loop 設計，有判斷力的人用來加速理解深入的工作，沒有判斷力的人用來迴避理解工作本身——同一動作，相反結果。
+
+### 風險防護策略
+
+- 定期抽查 loop 產出，不要只看 CI 綠燈。
+- 設定 loop 的產出量上限，避免 review backlog 失控。
+- 在 state file 記錄人類最後審查的時間點。
+- 高風險變更（安全、合規、產品 scope）強制跳出 loop 等人。
+- 定期用 loop 的錯誤模式回饋改善 harness（agentic flywheel）。
+
+## 何時適合引入 Loop vs 留在 Harness
+
+| 條件 | 建議 |
+|:--|:--|
+| 專案沒有可靠的本地驗證指令 | 先建 harness |
+| CI 不穩定或經常紅燈 | 先修 CI |
+| 團隊對 agent 產出沒有 review 流程 | 先建 review 流程 |
+| Maturity Level < 3 | 先升級 harness |
+| 重複性高、風險低的任務（triage、格式修復、依賴更新） | 適合 loop |
+| 變更涉及產品 scope、安全、架構取捨 | 不適合全自動 loop |