@moon791017/neo-skills 1.1.7 → 1.1.9

package/README.md

@@ -11,7 +11,7 @@
 
 目前專案提供：
 
-- `skills/`：22 個內建專家技能。
+- `skills/`：內建多個專家技能。
 - `bin/install-skills.js`：同步技能到 Antigravity CLI 全域技能目錄。
 - `bin/install-system-instructions.js`：把系統提示詞安裝到 Claude Code、Copilot CLI、Codex 或 Antigravity 的指導檔。
 - `scripts/check-skills-syntax.py`：非互動式技能結構驗證工具。
@@ -41,6 +41,7 @@
 | DevOps | `neo-azure-pipelines` | 建立、審查、除錯或現代化 Azure Pipelines YAML，尤其是 .NET build、Azure App Service 或 IIS 部署。 |
 | 需求釐清 | `neo-clarification` | 將模糊、情緒化、片段式、截圖式需求轉成規格、驗收條件或釐清問題。 |
 | Code Review | `neo-code-review` | 進行程式碼審查、PR/diff review、bug 風險掃描、安全性、效能或可維護性檢查。 |
+| 系統架構 | `neo-clean-architecture` | 設計、實作、審查或重構符合 Clean Architecture 原則的系統，劃分層級並排除特定技術依賴。 |
 | C# | `neo-csharp` | 撰寫、審查、除錯或現代化 C#/.NET 程式碼，包含語言版本、NRT、records、pattern matching 與 async。 |
 | C# | `neo-csharp-interface-generator` | 從 C# class 產生或更新 interface，並安全建立、追加或替換 interface block。 |
 | .NET | `neo-dotnet` | 廣泛 .NET 問題或尚未確定子領域時，先偵測 SDK/project shape 並導向合適技能。 |
@@ -147,6 +148,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | 設計 Azure Pipelines CI/CD | `neo-azure-pipelines` | `幫我建立 .NET 專案的 Azure Pipelines CI` |
 | 審查目前變更 | `neo-code-review` | `請 review 目前 git diff` |
 | 釐清模糊需求 | `neo-clarification` | `把這些零散需求整理成規格與待確認問題` |
+| 設計乾淨架構 | `neo-clean-architecture` | `幫我用 Clean Architecture 設計訂單管理模組` |
 | 寫 TypeScript 型別 | `neo-typescript` | `幫我設計這個 API response 的泛型型別` |
 | 建 Vue 3 元件 | `neo-vue` | `幫我重構這個 SFC，避免響應式踩坑` |
 | 改善 AI 開發流程 | `neo-agent-harness` | `評估這個專案讓 coding agent 協作的可靠度` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "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,150 @@
+# 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 打包在一起，方便團隊成員一次安裝。
+
+差異：只能看 filesystem 的 loop 是小 loop；能開 PR、連 ticket、ping channel 的 loop 才是完整的。
+
+### 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 是 loop 的脊椎——記住做過什麼、通過什麼、還剩什麼。
+- 看起來太簡單不重要，但每個 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 |

