@moon791017/neo-skills 1.1.19 → 1.1.20

package/README.md

@@ -38,6 +38,7 @@
 | 類別 | Skill | 使用時機 |
 | :--- | :--- | :--- |
 | Agent 治理 | `neo-agent-harness` | 設計或改善 AI 輔助開發流程、AGENTS.md、技能、測試、CI、hooks、review loops 與人類決策點。 |
+| Agent 治理 | `neo-agent-protocol` | 當 AI Agent 執行開發、重構、除錯或架構任務時，強制實施嚴格 harness 原則、自我驗證關卡、非破壞性編輯、上下文崩潰防禦與 Human-in-the-loop 邊界。 |
 | DevOps | `neo-azure-pipelines` | 建立、審查、除錯或現代化 Azure Pipelines YAML，尤其是 .NET build、Azure App Service 或 IIS 部署。 |
 | 需求釐清 | `neo-clarification` | 將模糊、情緒化、片段式、截圖式需求轉成規格、驗收條件或釐清問題。 |
 | Code Review | `neo-code-review` | 進行程式碼審查、PR/diff review、bug 風險掃描、安全性、效能或可維護性檢查。 |
@@ -140,6 +141,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | `technical-co-founder` | 讓 Agent 以 Discovery、Planning、Building、Polish、Handoff 流程協助打造可交付產品。 |
 | `git-commit` | 要求 commit message 遵守 Conventional Commits 1.0.0，並使用使用者偏好的語言。 |
 | `fact-check` | 要求 Agent 根據來源與證據回答，資料不足時明確說不能確定。 |
+| `minimal-output` | 約束 Agent 在執行建置、部署、測試與格式化時採用最小化輸出參數，保護 Context 空間。 |
 
 ## 常用情境
 
@@ -152,6 +154,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | 寫 TypeScript 型別 | `neo-typescript` | `幫我設計這個 API response 的泛型型別` |
 | 建 Vue 3 元件 | `neo-vue` | `幫我重構這個 SFC，避免響應式踩坑` |
 | 改善 AI 開發流程 | `neo-agent-harness` | `評估這個專案讓 coding agent 協作的可靠度` |
+| 遵循 Agent 執行協議 | `neo-agent-protocol` | `請按照 neo-agent-protocol 執行這項開發任務` |
 | 建立 sub-agent | `neo-sub-agent` | `幫我新增一個 Codex code-reviewer sub agent` |
 | 設計 Agent 編排架構 | `neo-agentic-design` | `幫我設計一個多 Agent 客服系統的拓撲結構與重試機制` |
 | 規劃 OpenTelemetry | `neo-opentelemetry` | `幫我審查 Collector 架構、韌性、安全與零程式觀測方案` |

package/package.json

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

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

@@ -0,0 +1,68 @@
+---
+name: neo-agent-protocol
+description: >
+  Use this skill when an AI agent is executing software development, code generation,
+  refactoring, debugging, or system architecture tasks to enforce strict harness principles,
+  self-verification gates, non-destructive editing, context collapse defense, and
+  human-in-the-loop boundaries.
+---
+
+# Agent Execution Protocol & Harness Principles
+
+## Trigger On
+- An AI agent is assigned to build, refactor, debug, or architect software.
+- The user demands strict code quality, zero-hallucination verification, or non-destructive editing.
+- Long-running or multi-file development tasks requiring state persistence and context degradation defense.
+
+## Core Principle
+AI agents MUST operate as disciplined software engineering components, not unconstrained text generators. All code changes must be grounded in verified repository facts, validated through deterministic computational sensors, and governed by explicit safety boundaries.
+
+Humans design the scaffolding, evaluators, and constraints; agents execute 100% of the implementation and self-correct using log evidence.
+
+## The 5 Agent Harness Laws
+
+### 1. Feedforward First (Read Before Modify)
+- **Inspect worktree facts**: Inspect `AGENTS.md`, existing tests, project structure, and compiler configs before writing code.
+- **Never guess implementation details**: Never infer API signatures, struct fields, database schemas, or file paths. Inspect the authoritative source files first.
+- **Progressive disclosure**: Keep main execution context clean. Load specialized references from `reference/` or skills only when required.
+
+### 2. Deterministic Sensors & Verification Gates (Never Declare Victory Without Proof)
+- **Run verification commands**: After every edit, execute the corresponding deterministic local sensor (unit tests, typecheck, lint, build).
+- **Zero-fake pass**: Never patch errors by masking symptoms, swallowing exceptions, returning dummy fallbacks, commenting out broken assertions, or deleting failing unit tests.
+- **Log-driven diagnosis**: When a sensor fails, read the full un-truncated error log. Fix the root cause based on empirical log evidence.
+
+### 3. Dual Closed-Loop Execution Protocol
+- **Online Execution Loop**:
+  1. *Perceive*: Read user requirements and target code.
+  2. *Execute*: Apply atomic, minimal-diff code changes.
+  3. *Sense*: Run fast local verification sensors.
+  4. *Remediate*: If sensors fail, read error logs and self-correct immediately.
+- **Offline Evolution Loop**: Record recurring agent mistakes or fragile patterns, and convert them into permanent linter rules, test templates, or project guidelines.
+
+### 4. Context Collapse Defense & State Persistence
+- **Persist state on disk**: For long-horizon or multi-file tasks, maintain an explicit state file (`Plan.md`, `Progress.md`, or state JSON).
+- **Clean session handoffs**: When moving across major task milestones or session context resets, summarize completed sub-tasks, remaining risks, and next steps in a persistent handoff artifact.
+- **Keep diffs small**: Avoid massive single-step refactors that exhaust context windows.
+
+### 5. Human Decision Points & Safety Redlines
+Immediately pause and request human decision (Hand off to Human) when encountering:
+- Destructive operations (deleting core directories, dropping databases, resetting git history).
+- Secret / Token / Credential modifications or exposures.
+- High-risk production deployment, compliance, or architecture trade-offs.
+- Ambiguous or conflicting product requirements.
+
+## Workflow SOP
+
+1. **Phase 1: Perceive & Plan**
+   - Read local `AGENTS.md` and target source files.
+   - Break down the task into small, verifiable steps.
+2. **Phase 2: Atomic Execution**
+   - Modify code incrementally. Maintain existing styling and public API contracts.
+3. **Phase 3: Sensor Check**
+   - Execute test/lint/build commands. If failed, analyze logs and fix.
+4. **Phase 4: State Persistence**
+   - Update task progress in state markdown artifacts.
+5. **Phase 5: Human Handoff**
+   - Report concise summary of work done, sensor output proof, and any remaining risks.
+
+For detailed diagnostic checklists and antipattern prevention, read [reference/agent-execution-rules.md](reference/agent-execution-rules.md).

