@moon791017/neo-skills 1.1.20 → 1.1.22

package/AGENTS.md

@@ -1,82 +1,62 @@
-# Neo Skills
+# neo-skills AGENTS.md
 
-**Neo Skills** 是給 AI Agent 使用的專家技能套件。核心交付物是 `skills/<skill-name>/SKILL.md` 與其延伸資源，並透過安裝工具同步到 Antigravity CLI 或其他支援 Agent Skills 規格的用戶端。
+---
 
-本專案的目標不是收集提示詞，而是把可重複使用的專業工作流程、參考文件、範本、非互動式腳本與評估資料打包成可維護的技能模組。
+## 1. Project Overview
 
-## 回應風格
+- **Primary Technology Stack**: `Node.js / JavaScript`
+- **Coding & Architectural Conventions**:
+  - Follow modular architecture and existing code formatting.
+  - Inspect existing implementation files before creating new utilities.
+  - Do NOT introduce unrequested third-party dependencies.
 
-- 使用繁體中文（台灣）。
-- Commit 訊息必須使用繁體中文（台灣）。
-- 需要事實判斷時，只根據使用者提供內容、目前 worktree、專案檔案或已驗證來源回答；資料不足時直接說明不能確定。
+---
 
-## 專案結構
+## 2. Commands
 
-| 路徑 | 用途 |
-| :--- | :--- |
-| `skills/<skill-name>/SKILL.md` | 每個技能的主要入口；第一行必須是 `---` frontmatter。 |
-| `skills/<skill-name>/references/` 或 `reference/` | 深度知識、檢核表、反模式、設計規範；只在需要時載入。 |
-| `skills/<skill-name>/assets/` | 文件、程式碼或設定檔範本。 |
-| `skills/<skill-name>/scripts/` | 可重複執行的非互動式輔助腳本。 |
-| `skills/<skill-name>/evals/` | 觸發率與輸出品質評估資料。 |
-| `bin/` | 安裝 CLI 與共用工具。 |
-| `scripts/check-skills-syntax.py` | 技能 frontmatter 與基本結構驗證工具。 |
-| `test/*.test.js` | Node.js 測試。 |
+List exact command lines used for project development, testing, linting, typechecking, and building:
 
-## 開發指令
+| Command Type | Exact Command Line | Purpose / Scope |
+| :--- | :--- | :--- |
+| **Unit / Integration Tests** | `npm test` | Verify behavioral correctness |
+| **Skill Syntax Check** | `python3 scripts/check-skills-syntax.py` | Verify skill markdown and frontmatter syntax |
+| **Build Check** | `npm run build` | Confirm clean compilation |
 
-- `npm install`：本地安裝依賴。
-- `npm test`：執行 Node.js 測試。
-- `python3 scripts/check-skills-syntax.py --dir skills`：驗證所有技能目錄與 `SKILL.md` frontmatter。
-- `node bin/install-skills.js`：將技能同步到 Antigravity CLI 全域技能目錄。
+---
 
-## Skill 品質標準
+## 3. Workflow
 
-每個技能都必須符合 Agent Skills 的漸進式揭露原則：
+The development workflow strictly follows this 9-stage closed loop:
 
-1. `SKILL.md` 第一行必須是 `---`。
-2. frontmatter 必須包含 `name` 與 `description`。
-3. `name` 必須與父資料夾名稱完全一致，使用 lowercase kebab-case。
-4. `description` 要描述「何時使用這個技能」，優先使用 `Use this skill when...` 或等價的明確觸發語。
-5. 自訂屬性放在 `metadata` 底下；不要在 frontmatter 頂層新增未標準化欄位。
-6. `SKILL.md` 保持精簡，複雜規則放入 `references/`、`assets/`、`scripts/` 或 `evals/`。
-7. 涉及版本、官方規格、SDK 或雲端服務的內容，若答案依賴最新狀態，必須查證官方來源；不能查證時要標明不確定。
-8. 修改技能時，同步檢查 README、evals、references、assets 與 scripts 是否仍一致。
+```mermaid
+graph TD
+    Step1[1. Perceive Task] --> Step2[2. Establish Baseline]
+    Step2 --> Step3[3. Reproduce Problem]
+    Step3 --> Step4[4. Plan Edits]
+    Step4 --> Step5[5. Minimal Implementation]
+    Step5 --> Step6[6. Incremental Verification]
+    Step6 --> Step7[7. Self-Review]
+    Step7 -->|Fail| Step4
+    Step7 -->|Pass| Step9[9. Handoff upon Pass]
+```
 
