@moon791017/neo-skills 1.1.9 → 1.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/skills/neo-agent-harness/reference/loop-engineering.md +91 -92
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@moon791017/neo-skills",
3
- "version": "1.1.9",
3
+ "version": "1.1.11",
4
4
  "type": "module",
5
5
  "description": "Neo Skills: A Universal AI Agent Skills Extension",
6
6
  "homepage": "https://neo-blog-iota.vercel.app/",
package/skills/neo-agent-harness/reference/loop-engineering.md CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  Use this reference when designing loop architectures that automate agent-driven workflows beyond a single session.
4
4
 
5
- ## Loop 與 Harness 的關係
5
+ ## Relationship Between Loops and Harnesses
6
6
 
7
- - Harness = 單一 agent 的工作環境（guides + sensors + gates）
8
- - Loop = harness 之上的排程驅動層，讓 harness 自己跑
9
- - 設計 loop 不是取代 prompt，而是把反覆的 prompt 動作系統化
7
+ - Harness = the working environment for a single agent (guides + sensors + gates)
8
+ - Loop = the scheduling layer on top of the harness that lets the harness run itself
9
+ - Designing a loop does not replace prompts; it systematizes repetitive prompt actions
10
10
 
11
11
  ```text
12
12
  Loop = Automations + Worktrees + Skills + Connectors + Sub-agents + State
@@ -14,137 +14,136 @@ Loop = Automations + Worktrees + Skills + Connectors + Sub-agents + State
14
14
  running on top of the Harness
15
15
  ```
16
16
 
17
- ## 五個基本原件 + State
17
+ ## Five Primitives + State
18
18
 
19
- ### 1. Automations（心跳）
19
+ ### 1. Automations (Heartbeat)
20
20
 
21
- Automations 是讓 loop 成為「真的迴圈」而非「跑過一次」的關鍵。
21
+ A loop without automations runs only once; automations make it repeat.
22
22
 
23
- - 排程式觸發，定時執行探索與分類。
24
- - 找到問題的送 triage inbox，沒發現的自動歸檔。
25
- - 可搭配 skills 維護排程任務的可維護性——呼叫 `$skill-name` 而非貼一大段指令。
26
- - `/loop` 按頻率重複執行；`/goal` 持續執行直到停止條件成立，且由獨立模型判斷是否完成。
23
+ - Schedule-driven triggers that periodically run exploration and classification.
24
+ - Findings go to the triage inbox; non-findings are auto-archived.
25
+ - Pair with skills to keep scheduled tasks maintainable—invoke `$skill-name` instead of pasting a wall of instructions.
26
+ - `/loop` repeats at a set frequency; `/goal` runs until a stop condition is met, with an independent model judging completion.
27
27
 
28
- 工具對應：
28
+ Tool mapping:
29
29
 
30
- - Codex：Automations tab（選專案、prompt、頻率、環境），結果進 Triage inbox；`/goal` run-until-done。
31
- - Claude Code：`/loop`、`/goal`、hooks、cron、GitHub Actions。
30
+ - Codex: Automations tab (select project, prompt, frequency, environment); results go to Triage inbox; `/goal` for run-until-done.
31
+ - Claude Code: `/loop`, `/goal`, hooks, cron, GitHub Actions.
32
32
 
33
- ### 2. Worktrees（隔離）
33
+ ### 2. Worktrees (Isolation)
34
34
 
35
- 多 agent 並行時避免檔案衝突。
35
+ Prevent file conflicts when multiple agents run in parallel.
36
36
 
37
- - 每個 agent 在獨立的 git worktree 工作，共享 repo history。
38
- - 一個 agent 的編輯不會碰到另一個的 checkout。
39
- - 人的 review bandwidth 仍是瓶頸——worktree 解決機械衝突，但你能同時審幾條線決定了你能跑幾個 agent（orchestration tax）。
37
+ - Each agent works in its own git worktree, sharing repo history.
38
+ - One agent's edits never touch another agent's checkout.
39
+ - Human review bandwidth is still the bottleneck—worktrees solve mechanical conflicts, but the number of agents you can run is limited by how many threads you can review simultaneously (orchestration tax).
40
40
 
41
- 工具對應：
41
+ Tool mapping:
42
42
 
43
- - Codex：內建 worktree per thread。
44
- - Claude Code：`git worktree`、`--worktree` flag、subagent 的 `isolation: worktree` 設定。
43
+ - Codex: Built-in worktree per thread.
44
+ - Claude Code: `git worktree`, `--worktree` flag, subagent `isolation: worktree` setting.
45
45
 