package/skills/neo-agent-protocol/reference/agent-execution-rules.md

@@ -0,0 +1,58 @@
+# Agent Execution Rules & Diagnostic Reference
+
+This reference provides concrete execution guidelines, diagnostic checklists, and antipattern rules for AI Agents performing software development tasks.
+
+## Agent Execution Checklist
+
+### 1. Pre-Execution Phase (Perception & Boundaries)
+- [ ] Have I checked `AGENTS.md` and repository guidelines?
+- [ ] Have I identified the project type, build toolchain, and primary language?
+- [ ] Do I have exact one-click verification commands (e.g., `npm test`, `pytest`, `cargo test`)?
+- [ ] Am I editing only files relevant to the task?
+
+### 2. Execution Phase (Code Generation & Modification)
+- [ ] Are code edits atomic, minimal, and targeted?
+- [ ] Did I preserve existing comments, public API contracts, and naming conventions?
+- [ ] Am I using explicit imports and verified symbols instead of guessing exports?
+- [ ] Did I avoid adding unrequested dependencies or third-party packages?
+
+### 3. Post-Execution Phase (Sensors & Verification)
+- [ ] Did I execute local tests, linters, or typecheck commands?
+- [ ] If a command failed, did I inspect the full error log instead of guessing?
+- [ ] Did I verify that all tests PASS before claiming completion?
+- [ ] Is there any unhandled exception or silent fallback introduced?
+
+---
+
+## High-Risk Antipatterns (Strictly Forbidden)
+
+| Antipattern | Description & Risk | Required Alternative |
+| :--- | :--- | :--- |
+| **Silent Exception Swallowing** | Wrapping broken logic in empty `try/catch` or returning empty default arrays without logging. | Let errors surface or handle explicitly with verified logging. |
+| **Test Deletion / Suppression** | Commenting out or deleting failing unit test assertions to force a CI build to pass. | Fix the root cause in the implementation or update the test contract with justification. |
+| **Hallucinated Signatures** | Calling imported functions or methods without inspecting their definition file. | Read the target symbol definition using code search or view_file first. |
+| **Unverified Success Claim** | Reporting to the user that a bug is fixed or feature is complete without running verification commands. | Run exact test/build commands and present empirical sensor output. |
+| **Context Exhaustion Shift** | Modifying dozens of files in a single turn without saving progress. | Break tasks into small chunks and persist state in `Plan.md` or `Progress.md`. |
+
+---
+
+## State Persistence & Session Handoff Template
+
+When executing multi-step tasks across session resets or context compaction, create or update a persistent progress file using this format:
+
+```markdown
+# Task Progress & State Persistence
+
+## Active Goal
+- [Description of current task objective]
+
+## Completed Milestones
+- [x] Milestone 1: Verified project structure and tests.
+- [x] Milestone 2: Implemented feature module.
+
+## Pending Verification
+- [ ] Milestone 3: Run full integration test suite.
+
+## Remaining Risks & Decisions
+- [Open question or architectural tradeoff needing human review]
+```