package/skills/neo-clean-architecture/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: neo-clean-architecture
+description: >
+  Use this skill when the user wants to design, implement, review, or refactor software systems conforming to Clean Architecture principles.
+  It structures code into Domain, Application, Infrastructure, and Presentation/API layers, enforcing inward-only dependencies.
+  It advocates rich domain models, CQRS, and the Result pattern, operating on technology-neutral concepts without database or framework bindings.
+metadata:
+  pattern: reviewer-generator
+  domain: architecture
+---
+
+# Clean Architecture
+
+Design and review software systems using Clean Architecture. The core objective is separating concerns based on their rate of change, directing all source code dependencies inward toward the Domain core.
+
+## Gotchas
+* **Anemic Models**: Entities that are mere data containers (only getters/setters) leak business logic. Entities must protect their invariants. State changes must go through explicit, business-oriented methods.
+* **Pointless Value Objects**: Avoid wrapping primitives (e.g., string, number) unless they encapsulate validation (e.g., email format) or behavior (e.g., auto-slug generation).
+* **Deep Object Graphs**: Do not nest full entities for associations. Loading a parent entity will trigger database performance issues. Reference other aggregates using IDs instead.
+* **Dependency Leakage**: Repository interfaces must reside in the Application layer, with implementations in Infrastructure. Never return query streams (e.g., `IQueryable`) to Application, as it leaks database concerns.
+* **Exception Control Flow**: Do not throw runtime exceptions for expected business failures (e.g., duplicate title, user not found). Use the Result pattern for flow control.
+
+---
+
+## Workflow Checklist
+
+Progress:
+- [ ] Step 1: Analyze Core & Boundaries (See `references/design_principles.md`).
+- [ ] Step 2: Design Domain Layer (Build entities and value objects; protect invariants).
+- [ ] Step 3: Design Application Layer (Define use case handlers, CQRS inputs, and repository interfaces).
+- [ ] Step 4: Implement Outer Layers (Implement database mapping, external services, and API controllers).
+- [ ] Step 5: Audit Architecture Health (Use `assets/review_checklist.md` to scan code).
+
+---
+
+## Detailed Guidelines
+
+### Step 1 — Analyze Core & Boundaries
+1. Categorize business rules:
+   - Domain Layer: Core rules that would exist even without a computer system.
+   - Application Layer: System orchestration, workflows, and protocols.
+   - Outer Layers (Infrastructure/Presentation): Delivery mechanisms and persistence details.
+2. Read [design_principles.md](references/design_principles.md) for architectural details.
+
+### Step 2 — Design Domain Layer
+1. Entities: Keep setters private or read-only.
+2. Domain Methods: Expose semantic operations (e.g., `updateContent()`, `addTag()`) that validate rules inside the entity.
+3. Associations: Keep aggregates decoupled by referencing other aggregate roots via ID only.
+
+### Step 3 — Design Application Layer
+1. Separate write operations (Commands) from read operations (Queries) using **CQRS**.
+2. Define technology-neutral interfaces (e.g., `IUserRepository`), keeping database or network specifics out of Application.
+3. Wrap use case outcomes in a **Result** type containing success/failure status, value, error type, and message. Refer to [layer_specifications.md](references/layer_specifications.md) for concepts mapping.
+
+### Step 4 — Implement Infrastructure & Presentation
+1. **Infrastructure**: Implement interfaces defined in Application. Configure ORM/database mappings, value conversions, and call external services.
+2. **Presentation/API**: Handle transmission protocols (e.g., HTTP, gRPC). Map request payload to Command/Query, dispatch it to Application, and translate the Result into appropriate responses (e.g., HTTP 200, 201, 400, 404, 409).
+
+---
+
+## Output Templates
+
+### 1. Architecture Blueprint Template
+```markdown
+# [System Name] Clean Architecture Blueprint
+
+## 1. Domain Layer
+* **Entities & Aggregate Roots**:
+  - `EntityName` (ID-association explanation)
+* **Value Objects**:
+  - `ValueObjectName` (Validation and behavior description)
+
+## 2. Application Layer
+* **Use Cases (CQRS / Handlers)**:
+  - `CreateSomethingCommand` & Handler
+  - `GetSomethingQuery` & Handler
+* **External Interfaces (Gateways / Repositories)**:
+  - `ISomethingRepository` (Interface methods)
+
+## 3. Infrastructure Layer
+* **Persistence Configurations**:
+  - `SomethingRepository` implementation notes
+  - Value Object persistence mapping rules
+
+## 4. Presentation / API Layer
+* **Contracts (Request/Response)**:
+  - `CreateSomethingRequest` -> `SomethingResponse`
+* **Route & Status Code Mappings**:
+  - `POST /api/something` -> `201 Created` / `400 Bad Request` / `409 Conflict`
+```
+
+### 2. Architecture Review Template
+```markdown
+# Clean Architecture Review — [Project Name]
+
+## Health Score: [Score]/10
+[Brief architectural health assessment]
+
+## Findings & Recommendations
+### 🔴 Critical (Dependency Violation / Invariant Leakage)
+* **Location**: `path/to/file.ext#L12-30`
+* **Problem**: [Description of the clean architecture violation]
+* **Remediation**:
+  ```[language]
+  // Corrected code snippet
+  ```
+
+### 🟡 Warning (Anemic Model / Pointless Wrapping)
+* **Location**: `path/to/file.ext`
+* **Problem**: [Issue description]
+* **Remediation**: [Code or prose description]
+
+### 🟢 Info (Structural / Pipeline Enhancements)
+* **Location**: `path/to/file.ext`
+* **Remediation**: [Suggestion details]
+```

package/skills/neo-clean-architecture/assets/architecture_template.md

@@ -0,0 +1,93 @@
+# [System Name] — Clean Architecture Design Blueprint
+
+This document specifies the architectural layout for [System Name], conforming to inward-only dependency rules of Clean Architecture.
+
+---
+
+## 1. Domain Layer
+
+The Domain layer is independent of databases, web frameworks, and libraries.
+
+### 1.1 Entities
+
+#### Entity: `[EntityName]`
+* **Description**: [E.g., Represents a registered user account]
+* **Core Attributes** (Read-Only):
+  - `id`: UniqueIdentifier
+  - `[PropertyName]`: [PropertyType]
+* **Invariants & Operations**:
+  - `[MethodName]([parameters])`: [Explain what state changes are made and which invariants are verified]
+  - `constructor([parameters])`: [Initial validation rules upon instantiation]
+
+### 1.2 Value Objects
+
+#### Value Object: `[ValueObjectName]`
+* **Description**: [E.g., Format-validated email address]
+* **Attributes**:
+  - `value`: String
+* **Validation & Formatting**:
+  - [Explain formatting rules or auto-slug generation rules]
+
+---
+
+## 2. Application Layer
+
+Defines use cases, structures input commands/queries, and declares repository interfaces.
+
+### 2.1 Use Cases (CQRS)
+
+#### Command / Query: `[OperationName]`
+* **Description**: [E.g., Creating a new record]
+* **Input Schema**:
+  - `[ParamName]`: [ParamType]
+* **Handler Execution Steps**:
+  1. Trigger **Input Validator** to verify payload formatting.
+  2. Call `[Repository].exists([uniqueKey])` to check for conflicts (return `Result.conflict` if true).
+  3. Instantiate `[DomainEntity]`.
+  4. Invoke `[Repository].add([EntityInstance])`.
+  5. Return `Result.success([EntityId])`.
+
+### 2.2 Repository Interfaces
+
+#### Interface: `I[EntityName]Repository`
+* `findById(id: UniqueIdentifier): Promise<[EntityName] | null>`
+* `add(entity: [EntityName]): Promise<void>`
+* `update(entity: [EntityName]): Promise<void>`
+* `delete(id: UniqueIdentifier): Promise<void>`
+
+---
+
+## 3. Infrastructure Layer
+
+Implements Application interfaces and coordinates technology-specific libraries.
+
+### 3.1 Persistence
+
+#### Class: `[EntityName]Repository`
+* **Interface**: `I[EntityName]Repository`
+* **Data Mapping**:
+  - Map entity `[EntityName]` to table `[table_name]`.
+  - Convert Value Object `[ValueObjectName]` to primitive database column type `[column_type]` on save, and deserialize on fetch.
+* **Transaction Management**:
+  - Save changes using the persistence tracker in the repository's persist methods.
+
+### 3.2 External Gateways
+* [E.g., File storage clients, mail gateways, third-party REST clients]
+
+---
+
+## 4. Presentation / API Layer
+
+Entry point translating network protocols to Use Case payloads.
+
+### 4.1 Endpoints & Routing
+
+#### Route: `[HTTP_METHOD] /api/[resource_path]`
+* **Description**: [E.g., Create a resource]
+* **Request Contract**:
+  - `[FieldName]`: [FieldType]
+* **Response & Status Codes**:
+  - `201 Created` / `200 OK` -> `[ResponseContract]`
+  - `400 Bad Request` -> Validation Schema Errors
+  - `409 Conflict` -> Business Rule Violations
+  - `404 Not Found` -> Resource Missing

package/skills/neo-clean-architecture/assets/review_checklist.md

@@ -0,0 +1,35 @@
+# Clean Architecture Review Checklist
+
+Use this checklist to scan and review code bases for conformity to Clean Architecture boundaries.
+
+---
+
+## 1. Dependency Directions
+* [ ] **Physical Inward Dependency (🔴 Critical)**: Do inner circles (Domain, Application) import, reference, or depend on outer circles (Infrastructure, Presentation, ORM, Web Frameworks)?
+* [ ] **Query Stream Leakage (🔴 Critical)**: Do repository interfaces return ORM-specific query streams (e.g., `IQueryable`, `IPreparedQuery`)? This leaks persistence details to Application.
+* [ ] **ORM Annotation Leakage (🟡 Warning)**: Do domain entities contain database-specific annotations (e.g., `@Table`, `@Column`, `[Key]`, `[Required]`)? (Map ORM metadata in the Infrastructure layer instead).
+* [ ] **External SDK Leakage (🟡 Warning)**: Does the Application layer reference third-party SDK types as handler parameters? (Isolate using DTOs or custom interfaces).
+
+---
+
+## 2. Domain Layer
+* [ ] **Anemic Model (🟡 Warning)**: Are entities plain data bags with public setters, shifting business rules into Application Services?
+* [ ] **Invariant Protection (🟡 Warning)**: Do entity constructors and methods validate rules? Can an entity be instantiated in an invalid state?
+* [ ] **Pointless Value Objects (🟢 Info)**: Are primitives wrapped in value objects without any validation or formatting benefits? (Avoid pointless overhead).
+* [ ] **Coupling by Nested Entities (🟡 Warning)**: Do entities reference other aggregate roots directly as objects (e.g., `class Order { user: User }`)? (Reference aggregate roots via IDs instead to avoid ORM pre-loading performance traps).
+
+---
+
+## 3. Application & Use Case Layer
+* [ ] **Single Responsibility Use Cases (🟢 Info)**: Do use case classes or handlers manage multiple unrelated actions? (Prefer a single handler per business command/query).
+* [ ] **Cross-Cutting Concern Pollution (🟡 Warning)**: Are logging, validation, and transaction commits scattered across use case handlers? (Centralize via pipeline middleware or interceptors).
+* [ ] **Exception Control Flow (🟡 Warning)**: Does application code throw exceptions for expected failures (e.g., password mismatch, username conflict)? (Use Result objects instead).
+* [ ] **Database Transaction Leaks (🔴 Critical)**: Does Application code directly call SQL, NoSQL, or Transaction Commit APIs? (Isolate via `IRepository` and `IUnitOfWork` interfaces).
+
+---
+
+## 4. Presentation & API Layer
+* [ ] **Thin Controllers (🟡 Warning)**: Do controllers or endpoint handlers contain business logic? (Controllers must only parse request payloads and dispatch them).
+* [ ] **Contract Leakage (🟡 Warning)**: Do controllers expose Domain Entities or persistence models directly as API payloads? (Use separate Request/Response DTO contracts).
+* [ ] **Format Validation Isolation (🟢 Info)**: Is basic format validation (e.g., empty string, regex check) caught at the boundary via validators, separate from domain invariants?
+* [ ] **Status Code Mapping (🟢 Info)**: Are Result errors correctly mapped to transport status codes (e.g., HTTP 400, 404, 409, 500)?

package/skills/neo-clean-architecture/evals/eval_queries.json

@@ -0,0 +1,26 @@
+{
+  "should_trigger": [
+    "How to design a clean architecture order module?",
+    "I want to map out a Clean Architecture project structure, how should I layer it?",
+    "Could you check if this domain entity is an anemic model and tell me how to make it a Rich Domain Model?",
+    "How do I implement the Repository Pattern in Clean Architecture without leaking database concerns?",
+    "Should book loan business logic reside in the Domain or Application layer?",
+    "Can you do a Clean Architecture code review on my project structure and code?",
+    "How do I use the Result Pattern instead of Exceptions for flow control?",
+    "How should I reference associations between aggregate roots in Clean Architecture to avoid ORM performance traps?",
+    "Why shouldn't a repository return IQueryable?",
+    "Help me design microservice core logic layers using technology-neutral architecture concepts."
+  ],
+  "should_not_trigger": [
+    "How do I write an ASP.NET Core Minimal API Controller in C#?",
+    "Help me install EF Core SqlServer package and add a new Migration.",
+    "How to write a MediatR Pipeline Behavior?",
+    "How do I write a React file upload UI component?",
+    "Teach me how to write a PostgreSQL JSONB column query in SQL.",
+    "Does this code have a memory leak? Please review for performance issues.",
+    "How do I configure Docker to run a MySQL database?",
+    "What are the three pillars of object-oriented programming?",
+    "How do I implement a binary search tree in Python?",
+    "Write a simple script to parse a CSV file and sum a column."
+  ]
+}

package/skills/neo-clean-architecture/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "neo-clean-architecture",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design a Clean Architecture blueprint for an 'Online Library System'. Key requirements: Borrow books (limits: max 5 books per reader, book must be available, loan record automatically saves checkout date and due date). Keep it technology-neutral and concept-focused; do not use specific programming languages.",
+      "expected_output": "A structured Clean Architecture plan containing Domain layer (Entities: Book/Reader/Loan, Value Object: LoanDuration), Application layer (BorrowBookCommand & Handler, IBookRepository interface), and generic descriptions of Infrastructure and Presentation layers, without C# or Java annotations.",
+      "assertions": [
+        "The output lists the four standard layers (Domain, Application, Infrastructure, Presentation)",
+        "The domain entity includes invariant validation methods (e.g., limit checks or status validation)",
+        "The repository interface is defined in the Application layer, not the Infrastructure layer",
+        "Entities reference each other by ID (e.g., Loan references ReaderId/BookId) rather than full object nests",
+        "The design does not depend on specific libraries or frameworks (e.g., EF Core, MediatR, Prisma)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this code snippet for Clean Architecture conformity and suggest remediation:\n```javascript\n// In Controller\napp.post('/api/orders', async (req, res) => {\n  const { userId, items } = req.body;\n  if (!userId) return res.status(400).send('User ID is required');\n  \n  // Direct database query\n  const activeOrder = await db.query('SELECT * FROM orders WHERE user_id = $1 AND status = \\'ACTIVE\\'', [userId]);\n  if (activeOrder.rows.length > 0) {\n    return res.status(409).send('Each user can have only one active order');\n  }\n  \n  const order = {\n    id: generateUUID(),\n    userId,\n    items,\n    status: 'ACTIVE',\n    createdAt: new Date()\n  };\n  await db.query('INSERT INTO orders (id, user_id, items, status, created_at) VALUES ($1, $2, $3, $4, $5)', [order.id, order.userId, JSON.stringify(order.items), order.status, order.createdAt]);\n  \n  res.status(201).json(order);\n});\n```",
+      "expected_output": "An architecture review pointing out database dependency and business logic (limit of one active order) leakage in the controller. It should offer remediation to split code into an Order entity (protecting invariants), a CreateOrderUseCase/Handler, and an IOrderRepository interface, providing technology-neutral code examples.",
+      "assertions": [
+        "Identifies business logic leakage in the controller as a violation",
+        "Identifies direct database coupling in the controller as a violation",
+        "Recommends moving 'one active order check' to the Application/Domain layer",
+        "Includes a technology-neutral refactored code example (with Repository interface and Use Case handler)",
+        "Conforms to the review report template format (containing score, findings, and remediation categories)"
+      ]
+    }
+  ]
+}