-## 腳本規範
+1. **Perceive Task**: Read project guidelines (`AGENTS.md`) and target source files to understand goals and constraints.
+2. **Establish Baseline**: Run existing test and build commands to confirm the project is in a stable, passing state.
+3. **Reproduce Problem**: Write or run test cases/verification steps that reliably reproduce the issue or requirement.
+4. **Plan Edits**: Decompose the task into small, atomic edit plans to avoid large single-turn changes.
+5. **Minimal Implementation**: Apply minimal code changes while preserving existing comments and public API contracts.
+6. **Incremental Verification**: Run local test, lint, and build commands immediately after each edit.
+7. **Self-Review**: Inspect diffs and execution logs; if checks fail, read full un-truncated error logs to find the root cause.
+8. **Remediate on Failure**: If verification or self-review fails, return to "Plan Edits / Minimal Implementation" to adjust.
+9. **Handoff upon Pass**: Once all verification sensors pass, present a concise report with empirical proof for handoff.
 
-寫在 `skills/<skill-name>/scripts/` 或全域 `scripts/` 的輔助腳本必須符合：
+---
 
-1. **非互動式**：只透過 CLI 參數、環境變數或 stdin 接收輸入；不要使用 `input()`、TTY prompt 或確認對話。
-2. **stdout/stderr 分離**：stdout 只輸出可解析資料（JSON、CSV、TSV）；診斷、進度與錯誤輸出到 stderr。
-3. **可重試**：能支援 dry-run 或安全重跑時要提供；避免同一輸入造成不可預期副作用。
-4. **PEP 723**：Python 腳本需放入 inline dependency block，方便 `uv run` 直接執行。
+## 4. Forbidden Antipattern Redlines
 
-## 測試規範
-
-- 變更 installer、檔案布局、hook 邏輯或驗證腳本時，新增或更新 `test/*.test.js`。
-- 變更技能 frontmatter 或新增技能後，執行 `python3 scripts/check-skills-syntax.py --dir skills`。
-- 變更腳本時，優先加入可由 CI 或本地命令執行的非互動式測試。
-- PR 前至少確認 `npm test` 通過。
-
-## Commit 與 PR
-
-- Commit 採 Conventional Commits 1.0.0：`<type>[optional scope]: <description>`。
-- 常用 type：`feat`、`fix`、`docs`、`test`、`refactor`、`build`、`ci`、`chore`。
-- Commit 主旨使用繁體中文（台灣），不要加句號。
-- 不要加入 `Co-authored-by` 或任何 AI attribution trailer。
-- 每個 commit 聚焦單一邏輯變更，不混入不相關修改。
-- PR 說明需包含行為變更、已執行指令與相關 issue。
-
-## 安全與內容
-
-- 不提交 secret、token、sample credentials 或可被誤用的危險提示詞。
-- 移除技能時，完整刪除目錄並同步清理 README、安裝文件與任何引用。
-- 不確定某項外部規格是否仍正確時，不要把它寫成確定事實。
-
-## Agent 工作流程
-
-1. 先讀目前 worktree，不依賴記憶中的舊狀態。
-2. 小步修改，保留使用者既有變更。
-3. 文件、技能與驗證工具要互相對齊。
-4. 完成後回報修改重點、已跑驗證，以及仍未處理的風險或待辦。
+| Forbidden Action | Why It Is Prohibited | Required Behavior |
+| :--- | :--- | :--- |
+| **Silent Exception Swallowing** | Hides runtime failures and causes silent data corruption. | Let exceptions surface or handle explicitly with logging. |
+| **Test Deletion / Suppression** | Forces builds to pass without fixing underlying bugs. | Fix root cause in source or update contract with justification. |
+| **Hallucinated Signatures** | Invokes non-existent methods causing runtime crashes. | View symbol definition using search tools first. |
+| **Unverified Completion Claim** | Misleads user regarding feature or bug state. | Run test/build commands and present log proof. |

package/README.md