46
- ### 3. Skills（知識固化）
46
+ ### 3. Skills (Crystallized Knowledge)
47
47
 
48
- 把反覆解釋的專案上下文寫成 SKILL.md。
48
+ Write repeatedly explained project context into a SKILL.md.
49
49
 
50
- - 消除 intent debt：每次冷啟動，agent 會用自信的猜測填補意圖缺口。Skill 把意圖寫在外面，agent 每次讀取，不需重建。
51
- - 沒有 skills 的 loop 每個 cycle 從零推導你的整個專案；有 skills 的 loop 會累積複利。
52
- - Skill 是創作格式，Plugin 是發布格式——跨 repo 分享時打包成 plugin。
50
+ - Eliminate intent debt: on every cold start, an agent fills intent gaps with confident guesses. A skill externalizes intent so the agent reads it every time instead of reconstructing it.
51
+ - A loop without skills re-derives your entire project from scratch each cycle; a loop with skills carries forward knowledge from the last run.
52
+ - A skill is an authoring format; a plugin is a distribution format—package skills as plugins when sharing across repos.
53
53
 
54
- 工具對應：
54
+ Tool mapping:
55
55
 
56
- - Codex：Agent Skills (`SKILL.md`)，用 `$name` 或 `/skills` 呼叫，或由 description 自動觸發。
57
- - Claude Code：Agent Skills (`SKILL.md`)。
56
+ - Codex: Agent Skills (`SKILL.md`), invoked via `$name` or `/skills`, or auto-triggered by description.
57
+ - Claude Code: Agent Skills (`SKILL.md`).
58
58
 
59
- ### 4. Plugins / Connectors（外部整合）
59
+ ### 4. Plugins / Connectors (External Integration)
60
60
 
61
- 透過 MCP 連接外部工具，讓 loop 能在真實環境中行動。
61
+ Connect external tools via MCP so the loop can act in real environments.
62
62
 
63
- - 可連接 issue tracker、database、staging API、Slack。
64
- - Codex 和 Claude Code 都用 MCP，connector 通常跨工具可用。
65
- - Plugins 把 connectors 和 skills 打包在一起，方便團隊成員一次安裝。
63
+ - Can connect to issue trackers, databases, staging APIs, Slack.
64
+ - Both Codex and Claude Code use MCP; connectors are generally cross-tool portable.
65
+ - Plugins bundle connectors and skills together for one-step team installation.
66
66
 
67
- 差異：只能看 filesystem 的 loop 是小 loop；能開 PR、連 ticket、ping channel 的 loop 才是完整的。
67
+ A loop without connectors can only output suggestions; a loop with connectors can open PRs, link tickets, and ping channels directly.
68
68
 
69
- ### 5. Sub-agents（生成與驗證分離）
69
+ ### 5. Sub-agents (Separating Generation from Verification)
70
70
 
71
- Loop 裡最關鍵的結構性設計是把 maker 和 checker 分開。
71
+ The structural premise of a loop is separating maker from checker.
72
72
 
73
- - 寫程式碼的 model 對自己的作業打分數太寬容。第二個 agent 用不同指令（有時不同 model）才能抓到第一個說服自己接受的問題。
74
- - `/goal` 底層也是 maker/checker 分離——用獨立的小模型判斷 loop 是否完成，而不是讓做事的 agent 自己說完成了。
75
- - 常見分工：一個 explore、一個 implement、一個 verify against spec。
76
- - Sub-agents 會燒更多 token，花在值得第二意見的地方。
73
+ - The model that writes the code grades its own work too leniently. A second agent with different instructions (sometimes a different model) catches issues the first agent convinced itself to accept.
74
+ - `/goal` also uses maker/checker separation under the hood—an independent small model judges whether the loop is done, rather than letting the working agent declare itself finished.
75
+ - Common division of labor: one explores, one implements, one verifies against spec.
76
+ - Sub-agents burn more tokens; spend them where a second opinion is worthwhile.
77
77
 
78
- > **職責邊界**：本段只講「為什麼 loop 需要 maker/checker 分離」這個設計決策。具體 sub-agent 的定義格式、指令撰寫、model 選擇等實作細節，請使用 `neo-sub-agent` 技能。
78
+ > **Responsibility boundary**: This section only covers the design rationale for why loops need maker/checker separation. For implementation details such as sub-agent definition format, instruction writing, and model selection, use the `neo-sub-agent` skill.
79
79
 