package/skills/neo-clean-architecture/references/design_principles.md

@@ -0,0 +1,130 @@
+# Clean Architecture Design Principles
+
+This document defines core concepts of Clean Architecture, focusing on technology-neutral guidelines applicable across different programming languages and frameworks.
+
+---
+
+## 1. Separation of Concerns
+
+Components change for different reasons and at different rates:
+* **Business Rules** (e.g., discount logic): Exist in the **Domain** core. Changes reflect business policy shifts.
+* **Application Use Cases** (e.g., notifying users after sign-up): Coordinate flows in the **Application** layer.
+* **Technical Details** (e.g., PostgreSQL migration, REST-to-gRPC switch): Restricted to **Infrastructure** and **Presentation**.
+
+Coupling these layers increases regression risks. Boundaries isolate changes to keep updates localized.
+
+---
+
+## 2. Inward Dependency Rule
+
+Source code dependencies must point strictly inward. Inner circles have zero knowledge of outer circles.
+
+```
+┌──────────────────────────────────────────────┐
+│  Presentation / API Layer                    │
+│  ┌────────────────────────────────────────┐  │
+│  │  Infrastructure Layer                   │  │
+│  │  ┌──────────────────────────────────┐  │  │
+│  │  │  Application Layer (Use Cases)   │  │  │
+│  │  │  ┌────────────────────────────┐  │  │  │
+│  │  │  │  Domain Core (Entities)    │  │  │  │
+│  │  │  └────────────────────────────┘  │  │  │
+│  │  └──────────────────────────────────┘  │  │
+│  └────────────────────────────────────────┘  │
+└──────────────────────────────────────────────┘
+```
+
+* **Domain Core**: Inmost circle. Depends on nothing. Free of frameworks, database drivers, or outer-circle constructs.
+* **Application**: Depends only on Domain. Defines use cases and abstractions (e.g., Repository interfaces).
+* **Infrastructure**: Depends on Application and Domain. Implements application interfaces, managing persistence and external networks.
+* **Presentation**: Depends on Application. Entry point handling transport protocols (HTTP/gRPC/CLI) and dispatching inputs.
+
+### Dependency Inversion Principle (DIP)
+To persist data without letting the Application depend on Infrastructure:
+* **Approach**: Define an abstract interface (e.g., `IRepository`) in the Application layer. Implement this interface (e.g., `SqlRepository`) in the Infrastructure.
+* **Result**: At runtime, DI resolves the implementation. At compile time, the source code dependency points inward, protecting the boundary.
+
+---
+
+## 3. Rich Domain Model
+
+Entities must protect their **Invariants (business rules and consistency constraints)**. Properties must be read-only, and state changes must go through semantic methods.
+
+Anemic Domain Models (data containers with public setters) scatter business rules across services, leading to duplication and maintenance overhead.
+
+```javascript
+// ✅ Correct Design: Read-only properties, state changes managed via semantic methods
+class Prompt {
+    #id;
+    #title;
+    #content;
+    #tags = new Set();
+
+    constructor(title, content) {
+        if (!title || title.trim() === "") throw new Error("Title is required");
+        this.#id = generateUUID();
+        this.#title = title.trim();
+        this.#content = content;
+    }
+
+    get title() { return this.#title; }
+    get content() { return this.#content; }
+    get tags() { return Array.from(this.#tags); }
+
+    updateContent(newContent) {
+        if (!newContent || newContent.trim() === "") throw new Error("Content cannot be empty");
+        if (this.#content === newContent) return; 
+        this.#content = newContent;
+    }
+
+    addTag(tagValue) {
+        const normalized = tagValue.trim().toLowerCase();
+        if (normalized.length === 0) return;
+        this.#tags.add(normalized);
+    }
+}
+```
+
+---
+
+## 4. Value Objects
+
+Value Objects have no identity (ID) and are defined entirely by their properties. Two Value Objects are equal if their attributes match.
+
+### Avoid Over-engineering
+Do not wrap primitives unless they validate (e.g., `Email` format) or transform data (e.g., `Tag` slugification). Use Value Objects only when:
+1. **Validation is needed**: E.g., verifying `Email` format.
+2. **Behavior is needed**: E.g., converting tag inputs to slugs.
+3. **Attributes form a conceptual whole**: E.g., `Money(amount, currency)`.
+
+---
+
+## 5. Result Pattern
+
+Expected business failures (e.g., resource not found, title conflict) should return a structured `Result` object instead of throwing runtime exceptions.
+
+Exceptions must be reserved for unexpected, fatal system issues (e.g., database connection loss, out-of-memory).
+
+### Generic Result Design
+```javascript
+class Result {
+    constructor(isSuccess, value = null, error = null, errorType = "None") {
+        this.isSuccess = isSuccess;
+        this.value = value;
+        this.error = error;
+        this.errorType = errorType; // e.g., "NotFound", "Validation", "Conflict", "None"
+    }
+
+    static success(value) {
+        return new Result(true, value, null, "None");
+    }
+
+    static failure(error, type = "Failure") {
+        return new Result(false, null, error, type);
+    }
+
+    static notFound(error = "Resource not found") {
+        return new Result(false, null, error, "NotFound");
+    }
+}
+```