@@ -37,8 +37,7 @@
 
 | 類別 | Skill | 使用時機 |
 | :--- | :--- | :--- |
-| Agent 治理 | `neo-agent-harness` | 設計或改善 AI 輔助開發流程、AGENTS.md、技能、測試、CI、hooks、review loops 與人類決策點。 |
-| Agent 治理 | `neo-agent-protocol` | 當 AI Agent 執行開發、重構、除錯或架構任務時，強制實施嚴格 harness 原則、自我驗證關卡、非破壞性編輯、上下文崩潰防禦與 Human-in-the-loop 邊界。 |
+| Agent 治理 | `neo-harness` | 掃描專案環境，自動產生或升級專屬且合規的 AGENTS.md 檔，整合 Harness 評估、閉環 Workflow 與編排架構。 |
 | DevOps | `neo-azure-pipelines` | 建立、審查、除錯或現代化 Azure Pipelines YAML，尤其是 .NET build、Azure App Service 或 IIS 部署。 |
 | 需求釐清 | `neo-clarification` | 將模糊、情緒化、片段式、截圖式需求轉成規格、驗收條件或釐清問題。 |
 | Code Review | `neo-code-review` | 進行程式碼審查、PR/diff review、bug 風險掃描、安全性、效能或可維護性檢查。 |
@@ -60,7 +59,6 @@
 | TypeScript | `neo-typescript` | 處理 TypeScript、tsconfig、strict mode、泛型、conditional/mapped/template literal types、ESM/CJS 與 runtime boundaries。 |
 | Vue | `neo-vue` | 建置、除錯、重構或審查 Vue 3、SFC、Composition API、Pinia、Vue Router、Vite 與 Vue+TypeScript。 |
 | Agent 架構 | `neo-sub-agent` | 設計、建立、審查或轉換 sub-agent、custom agent、worker/reviewer/planner agent 或 multi-agent workflow。 |
-| Agent 架構 | `neo-agentic-design` | 設計、評估或實作 Agent 工作流、提示詞鏈、路由、規劃、反思、多 Agent 協作與記憶體管理等框架無關模式。 |
 | 技能開發 | `generate-skill` | 建立、更新、審查或最佳化 Agent Skill，包含規格、觸發描述、延伸資源、評估資料與設計模式。 |
 | 可觀測性 | `neo-opentelemetry` | 解釋 OpenTelemetry 概念、規劃或審查 Collector 架構與設定、處理維運排障、安全、零程式 instrumentation 及相容性遷移。 |
 | 文字潤飾 | `neo-stop-slop` | 去除繁中或英文中的 AI 腔、贅詞、公式化句式，支援文件、註解、commit message 與 PR 說明。 |
@@ -153,33 +151,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | 設計乾淨架構 | `neo-clean-architecture` | `幫我用 Clean Architecture 設計訂單管理模組` |
 | 寫 TypeScript 型別 | `neo-typescript` | `幫我設計這個 API response 的泛型型別` |
 | 建 Vue 3 元件 | `neo-vue` | `幫我重構這個 SFC，避免響應式踩坑` |
-| 改善 AI 開發流程 | `neo-agent-harness` | `評估這個專案讓 coding agent 協作的可靠度` |
-| 遵循 Agent 執行協議 | `neo-agent-protocol` | `請按照 neo-agent-protocol 執行這項開發任務` |
+| 建立 Agent 治理 | `neo-harness` | `幫我針對這個專案評估並產生 AGENTS.md` |
 | 建立 sub-agent | `neo-sub-agent` | `幫我新增一個 Codex code-reviewer sub agent` |
-| 設計 Agent 編排架構 | `neo-agentic-design` | `幫我設計一個多 Agent 客服系統的拓撲結構與重試機制` |
 | 規劃 OpenTelemetry | `neo-opentelemetry` | `幫我審查 Collector 架構、韌性、安全與零程式觀測方案` |
 | 去掉 AI 腔 | `neo-stop-slop` | `把這段 PR 說明改得自然、直接一點` |