80
- 工具對應：
80
+ Tool mapping:
81
81
 
82
- - Codex：`.codex/agents/` 下的 TOML 定義檔，每個有 name、description、instructions、optional model 和 reasoning effort。
83
- - Claude Code：`.claude/agents/` 下的 subagent 定義 + agent teams。
82
+ - Codex: TOML definition files under `.codex/agents/`, each with name, description, instructions, optional model, and reasoning effort.
83
+ - Claude Code: Subagent definitions under `.claude/agents/` + agent teams.
84
84
 
85
- ### 6. State（外部記憶）
85
+ ### 6. State (External Memory)
86
86
 
87
- 模型在對話之間會遺忘，進度必須寫在 repo 裡。
87
+ Models forget between conversations; progress must be written to the repo.
88
88
 
89
- - 格式：markdown 檔、Linear board、或任何對話外的持久化儲存。
90
- - State 是 loop 的脊椎——記住做過什麼、通過什麼、還剩什麼。
91
- - 看起來太簡單不重要，但每個 long-running agent 都依賴它：agent 會忘，repo 不會。
89
+ - Format: markdown files, Linear boards, or any persistent store outside the conversation.
90
+ - State tracks what was done, what passed, and what remains. Every long-running agent depends on it: agents forget, repos don't.
92
91
 
93
- ## 原件對照表
92
+ ## Primitives Comparison Table
94
93
 
95
- | 原件 | Loop 中的職責 | Codex | Claude Code |
94
+ | Primitive | Role in Loop | Codex | Claude Code |
96
95
  |:--|:--|:--|:--|
97
- | Automations | 排程探索與分類 | Automations tab, `/goal` | `/loop`, `/goal`, hooks, cron, GitHub Actions |
98
- | Worktrees | 隔離並行 | 內建 worktree per thread | `git worktree`, `--worktree`, `isolation: worktree` |
99
- | Skills | 固化專案知識 | Agent Skills (`SKILL.md`), `$name` | Agent Skills (`SKILL.md`) |
100
- | Plugins / Connectors | 外部工具整合 | Connectors (MCP) + Plugins | MCP servers + Plugins |
101
- | Sub-agents | 生成與驗證分離 | `.codex/agents/` TOML | `.claude/agents/` + agent teams |
102
- | State | 跨對話進度 | Markdown / Linear connector | Markdown (`AGENTS.md`, progress files) / Linear MCP |
96
+ | Automations | Scheduled exploration and classification | Automations tab, `/goal` | `/loop`, `/goal`, hooks, cron, GitHub Actions |
97
+ | Worktrees | Parallel isolation | Built-in worktree per thread | `git worktree`, `--worktree`, `isolation: worktree` |
98
+ | Skills | Crystallized project knowledge | Agent Skills (`SKILL.md`), `$name` | Agent Skills (`SKILL.md`) |
99
+ | Plugins / Connectors | External tool integration | Connectors (MCP) + Plugins | MCP servers + Plugins |
100
+ | Sub-agents | Separating generation from verification | `.codex/agents/` TOML | `.claude/agents/` + agent teams |
101
+ | State | Cross-conversation progress | Markdown / Linear connector | Markdown (`AGENTS.md`, progress files) / Linear MCP |
103
102
 
104
- ## 範例：一個完整 loop 的流程
103
+ ## Example: A Complete Loop Flow
105
104
 
106
- 1. **Automation** 每天早上在 repo 上執行，prompt 呼叫 triage skill。
107
- 2. Triage skill 讀取昨天的 CI failures、open issues、recent commits。
108
- 3. 發現值得處理的 findings，寫入 **state file** 或 Linear board。
109
- 4. 對每個 finding，開一個隔離的 **worktree**。
110
- 5. 送一個 **sub-agent**（maker）進 worktree 草擬修復。
111
- 6. 送第二個 **sub-agent**（checker）用專案 **skills** 和現有 tests 審查草稿。
112
- 7. **Connectors** 開 PR、更新 ticket、CI 通過後 ping channel。
113
- 8. 無法處理的 finding 送到 triage inbox 給人。
114
- 9. **State file** 記錄什麼被嘗試了、什麼通過了、什麼還開著。
115
- 10. 明天早上的 run 從 state 接續。
105
+ 1. **Automation** runs on the repo every morning; prompt invokes the triage skill.
106
+ 2. Triage skill reads yesterday's CI failures, open issues, and recent commits.
107
+ 3. Noteworthy findings are written to a **state file** or Linear board.
108
+ 4. For each finding, an isolated **worktree** is created.
109
+ 5. A **sub-agent** (maker) is sent into the worktree to draft a fix.
110
+ 6. A second **sub-agent** (checker) reviews the draft using project **skills** and existing tests.
111
+ 7. **Connectors** open a PR, update the ticket, and ping the channel once CI passes.
112
+ 8. Findings that cannot be handled are sent to the triage inbox for humans.
113
+ 9. The **state file** records what was attempted, what passed, and what remains open.
114
+ 10. Tomorrow morning's run picks up from state.
116
115
 