package/skills/neo-clean-architecture/references/layer_specifications.md

@@ -0,0 +1,73 @@
+# Clean Architecture Layer Specifications & Mappings
+
+This document defines the responsibilities of each layer and provides guidance on translating technology-specific code/libraries into clean, technology-neutral concepts.
+
+---
+
+## Layers & Boundary Rules
+
+| Layer Name | Core Responsibility | Absolute Prohibitions (Boundary Rules) |
+| :--- | :--- | :--- |
+| **Domain** | 1. Entities<br>2. Value Objects<br>3. Domain logic & invariants<br>4. Domain events | 🚫 No database or ORM dependencies.<br>🚫 No transport protocol references (HTTP/gRPC/CLI).<br>🚫 No references to outer-layer modules (Application/Infrastructure).<br>🚫 No third-party framework annotations (e.g., Spring, Nest, ASP.NET). |
+| **Application** | 1. Use case handlers<br>2. Command & Query inputs<br>3. Repository & Gateway interfaces<br>4. Pipeline / Interceptor interfaces | 🚫 No SQL queries or DB connection details.<br>🚫 No direct HTTP requests, responses, or routing concerns.<br>🚫 No direct access to outer networks, filesystems, or email drivers. |
+| **Infrastructure** | 1. Implement Application interfaces (Repositories)<br>2. Persistence settings & ORM configurations<br>3. External gateway implementations (Mail, Queue, File Storage) | 🚫 No business logic execution outside application-defined interfaces.<br>🚫 No direct database state modification bypassing domain invariants.<br>🚫 No dependencies on Presentation layer structures (e.g., HTTP sessions). |
+| **Presentation / API** | 1. Parse and validate Request Contracts<br>2. Basic format validation (length, null check, regex)<br>3. Dispatch inputs to Application Use Cases<br>4. Map Result to Response Contracts & Status Codes | 🚫 No direct database queries (must go through Application).<br>🚫 No business rules or invariant checks.<br>🚫 No business transaction assembly across aggregates. |
+
+---
+
+## Technology-Specific to Clean Concept Mappings
+
+When reviewing codebases, map programming language syntax and library features to these universal concepts:
+
+### 1. Request Orchestration (e.g., MediatR in C#, Spring Service in Java)
+* **Library Feature**:
+  * C# `IMediator.Send(command)` or `IRequestHandler`.
+  * Java `@Service` annotations mixing use case execution with business logic.
+* **Technology-Neutral Concept**:
+  * **Command/Query Dispatcher** or **Use Case Interactor**.
+  * Separate each business workflow into a dedicated `UseCase` class or `Handler` function, dividing input schemas from execution logic.
+* **Concept Mapping Code**:
+  ```javascript
+  // Technology-neutral Use Case concept
+  class CreateUserUseCase {
+      constructor(userRepository, emailGateway) {
+          this.userRepository = userRepository;
+          this.emailGateway = emailGateway;
+      }
+
+      async execute(command) {
+          // Flow coordination...
+      }
+  }
+  ```
+
+### 2. Cross-Cutting Concerns (e.g., MediatR Pipeline, Spring AOP, Express Middleware)
+* **Library Feature**:
+  * C# `IPipelineBehavior<TRequest, TResponse>` or Express `next()` middleware.
+* **Technology-Neutral Concept**:
+  * **Pipeline Middleware / Interceptor**.
+  * Intercept actions before and after use case execution to run Logging, Validation, Transaction, and Caching. This isolates the core handler from infrastructure concerns.
+
+### 3. Persistence Mapping (e.g., EF Core, Hibernate, Prisma, Mongoose)
+* **Library Feature**:
+  * C# `DbContext`, `DbSet`, `IEntityTypeConfiguration`, or ORM navigation properties with Lazy Loading.
+* **Technology-Neutral Concept**:
+  * **Persistence Context** and **Data Mapper**.
+  * Map entities to database schemas, converting value objects to database-friendly primitives. The Domain layer must remain free of ORM annotations or persistence metadata.
+
+### 4. Repository Leakage
+* **Library Feature**:
+  * Returning C# `IQueryable<T>` or Java `Stream<T>` from repositories.
+* **Technology-Neutral Concept**:
+  * **Leaky Abstraction Anti-Pattern**.
+  * Returning query streams allows Application code to inject query filters (e.g., SQL/LINQ criteria), leaking database capabilities inward and blocking unit test isolation.
+  * **Remediation**: Repositories must return **concrete collections** (e.g., `List` or pagination objects) or expose semantic queries (e.g., `findActiveUsersByRole`).
+
+### 5. Input Validation (e.g., FluentValidation, JSR-380 annotations)
+* **Library Feature**:
+  * `AbstractValidator` or `@NotNull` property constraints.
+* **Technology-Neutral Concept**:
+  * **Input Validator**.
+  * Manage basic schema checks at boundaries. Separate validation into:
+    1. **Format Validation**: Intercept malformed payloads at API/Application boundaries.
+    2. **Invariant Validation**: Enforce business policy rules inside the Domain entity constructor/methods.