-
-## 開發
-
-```bash
-npm install
-npm test
-python3 scripts/check-skills-syntax.py --dir skills
-```
-
-## 維護技能
-
-新增或修改 skill 時，請同步檢查：
-
-1. `SKILL.md` 第一行是 `---`。
-2. frontmatter 有 `name` 與觸發導向的 `description`。
-3. `name` 與資料夾名稱一致。
-4. 深度內容放進 `references/` 或 `reference/`，範本放進 `assets/` 或 `templates/`，可執行流程放進 `scripts/`。
-5. 腳本必須非互動式，stdout 只輸出可解析資料，診斷輸出到 stderr。
-6. README 的技能清單與實際 `skills/` 內容一致。
-7. 執行 `python3 scripts/check-skills-syntax.py --dir skills` 與 `npm test`。
-
-## License
-
-MIT

package/bin/_system-instructions.js

@@ -114,6 +114,12 @@ Run all build, test, deploy, and formatting commands with minimal output flags (
 - **Build**: \`dotnet build -v q --nologo\`, \`cargo build --quiet\`, \`go build\`
 - **Lint & Format**: \`eslint --quiet\`, \`prettier --check --loglevel warn\`
 - **Deploy & Infra**: \`docker build -q .\`, \`terraform plan -no-color\`
+
+### Documentation & Comment Language Rules
+1. **Single Language per Statement**: Every title, section, paragraph, list item, table cell, or code comment must use ONLY ONE natural language (Chinese OR English). Never mix side-by-side bilingual translations in a single statement.
+   - Allowed: \`## 變更架構流程\`, \`## Architectural Flow\`, \`// 取得使用者資料\`, \`// Fetch user data\`
+   - Forbidden: \`## 變更架構流程 (Architectural Flow)\`, \`// 取得使用者資料 (Fetch user data)\`
+2. **Original Code & Terms Exempted**: File names, paths, APIs, code symbols, commands, and essential technical terms may remain in their original language.
 `;
 
 /**

package/package.json

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

package/skills/neo-harness/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: neo-harness
+description: >
+  Use this skill when you need to inspect a target project codebase and generate or improve a tailored,
+  comprehensive AGENTS.md file (Harness Workflow Specification) that enforces strict AI agent
+  harness rules, feedback sensors, execution SOP, orchestration topologies, and safety redlines.
+  Supports non-interactive script execution via scripts/generate-agents-md.py.
+  The generated AGENTS.md MUST NOT exceed 32 KiB in size.
+license: MIT
+metadata:
+  version: "1.0.0"
+  type: "unified-harness-generator"
+---
+
+# Unified Agent Harness Architect & Workflow Generator
+
+This skill integrates three core Agent engineering domains (**Harness Assessment**, **Execution Protocol**, and **Orchestration Architecture**) to analyze a target project and generate a tailored, strict `AGENTS.md` file (Harness Workflow Specification).
+
+## Core Principle
+
+```text
+Agent = Model (Reasoning & Generation) + Harness (Guides + Sensors + Gates + Topologies)
+```
+
+The generated `AGENTS.md` acts as the single source of truth governing all AI Agents operating in the project.
+
+> [!IMPORTANT]
+> **Size Constraint**: The generated `AGENTS.md` MUST NOT exceed 32 KiB (32,768 bytes) to prevent token pollution in session context windows.
+
+---
+
+## Quick Automation (Non-Interactive Generator Script)
+
+To quickly analyze a repository and generate or preview an `AGENTS.md` file, run the non-interactive script:
+
+```bash
+# Preview generated content (dry-run)
+python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir /path/to/repo --dry-run
+
+# Generate AGENTS.md directly in target repository
+python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir /path/to/repo --force
+```
+
+---
+
+## Workflow SOP
+
+### Step 1 — Perceive Target Repository
+1. Inspect project root and structure manually or via `scripts/generate-agents-md.py`:
+   - Configuration files: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, etc.
+   - Build, lint, and test toolchains.
+   - Existing guidelines: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, README.
+   - CI workflows: `.github/workflows/`, GitLab CI, etc.
+2. Identify primary languages, test suites, and fast local feedback sensors.
+
+### Step 2 — Reason & Synthesize Harness Rules
+Load detailed reference knowledge as needed:
+* **Harness Assessment & Sensors**: Read [references/harness-assessment.md](references/harness-assessment.md) to rate harnessability and define computational vs. inferential sensors.
+* **Execution Protocol & SOP**: Read [references/execution-protocol.md](references/execution-protocol.md) to enforce the 5 Harness Laws, dual-loop SOP, zero-fake pass, and antipattern rules.
+* **Orchestration Topologies**: Read [references/orchestration-patterns.md](references/orchestration-patterns.md) to select appropriate routing, chaining, or human-in-the-loop (HITL) gates.
+
+### Step 3 — Generate `AGENTS.md`
+Use `scripts/generate-agents-md.py` or [assets/AGENTS.md.template](assets/AGENTS.md.template) as the baseline template. Populate it with discovered project facts:
+1. **Feedforward Guides**: Exact coding styles, module boundaries, and domain conventions.
+2. **Deterministic Feedback Sensors**: Exact one-click test/lint/build commands.
+3. **The 5 Agent Harness Laws**: Mandatory execution principles.
+4. **Dual Closed-Loop Execution SOP**: Perceive ➔ Execute ➔ Sense ➔ Remediate.
+5. **Forbidden Antipatterns**: Strict redlines (no silent exception swallowing, no test deletion, no hallucinated signatures).
+6. **Human Decision Points & Safety Redlines**: Explicit boundaries requiring human approval.
+
+### Step 4 — Verify Size & Quality Gate
+1. Check the file size of the generated `AGENTS.md`:
+   - Must be `<= 32,768 bytes`.
+   - If over 32 KiB, prune redundant descriptions or move extended reference docs to separate files under `.agents/` or `docs/`.
+2. Validate syntax and formatting.

package/skills/neo-harness/assets/AGENTS.md.template

@@ -0,0 +1,63 @@
+# {{PROJECT_NAME}} AGENTS.md
+
+---
+
+## 1. Project Overview
+
+- **Primary Technology Stack**: `{{TECH_STACK}}`
+- **Coding & Architectural Conventions**:
+  - Follow modular architecture and existing code formatting.
+  - Inspect existing implementation files before creating new utilities.
+  - Do NOT introduce unrequested third-party dependencies.
+
+---
+
+## 2. Commands
+
+List exact command lines used for project development, testing, linting, typechecking, and building:
+
+| Command Type | Exact Command Line | Purpose / Scope |
+| :--- | :--- | :--- |
+| **Unit / Integration Tests** | `{{TEST_COMMAND}}` | Verify behavioral correctness |
+| **Type Check** | `{{TYPECHECK_COMMAND}}` | Verify static type contracts |
+| **Lint & Format** | `{{LINT_COMMAND}}` | Enforce code style and syntax rules |
+| **Build Check** | `{{BUILD_COMMAND}}` | Confirm clean compilation |
+
+---
+
+## 3. Workflow
+
+The development workflow strictly follows this 9-stage closed loop:
+
+```mermaid
+graph TD
+    Step1[1. Perceive Task] --> Step2[2. Establish Baseline]
+    Step2 --> Step3[3. Reproduce Problem]
+    Step3 --> Step4[4. Plan Edits]
+    Step4 --> Step5[5. Minimal Implementation]
+    Step5 --> Step6[6. Incremental Verification]
+    Step6 --> Step7[7. Self-Review]
+    Step7 -->|Fail| Step4
+    Step7 -->|Pass| Step9[9. Handoff upon Pass]
+```
+
+1. **Perceive Task**: Read project guidelines (`AGENTS.md`) and target source files to understand goals and constraints.
+2. **Establish Baseline**: Run existing test and build commands to confirm the project is in a stable, passing state.
+3. **Reproduce Problem**: Write or run test cases/verification steps that reliably reproduce the issue or requirement.
+4. **Plan Edits**: Decompose the task into small, atomic edit plans to avoid large single-turn changes.
+5. **Minimal Implementation**: Apply minimal code changes while preserving existing comments and public API contracts.
+6. **Incremental Verification**: Run local test, lint, and build commands immediately after each edit.
+7. **Self-Review**: Inspect diffs and execution logs; if checks fail, read full un-truncated error logs to find the root cause.
+8. **Remediate on Failure**: If verification or self-review fails, return to "Plan Edits / Minimal Implementation" to adjust.
+9. **Handoff upon Pass**: Once all verification sensors pass, present a concise report with empirical proof for handoff.
+
+---
+
+## 4. Forbidden Antipattern Redlines
+
+| Forbidden Action | Why It Is Prohibited | Required Behavior |
+| :--- | :--- | :--- |
+| **Silent Exception Swallowing** | Hides runtime failures and causes silent data corruption. | Let exceptions surface or handle explicitly with logging. |
+| **Test Deletion / Suppression** | Forces builds to pass without fixing underlying bugs. | Fix root cause in source or update contract with justification. |
+| **Hallucinated Signatures** | Invokes non-existent methods causing runtime crashes. | View symbol definition using search tools first. |
+| **Unverified Completion Claim** | Misleads user regarding feature or bug state. | Run test/build commands and present log proof. |

package/skills/neo-harness/references/execution-protocol.md

@@ -0,0 +1,47 @@
+# Agent Execution Protocol & Safety Redlines
+
+This reference provides execution laws, closed-loop SOPs, and antipattern rules for neo-harness.
+
+## The 5 Agent Harness Laws
+
+### Law 1: Feedforward First (Read Before Modify)
+- Read `AGENTS.md` and target source files before making edits.
+- Never guess API signatures, struct fields, or database schemas. Inspect authoritative files first.
+
+### Law 2: Deterministic Sensors & Verification Gates
+- Execute test/lint/build commands after every edit. Never declare completion without log proof.
+- Zero-fake pass: Never patch errors by swallowing exceptions, returning dummy fallbacks, commenting out broken assertions, or deleting failing unit tests.
+
+### Law 3: Dual Closed-Loop Execution Protocol
+- **Online Execution Loop**: Perceive ➔ Execute (Atomic Diff) ➔ Sense (Fast Local Check) ➔ Remediate (Fix using Log Evidence).
+- **Offline Evolution Loop**: Convert recurring agent errors into permanent linter rules or test cases.
+
+### Law 4: Context Collapse Defense & State Persistence
+- Maintain disk-based progress files (`Plan.md` or `Progress.md`) for long-horizon or multi-file tasks.
+- Keep single-turn code diffs small and targeted.
+
+### Law 5: Human Decision Points & Safety Redlines
+Immediately pause and request human intervention when encountering:
+- Destructive file/database operations or git history resets.
+- Secret/credential exposures or modifications.
+- High-risk production deployments, compliance, or architecture trade-offs.
+
+---
+
+## High-Risk Antipattern Redlines
+
+| Forbidden Antipattern | Description & Hazard | Mandatory Alternative |
+| :--- | :--- | :--- |
+| **Silent Exception Swallowing** | Wrapping errors in empty `try/catch` or returning empty default values. | Surface errors or handle explicitly with verified logging. |
+| **Test Deletion / Suppression** | Deleting or commenting out failing test assertions to pass CI. | Fix root cause in source code or update test contract with justification. |
+| **Hallucinated Signatures** | Calling functions without reading their definition file. | View target symbol definition file first using code search. |
+| **Unverified Completion Claim** | Telling the user a task is fixed without running verification commands. | Run exact test/build commands and present log proof. |
+
+---
+
+## Log-Driven Diagnostic Checklist
+
+1. When a command fails, fetch and read the complete, un-truncated error log.
+2. Identify the exact file line number and root cause exception message.
+3. Formulate a targeted fix addressing the root cause, not just masking the symptom.
+4. Re-run verification commands to confirm the fix works cleanly.

package/skills/neo-harness/references/harness-assessment.md

@@ -0,0 +1,67 @@
+# Harness Assessment & Sensor Design
+
+This reference provides harness evaluation, sensor classification, and maturity rating guidance for neo-harness.
+
+## Core Model
+
+An Agent Harness is the complete external control system wrapped around an LLM model:
+
+```text
+Agent = Model + Harness
+```
+
+A robust harness fulfills two primary objectives:
+1. **Increase First-Time Accuracy**: Provide clear feedforward guidance before code generation.
+2. **Enable Autonomous Remediation**: Provide fast, deterministic feedback sensors so the agent self-corrects before human review.
+
+---
+
+## 1. Feedforward Guides (Before Action)
+
+Feedforward controls shape agent output before any edits occur:
+- Project instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`).
+- Coding style references, architecture documentation, module boundary maps.
+- Task breakdown templates and domain vocabulary glossaries.
+
+---
+
+## 2. Feedback Sensors (After Action)
+
+Feedback sensors evaluate generated code and provide correction signals.
+
+### Computational Sensors (Fast & Deterministic)
+Prefer computational sensors whenever available:
+- **Type Checking**: `tsc`, `mypy`, `pyright`, `go vet`, `cargo check`.
+- **Unit & Integration Tests**: `npm test`, `pytest`, `cargo test`, `go test`.
+- **Linters & Formatters**: `eslint`, `flake8`, `ruff`, `prettier`.
+- **Security & Dependency Scanners**: `npm audit`, `trivy`, secret scanners.
+
+### Inferential Sensors (Semantic & Judgment)
+Use inferential sensors when deterministic tools are insufficient:
+- AI Code Reviews & LLM Judges.
+- Architecture fitness reviews.
+- Acceptance criteria verification.
+
+---
+
+## 3. Harnessability Maturity Model
+
+Rate target repository harnessability as **Low**, **Medium**, or **High**:
+
+| Rating | Characteristics | Required Actions |
+| :--- | :--- | :--- |
+| **Low (低)** | Missing test suites, no single-command test runner, ambiguous coding style, unconfigured linters. | Establish baseline test runners and lint commands before delegating multi-file agent tasks. |
+| **Medium (中)** | Tests exist but run slowly; linters present but not enforced in CI; partial `AGENTS.md`. | Define exact fast-sensor commands in `AGENTS.md`; break tasks into atomic verifiable steps. |
+| **High (高)** | Single-command fast test/lint/build runners; strict CI enforcement; clear module boundaries and explicit `AGENTS.md`. | Fully leverage autonomous closed-loop execution and scheduled/loop automations. |
+
+---
+
+## 4. Loop Primitives & State Persistence
+
+When workflows extend beyond a single session:
+1. **Automations**: Scheduled triggers for periodic maintenance or exploration.
+2. **Worktrees**: Git worktree isolation for parallel agent executions.
+3. **Skills**: Modularized domain knowledge in `SKILL.md`.
+4. **Connectors**: External tools (CI, issue trackers, messaging).
+5. **Sub-agents**: Separation of generation (Maker) and verification (Checker).
+6. **State**: Disk-persisted progress tracking (`Plan.md`, `Progress.md`).

package/skills/neo-harness/references/orchestration-patterns.md

@@ -0,0 +1,46 @@
+# LLM Orchestration Patterns & Topology Design
+
+This reference provides LLM agent orchestration architectures and safety guardrails for neo-harness.
+
+## Core Orchestration Patterns
+
+### 1. Prompt Chaining
+Decompose complex tasks into sequential, dependent sub-tasks. Output of Step A feeds into Step B.
+
+### 2. Routing
+Dynamically route requests to specialized sub-agents or tools based on classification or semantic input.
+
+### 3. Parallelization
+Run independent sub-tasks concurrently (e.g., section generation or multi-perspective reviews) and synthesize results.
+
+### 4. Reflection & Self-Correction
+Evaluate generated output against quality criteria or test feedback, then iterate.
+> [!WARNING]
+> Always enforce a maximum iteration limit (3–5 cycles) to prevent infinite loops.
+
+### 5. Human-in-the-Loop (HITL) Gates
+Insert explicit review checkpoints for high-risk operations (e.g., database schema migrations, external API calls, financial actions).
+
+---
+
+## Standard Topology Diagram (Mermaid)
+
+When documenting an Agent workflow in `AGENTS.md`, include a concise Mermaid topology:
+
+```mermaid
+graph TD
+    UserReq[User Request / Goal] --> Perceive[Perceive & Plan Step]
+    Perceive --> Execute[Atomic Code Edit]
+    Execute --> Sense{Local Sensor Check}
+    Sense -->|Pass| HITL{HITL Gate / Approval}
+    Sense -->|Fail| Remediate[Log-driven Self-Correction]
+    Remediate --> Execute
+    HITL -->|Approved| Done[Complete & Commit]
+```
+
+---
+
+## Context Window Guardrails
+
+1. **Context Pruning Protection**: Protect system prompts, project rules, and active task state from being pruned during context compaction.
+2. **Size Enforcement**: Keep project instruction files (like `AGENTS.md`) under 32 KiB (32,768 bytes) to preserve prompt headroom.