117
- 你設計了一次，之後不再手動 prompt 任何步驟。
116
+ You design it once; after that, you never manually prompt any step.
118
117
 
119
- ## Loop 三大風險
118
+ ## Three Major Loop Risks
120
119
 
121
- ### 1. 驗證仍在你身上
120
+ ### 1. Verification Is Still on You
122
121
 
123
- Loop 無人值守時也會無人值守地犯錯。Maker/checker 分離是必要但不充分的——「done」是一個 claim，不是 proof。你的工作是 ship 你確認有效的程式碼。
122
+ An unattended loop also makes mistakes unattended. Maker/checker separation is necessary but not sufficient—"done" is a claim, not a proof. Your job is to ship code you have confirmed works.
124
123
 
125
- ### 2. 理解債（Comprehension Debt）
124
+ ### 2. Comprehension Debt
126
125
 
127
- Loop 越快產出你沒寫的程式碼，你對系統的理解缺口越大。除非你讀 loop 產出的東西，否則理解債只會加速累積。
126
+ The faster a loop produces code you didn't write, the larger your understanding gap grows. Unless you read what the loop produces, comprehension debt only accelerates.
128
127
 
129
- ### 3. 認知投降（Cognitive Surrender）
128
+ ### 3. Cognitive Surrender
130
129
 
131
- 當 loop 自己跑，人很容易停止有主見、照單全收。同一個 loop 設計，有判斷力的人用來加速理解深入的工作，沒有判斷力的人用來迴避理解工作本身——同一動作，相反結果。
130
+ When a loop runs itself, people easily stop having opinions and accept everything at face value. The same loop design, used by someone with judgment, accelerates deeply understood work; used by someone without judgment, it becomes a way to avoid understanding the work itself—same action, opposite outcomes.
132
131
 
133
- ### 風險防護策略
132
+ ### Risk Mitigation Strategies
134
133
 
135
- - 定期抽查 loop 產出，不要只看 CI 綠燈。
136
- - 設定 loop 的產出量上限，避免 review backlog 失控。
137
- - 在 state file 記錄人類最後審查的時間點。
138
- - 高風險變更（安全、合規、產品 scope）強制跳出 loop 等人。
139
- - 定期用 loop 的錯誤模式回饋改善 harness（agentic flywheel）。
134
+ - Periodically spot-check loop output; don't rely solely on green CI.
135
+ - Set output volume caps on the loop to prevent review backlog from spiraling.
136
+ - Record the timestamp of the last human review in the state file.
137
+ - Force high-risk changes (security, compliance, product scope) to exit the loop and wait for a human.
138
+ - Regularly feed loop error patterns back to improve the harness (agentic flywheel).
140
139
 
141
- ## 何時適合引入 Loop vs 留在 Harness
140
+ ## When to Introduce a Loop vs. Stay with the Harness
142
141
 
143
- | 條件 | 建議 |
142
+ | Condition | Recommendation |
144
143
  |:--|:--|
145
- | 專案沒有可靠的本地驗證指令 | 先建 harness |
146
- | CI 不穩定或經常紅燈 | 先修 CI |
147
- | 團隊對 agent 產出沒有 review 流程 | 先建 review 流程 |
148
- | Maturity Level < 3 | 先升級 harness |
149
- | 重複性高、風險低的任務（triage、格式修復、依賴更新） | 適合 loop |
150
- | 變更涉及產品 scope、安全、架構取捨 | 不適合全自動 loop |
144
+ | Project lacks reliable local verification commands | Build the harness first |
145
+ | CI is unstable or frequently red | Fix CI first |
146
+ | Team has no review process for agent output | Establish a review process first |
147
+ | Maturity Level < 3 | Upgrade the harness first |
148
+ | Highly repetitive, low-risk tasks (triage, format fixes, dependency updates) | Good fit for a loop |
149
+ | Changes involve product scope, security, or architecture trade-offs | Not suitable for a fully automated loop |