@moon791017/neo-skills 1.1.23 → 1.1.25

package/AGENTS.md

@@ -46,8 +46,8 @@ graph TD
 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.
+7. **Self-Review**: After an AI Agent finishes modifying code, tests, configuration, or scripts, activate `neo-code-review` and review the current uncommitted working tree with `--working-tree`. 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 review finds a critical issue, the review scope is unclear, or the skill cannot be loaded, do not declare completion or hand off. Return to "Plan Edits / Minimal Implementation", then rerun verification and `neo-code-review` after each remediation.
 9. **Handoff upon Pass**: Once all verification sensors pass, present a concise report with empirical proof for handoff.
 
 ---

package/package.json

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

package/skills/neo-code-review/SKILL.md

@@ -1,81 +1,70 @@
 ---
 name: neo-code-review
 description: >
-  Use this skill when the user asks for a code review, audit, PR/diff review, bug
-  risk scan, security/performance/style feedback, or validation of recent changes.
-  Prioritize actionable findings with file and line evidence.
+  Use this skill when the user asks to review or audit source code, a PR, diff, commit,
+  or recent changes for bugs, security, performance, tests, compatibility, or
+  maintainability. Also use it after an AI agent finishes modifying code to inspect the
+  current uncommitted working tree before handoff and report actionable findings with
+  file and line evidence.
+compatibility: Requires Python 3.11+ and uv for the Git change helper.
 ---
 
-# Code Review Specifications
+# Code Review
 
-Apply the Reviewer Pattern. Follow this protocol strictly to systematically, objectively, and constructively review the user's code changes.
+Use the Reviewer workflow. Keep the review read-only and report only evidence-backed, actionable findings.
 
----
-
-## 1. Perceive Phase
+## Trigger On
 
-1. **Identify the Input Source**:
-   - **Scenario A: Specific files are provided**
-     - If the user provides specific file paths or directly attaches code snippets in the conversation, use them as the primary targets for review.
-   - **Scenario B: No files are specified but inside a Git repository**
-     - If the user asks to "review changes", "review PR", or asks for a review without providing explicit code but the project is a Git repository, **proactively run the helper script** to fetch the changes:
-       ```bash
-       uv run skills/neo-code-review/scripts/git-diff-reviewer.py
-       ```
-     - To review only the staging area, append the `--staged` argument.
-     - To review a specific commit range, append the `--commit <range>` argument.
-   - **Scenario C: No changes detected and not a Git repository**
-     - If no code input is detected and the environment is not a Git repository, gracefully prompt the user: "No code changes detected. Please provide a specific code snippet or file path." and terminate the review.
+- The user requests a code, PR, diff, commit, security, performance, test, or maintainability review.
+- An AI Agent finishes modifying code, tests, configuration, or scripts before handoff.
 
-2. **Identify Programming Languages & Frameworks**:
-   - Identify the programming language (e.g., TypeScript, C#, Python) and relevant frameworks in the code changes to apply language-specific style standards in subsequent phases.
+## Workflow
 
----
+1. **Collect the review scope**
+   - Use the files or code snippets supplied by the user as the primary scope.
+   - If no scope is supplied inside a Git repository, run:
+     ```bash
+     uv run skills/neo-code-review/scripts/git-diff-reviewer.py --working-tree
+     ```
+   - Use `--staged` for staged-only changes and `--commit <range>` for a commit range.
+   - Read surrounding code, related tests, and existing contracts. If no reviewable input exists, report it and stop.
 
-## 2. Reason Phase
+2. **Load the rules**
+   - Read [review-checklist.md](references/review-checklist.md) before evaluating code.
+   - Identify the actual language, framework, and affected behavior from the change. Do not infer unverified rules from filenames.
 
-1. **Load the Review Checklist**:
-   - Before evaluating any code, **always read** the external review checklist reference:
-     [review-checklist.md](file:///Users/ben/Projects/neo-skills/skills/neo-code-review/references/review-checklist.md)
-   
-2. **Systematically Evaluate Code**:
-   - Analyze the code logic deeply and compare it against the checklist dimensions: Correctness, Regression Risk, Security, Performance, Data & Concurrency, Test Gaps, SOLID/Design Principles, Logging/Observability, Maintainability, and Style.
-   - Prioritize evidence-backed findings that create concrete behavioral, security, operational, compatibility, or maintainability risk.
-   - Filter out **🔴 Critical Issues (Must-fix)** for defects such as requirement breakage, security vulnerabilities, data corruption/loss, broken authorization, severe regressions, or production-impacting reliability failures.
-   - Classify lower-risk performance, design, logging, test coverage, readability, and maintainability issues under **🟡 Suggestions** when they have a clear reason and actionable remediation.
-
----
+3. **Analyze risk**
+   - Prioritize correctness, regressions, security, data consistency, resource lifetime, concurrency, and high-risk test gaps.
+   - `🔴 Critical Issues` contain only security vulnerabilities, data loss, incorrect behavior, authorization bypasses, or major regressions.
+   - `🟡 Suggestions` contain only actionable, non-blocking issues with a clear impact and remediation direction.
+   - Do not report preferences, unsupported speculation, or checklist items that were not triggered by evidence.
 
-## 3. Act Phase
+4. **Produce a concise report**
+   - Write in English and preserve file paths and line numbers, such as `src/user.ts:42`.
+   - Use this structure. Write `None` when a section has no findings; do not omit the severity sections:
 
-Generate a highly structured and elegant Code Review Report in **Traditional Chinese (Taiwan)**. The report must strictly follow this format:
+     ```markdown
+     ## 🔍 Review Summary
+     - **Status**: `🟢 Ready to deliver`, `🟡 Fix recommended`, `🔴 Delivery blocked`, or `⚪ No reviewable changes`
+     - **Scope**: Files or changes that were inspected.
 
-### 🔍 審查摘要 (Summary)
-- **整體評估 (Overall Assessment)**: Provide a brief summary and a clear status rating (e.g., "🔴 需要重大修正後合併" (Needs major changes before merging), "🟡 建議修正後合併" (Recommended to fix before merging), "🟢 結構優良，隨時可合併" (Excellent structure, ready to merge)).
-- **變更概述 (Change Overview)**: Briefly describe the main purpose and scope of this change.
+     ## 🔴 Critical Issues
+     - **Location**: `path:line`
+       - **Problem**: Specific behavioral defect.
+       - **Impact**: Verifiable consequence.
+       - **Fix**: Concrete remediation direction; include code only when it clarifies the fix.
 
-### 🔴 嚴重問題 (Critical Issues)
-*This section must ONLY contain **Must-fix** items (security vulnerabilities, critical logic bugs, or severe flaws that may cause system failure). If none are found, write "無" (None).*
-- **[檔案路徑 / 程式碼區段]** (File Path / Code Snippet)
-  - **問題描述 (Problem Description)**: Clearly state what the problem is.
-  - **嚴重原因 (Severity Reason)**: Explain *why* this is a critical issue and its potential consequences.
-  - **修復方案 (Remediation)**: Provide a **concrete corrected code snippet (Code Snippet)** comparing it with the original or showing the fixed version.
+     ## 🟡 Suggestions
+     - **Location**: `path:line`
+       - **Recommendation**: Specific, non-blocking improvement.
 
-### 🟡 改進建議 (Suggestions)
-*Includes suggestions for performance optimization, clean code refactoring, edge-case handling, and comment improvements.*
-- **[檔案路徑 / 程式碼區段]** (File Path / Code Snippet)
-  - **建議事項 (Recommendation)**: How to optimize the code for performance, readability, or maintainability.
-  - **推薦做法 (Proposed Fix)**: Provide an optimized code example.
-
-### 🟢 優秀之處 (Praise) (Optional)
-- Highlight exceptionally well-written, elegant, highly readable, or well-tested code sections to encourage best practices.
-
-### ❓ 疑問與釐清 (Questions) (Optional)
-- Ask objective questions regarding business logic or unexpected implementations to seek clarification from the user.
-
----
+     ## 🟢 Strengths
+     - List only strengths directly supported by the change.
 
-## 4. Communication Guidelines
+     ## Validation
+     - List executed tests, builds, or checks that were not run.
+     ```
 
-- **Focus on the Code, not the Coder**: Be constructive, objective, respectful, and humble.
-- **Provide Code Snippets**: Always provide a "corrected code example" for identified issues where applicable. Avoid purely theoretical descriptions.
+5. **Apply the delivery gate**
+   - If an automatic review finds `🔴 Critical Issues`, cannot establish the review scope, or cannot load the skill, do not declare completion or hand off.
+   - After fixing findings, rerun the required checks and review the changes again.

package/skills/neo-code-review/evals/eval_queries.json

@@ -1,26 +1,28 @@
 {
   "should_trigger": [
-    "請幫我對這個拉取請求 (PR) 進行代碼審查",
-    "這段程式碼有沒有潛在的 Bug 或記憶體洩漏？",
-    "幫我看一下這個 JavaScript 檔案的安全性寫得怎麼樣",
-    "audit this python script for potential SQL injection or security flaws",
-    "我們今天的 git 變更寫得如何？執行 code review",
-    "review my latest git commit changes",
-    "幫我重構並審查這段 C# 程式碼，看有沒有違反 SOLID 原則",
-    "這段 TypeScript 程式碼寫得好嗎？有沒有改進空間？",
-    "檢查一下這段 SQL 查詢的效能，會不會有慢查詢或缺少索引的問題",
-    "進行靜態代碼分析，指出這個 Go 專案中的問題"
+    "Please review this pull request for correctness and regressions",
+    "Does this code contain potential bugs or memory leaks?",
+    "Review the security of this JavaScript file",
+    "Audit this Python script for potential SQL injection or security flaws",
+    "Review today's Git changes",
+    "Review the changes in my latest Git commit",
+    "Refactor and review this C# code for SOLID violations",
+    "Is this TypeScript code well designed? What should be improved?",
+    "Check this SQL query for performance problems, slow queries, or missing indexes",
+    "Run static code analysis and identify problems in this Go project",
+    "An AI Agent just finished modifying code. Review the uncommitted changes before handoff"
   ],
   "should_not_trigger": [
-    "如何安裝 git？",
-    "請幫我寫一個能夠上傳檔案的 FastAPI 後端介面",
-    "解釋一下什麼是 N+1 查詢問題與如何解決",
-    "幫我建立一個全新的 React 專案",
-    "請推薦好用的 Python Linter 工具",
-    "如何配置 tsconfig.json 來支援 ESM？",
-    "在 MacOS 上如何部署 Docker 容器？",
-    "幫我把這段 Python 代碼翻譯成 Rust",
-    "什麼是 SQL Injection 的原理？",
-    "幫我產生一份今天的開發進度週報"
+    "How do I install Git?",
+    "Write a FastAPI endpoint that uploads files",
+    "Explain the N+1 query problem and how to solve it",
+    "Create a new React project",
+    "Recommend a Python linter",
+    "How do I configure tsconfig.json for ESM?",
+    "How do I deploy a Docker container on macOS?",
+    "Translate this Python code into Rust",
+    "What is the principle behind SQL injection?",
+    "Generate today's development progress report",
+    "Run the current project's tests only; do not perform a code review"
   ]
 }

package/skills/neo-code-review/evals/evals.json

@@ -3,27 +3,38 @@
   "evals": [
     {
       "id": 1,
-      "prompt": "請幫我審查這段 Python 程式碼：\n```python\nimport sqlite3\n\ndef get_user_data(user_id):\n    conn = sqlite3.connect('users.db')\n    cursor = conn.cursor()\n    # 存在 SQL 注入風險與資源未關閉\n    query = f\"SELECT * FROM users WHERE id = '{user_id}'\"\n    cursor.execute(query)\n    return cursor.fetchall()\n```",
-      "expected_output": "結構化的代碼審查報告。必須明確指出 `user_id` 的 SQL 注入漏洞 (🔴 嚴重問題)，指出資料庫連接未釋放的效能/資源問題 (🟡 改進建議)，並提供參數化查詢與 `with` 語法糖的修正程式碼範例。報告應全為繁體中文，且包含標準的審查摘要與結構標題。",
+      "prompt": "Review this Python code:\n```python\nimport sqlite3\n\ndef get_user_data(user_id):\n    conn = sqlite3.connect('users.db')\n    cursor = conn.cursor()\n    query = f\"SELECT * FROM users WHERE id = '{user_id}'\"\n    cursor.execute(query)\n    return cursor.fetchall()\n```",
+      "expected_output": "A concise English review report. It must identify SQL injection caused by user_id and the unreleased database resources, classify SQL injection as a 🔴 Critical Issue, and provide concrete remediation using a parameterized query and resource management.",
       "assertions": [
-        "輸出包含 '🔍 審查摘要'",
-        "輸出包含 '🔴 嚴重問題'",
-        "輸出包含 '🟡 改進建議'",
-        "報告使用繁體中文 (台灣)",
-        "報告中指出 SQL 注入 (SQL Injection) 漏洞",
-        "報告中指出資料庫連接或 cursor 未正確釋放/關閉的問題",
-        "提供使用參數化查詢 (parameterized query) 或 with 語法的修復代碼範例"
+        "The output contains '🔍 Review Summary', '🔴 Critical Issues', '🟡 Suggestions', and '## Validation'",
+        "The report identifies the SQL injection vulnerability and its verifiable impact",
+        "The report identifies the database connection or cursor resource leak",
+        "The report classifies SQL injection as a delivery-blocking issue",
+        "The report provides remediation using a parameterized query and resource management",
+        "The report is written in English and contains no unsupported additional findings"
       ]
     },
     {
       "id": 2,
-      "prompt": "審查這段沒有明顯問題的 TypeScript 程式碼，並給出建議：\n```typescript\nexport interface User {\n  id: string;\n  name: string;\n  email: string;\n}\n\nexport function formatUserGreeting(user: User): string {\n  return `Hello, ${user.name}! Welcome back.`;\n}\n```",
-      "expected_output": "給予正面評價的繁體中文審查報告，包含摘要、優秀之處 (🟢 優秀之處)，且無嚴重的 Must-fix 問題。可能包含一些關於型別定義或未來擴充性的輕微建議。",
+      "prompt": "Review this TypeScript code with no obvious problems and provide recommendations:\n```typescript\nexport interface User {\n  id: string;\n  name: string;\n  email: string;\n}\n\nexport function formatUserGreeting(user: User): string {\n  return `Hello, ${user.name}! Welcome back.`;\n}\n```",
+      "expected_output": "A concise English review report. 🔴 Critical Issues must be None, the status must not block delivery, and the 🟢 Strengths section should recognize the clear types and simple function design.",
       "assertions": [
-        "輸出包含 '🔍 審查摘要'",
-        "報告中沒有將此代碼列為 '🔴 嚴重問題' (Must-fix)",
-        "輸出包含 '🟢 優秀之處'",
-        "報告中讚賞其簡單明瞭、型別定義清晰與具備良好的可讀性"
+        "The output contains '🔍 Review Summary', '🔴 Critical Issues', '🟢 Strengths', and '## Validation'",
+        "The 🔴 Critical Issues section explicitly says None",
+        "The report does not invent security, performance, or test defects",
+        "The report recognizes clear type definitions, simple logic, and good readability"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "An AI Agent just finished modifying code, tests, and configuration. Before handoff, run neo-code-review against the current uncommitted working tree, including staged, unstaged, and untracked files. Stop delivery if critical issues are found.",
+      "expected_output": "A concise English report scoped to the current uncommitted working tree. It must cite actual file and line evidence and use 🔴 Critical Issues to decide whether delivery is blocked. If no readable changes exist, it must state that no reviewable changes were found without inventing findings.",
+      "assertions": [
+        "The report confirms that the current uncommitted working tree was reviewed",
+        "The report distinguishes the staged, unstaged, and untracked file inputs",
+        "The report cites file paths and line numbers or clearly explains why they are unavailable",
+        "If 🔴 Critical Issues are found, the status blocks delivery",
+        "The report invents no findings when no changes exist"
       ]
     }
   ]

package/skills/neo-code-review/scripts/git-diff-reviewer.py

@@ -4,168 +4,232 @@
 # dependencies = []
 # ///
 
-"""
-AI Agentic Git Diff & Code Reader Tool (Non-interactive)
-專為 AI Agent 設計的非互動式程式碼變更與內容擷取腳本。
+"""Non-interactive Git change and file reader for AI Agents.
 
-設計要點：
-1. 嚴禁任何互動式提示詞 (input(), confirm())。
-2. 診斷日誌、錯誤訊息一律寫入 sys.stderr。
-3. 處理結果一律以乾淨的 JSON 結構輸出至 sys.stdout (或寫入指定 --output 檔案)。
+Output rules:
+1. Never request interactive input.
+2. Write diagnostics to stderr.
+3. Write JSON results to stdout or the file supplied with --output.
 """
 
-import sys
 import argparse
-import subprocess
 import json
 import os
-from typing import Dict, List, Any
+import subprocess
+import sys
+from typing import Any, Dict, List
+
 
 def log_diagnostic(message: str) -> None:
-    """將診斷日誌印至 stderr，避免污染 stdout 的 JSON。"""
+    """Write a diagnostic message to stderr."""
     print(f"[LOG] {message}", file=sys.stderr)
 
+
 def run_command(cmd: List[str]) -> str:
-    """執行 shell 命令並返回 stdout，出錯時拋出異常。"""
+    """Run a command and return stdout while preserving stderr on failure."""
     try:
         result = subprocess.run(
             cmd,
             capture_output=True,
             text=True,
-            check=True
+            check=True,
         )
         return result.stdout
-    except subprocess.CalledProcessError as e:
-        error_msg = f"命令執行失敗: {' '.join(cmd)}\nStderr: {e.stderr}"
-        raise RuntimeError(error_msg)
+    except subprocess.CalledProcessError as error:
+        raise RuntimeError(
+            f"Command failed: {' '.join(cmd)}\nStderr: {error.stderr}"
+        ) from error
+
+
+def is_git_repository() -> bool:
+    """Return whether the current path is inside a Git worktree."""
+    try:
+        run_command(["git", "rev-parse", "--is-inside-work-tree"])
+        return True
+    except RuntimeError:
+        return False
 
-def get_git_diff(staged_only: bool = False, commit_range: str = None) -> str:
-    """根據參數獲取 git diff 內容。"""
+
+def has_git_head() -> bool:
+    """Return whether the repository has at least one commit."""
+    try:
+        run_command(["git", "rev-parse", "--verify", "HEAD"])
+        return True
+    except RuntimeError:
+        return False
+
+
+def get_git_diff(staged_only: bool = False, commit_range: str | None = None) -> str:
+    """Get staged changes or a requested commit range."""
     cmd = ["git", "diff"]
     if commit_range:
         cmd.append(commit_range)
     elif staged_only:
         cmd.append("--cached")
-    
-    log_diagnostic(f"執行 Git 命令: {' '.join(cmd)}")
+
+    log_diagnostic(f"Running Git command: {' '.join(cmd)}")
     return run_command(cmd)
 
+
+def get_working_tree_diff() -> str:
+    """Get tracked changes after HEAD, including staged and unstaged changes."""
+    if has_git_head():
+        cmd = ["git", "diff", "HEAD", "--"]
+        log_diagnostic(f"Running Git command: {' '.join(cmd)}")
+        return run_command(cmd)
+
+    log_diagnostic("The repository has no HEAD; collecting staged and unstaged changes separately.")
+    parts = [
+        run_command(["git", "diff", "--cached", "--"]),
+        run_command(["git", "diff", "--"]),
+    ]
+    return "\n".join(part for part in parts if part.strip())
+
+
+def get_untracked_files() -> List[str]:
+    """Get non-ignored untracked files while preserving spaces in paths."""
+    output = run_command(["git", "ls-files", "--others", "--exclude-standard", "-z"])
+    return [path for path in output.split("\0") if path]
+
+
 def read_files_content(paths: List[str]) -> List[Dict[str, str]]:
-    """讀取指定檔案的完整內容。"""
-    contents = []
+    """Read the contents of the supplied files."""
+    contents: List[Dict[str, str]] = []
     for path in paths:
         if not os.path.exists(path):
-            log_diagnostic(f"[警告] 檔案不存在，跳過: {path}")
+            log_diagnostic(f"[WARN] File does not exist; skipping: {path}")
             continue
         if os.path.isdir(path):
-            log_diagnostic(f"[警告] 路徑是目錄，跳過: {path}")
+            log_diagnostic(f"[WARN] Path is a directory; skipping: {path}")
             continue
-            
+
         try:
-            log_diagnostic(f"讀取檔案內容: {path}")
-            with open(path, "r", encoding="utf-8", errors="ignore") as f:
-                contents.append({
-                    "path": path,
-                    "content": f.read()
-                })
-        except Exception as e:
-            log_diagnostic(f"[錯誤] 無法讀取檔案 {path}: {str(e)}")
-            
+            log_diagnostic(f"Reading file: {path}")
+            with open(path, "r", encoding="utf-8", errors="ignore") as file:
+                contents.append({"path": path, "content": file.read()})
+        except OSError as error:
+            log_diagnostic(f"[ERROR] Could not read {path}: {error}")
+
     return contents
 
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="專為 AI Agent 設計的非互動式代碼變更與內容擷取工具。",
-        epilog="使用範例: uv run git-diff-reviewer.py --staged"
+        description="Non-interactive Git change and file reader for AI Agents.",
+        epilog="Example: uv run git-diff-reviewer.py --working-tree",
     )
     parser.add_argument(
-        "-i", "--input",
+        "-i",
+        "--input",
         nargs="*",
-        help="選填。指定審查的檔案路徑列表。若未指定，將預設讀取 Git 變更。"
+        help="File paths to review; use Git change mode when omitted.",
     )
     parser.add_argument(
         "--staged",
         action="store_true",
-        help="僅讀取已暫存 (Staged) 的 Git 變更。"
+        help="Read staged Git changes only.",
+    )
+    parser.add_argument(
+        "--working-tree",
+        action="store_true",
+        help="Read tracked changes after HEAD and non-ignored untracked files.",
     )
     parser.add_argument(
         "--commit",
-        help="選填。指定 Commit 雜湊值或範圍（例如 HEAD~1..HEAD 或 commit_sha），獲取該範圍內的變更。"
+        help="Commit hash or range, for example HEAD~1..HEAD.",
     )
     parser.add_argument(
-        "-o", "--output",
-        help="選填。將 JSON 結果寫入指定檔案，而非輸出至 stdout。"
+        "-o",
+        "--output",
+        help="Write JSON to this file instead of stdout.",
     )
     parser.add_argument(
         "--dry-run",
         action="store_true",
-        help="模擬執行模式，僅在 stderr 輸出分析計畫，不輸出最終的代碼內容。"
+        help="Check the selected mode and Git state without reading change content.",
     )
-    return parser.parse_args()
+    args = parser.parse_args()
+
+    selectors = [
+        bool(args.input),
+        args.staged,
+        args.working_tree,
+        bool(args.commit),
+    ]
+    if sum(selectors) > 1:
+        raise ValueError(
+            "The --input, --staged, --working-tree, and --commit options are mutually exclusive."
+        )
+
+    return args
+
 
 def main() -> None:
     try:
         args = parse_args()
-        
-        # 準備回傳的結構化資料
         result: Dict[str, Any] = {
             "mode": "git-diff",
             "diff": "",
             "files": [],
-            "status": "success"
+            "status": "success",
         }
-        
-        # 1. 如果指定了具體檔案
+
         if args.input:
             result["mode"] = "specific-files"
-            log_diagnostic(f"指定檔案審查模式。目標檔案數: {len(args.input)}")
+            log_diagnostic(f"Specific-file review mode; file count: {len(args.input)}")
             if not args.dry_run:
                 result["files"] = read_files_content(args.input)
-        
-        # 2. 否則，預設使用 Git 變更模式
         else:
-            result["mode"] = "git-diff"
-            log_diagnostic("未指定特定檔案，進入 Git 變更審查模式。")
-            
-            # 先檢查是否為 git 專案
-            try:
-                run_command(["git", "rev-parse", "--is-inside-work-tree"])
-            except Exception:
+            if not is_git_repository():
                 result["status"] = "error"
-                result["error_message"] = "當前目錄非 Git 專案，且未指定輸入檔案。"
-                print(json.dumps(result, indent=2))
-                log_diagnostic("[錯誤] 當前目錄非 Git 專案。")
+                result["error_message"] = "The current path is not a Git repository and no input files were supplied."
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+                log_diagnostic("[ERROR] The current path is not a Git repository.")
                 sys.exit(1)
-                
-            if not args.dry_run:
-                diff_content = get_git_diff(staged_only=args.staged, commit_range=args.commit)
-                if not diff_content.strip():
-                    log_diagnostic("未偵測到任何 Git 變更（diff 為空）。")
-                    result["status"] = "empty"
-                else:
-                    result["diff"] = diff_content
-                    
-        # 3. 輸出結果
-        output_str = json.dumps(result, indent=2)
+
+            if args.working_tree:
+                result["mode"] = "working-tree"
+                log_diagnostic("Entering working-tree review mode.")
+                if not args.dry_run:
+                    result["diff"] = get_working_tree_diff()
+                    untracked_files = get_untracked_files()
+                    result["files"] = read_files_content(untracked_files)
+                    if not result["diff"].strip() and not untracked_files:
+                        result["status"] = "empty"
+                        log_diagnostic("No tracked or untracked changes were detected.")
+            else:
+                log_diagnostic("Entering Git change review mode.")
+                if not args.dry_run:
+                    diff_content = get_git_diff(
+                        staged_only=args.staged,
+                        commit_range=args.commit,
+                    )
+                    if not diff_content.strip():
+                        result["status"] = "empty"
+                        log_diagnostic("No Git changes were detected.")
+                    else:
+                        result["diff"] = diff_content
+
+        output_str = json.dumps(result, indent=2, ensure_ascii=False)
         if args.output:
-            with open(args.output, "w", encoding="utf-8") as f:
-                f.write(output_str)
-            log_diagnostic(f"已成功將代碼變更 JSON 寫入至: {args.output}")
+            with open(args.output, "w", encoding="utf-8") as file:
+                file.write(output_str)
+            log_diagnostic(f"Wrote JSON result to: {args.output}")
         else:
-            # 乾淨地將結果印在 stdout
             print(output_str)
-            
+
         sys.exit(0)
-        
-    except Exception as e:
-        log_diagnostic(f"[致命錯誤] 執行失敗: {str(e)}")
-        # 確保即使出錯也輸出 JSON 錯誤，使調用端不易崩潰
-        error_result = {
-            "status": "error",
-            "error_message": str(e)
-        }
-        print(json.dumps(error_result, indent=2))
+    except Exception as error:
+        log_diagnostic(f"[FATAL] Execution failed: {error}")
+        print(
+            json.dumps(
+                {"status": "error", "error_message": str(error)},
+                indent=2,
+                ensure_ascii=False,
+            )
+        )
         sys.exit(1)
 
+
 if __name__ == "__main__":
     main()

package/skills/neo-harness/SKILL.md

@@ -25,7 +25,8 @@ Agent = Model (Reasoning & Generation) + Harness (Guides + Sensors + Gates + Top
 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.
+> **Template Compliance & Size Constraint**:
+> Any created or modified `AGENTS.md` MUST strictly adhere to the design specification of [`assets/AGENTS.md.template`](assets/AGENTS.md.template) (containing 4 mandatory sections: Project Overview, Commands Table, 9-stage Workflow Mermaid loop, and Forbidden Antipattern Redlines Table) and MUST NOT exceed 32 KiB (32,768 bytes).
 
 ---
 
@@ -39,6 +40,9 @@ python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir /path/to/r
 
 # Generate AGENTS.md directly in target repository
 python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir /path/to/repo --force
+
+# Validate existing AGENTS.md against assets/AGENTS.md.template design specification
+python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir /path/to/repo --validate
 ```
 
 ---
@@ -59,17 +63,18 @@ Load detailed reference knowledge as needed:
 * **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`:
+### Step 3 — Generate & Format `AGENTS.md`
+Use `scripts/generate-agents-md.py` with [assets/AGENTS.md.template](assets/AGENTS.md.template) as the strict baseline template.
+All created or modified `AGENTS.md` files MUST strictly contain the following 4 structural sections in order:
+1. **`## 1. Project Overview`**: Primary tech stack, modular architecture, and coding conventions.
+2. **`## 2. Commands`**: Standard markdown table (`Command Type`, `Exact Command Line`, `Purpose / Scope`) listing test, typecheck, lint, build, or syntax check commands.
+3. **`## 3. Workflow`**: The mandatory 9-stage closed loop Mermaid diagram (`graph TD` from Step1 to Step9) followed by the 9 numbered step definitions.
+4. **`## 4. Forbidden Antipattern Redlines`**: Standard markdown table (`Forbidden Action`, `Why It Is Prohibited`, `Required Behavior`) specifying non-negotiable redlines.
+
+### Step 4 — Verify Template Compliance & Quality Gate
+1. Validate structural compliance against `assets/AGENTS.md.template`:
+   - Run `python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir /path/to/repo --validate`.
+2. 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.
+3. Validate syntax and markdown formatting.

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

@@ -45,3 +45,20 @@ Immediately pause and request human intervention when encountering:
 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.
+
+---
+
+## AGENTS.md Template Specification Gate
+
+All created or updated `AGENTS.md` files MUST comply with the design specification of `assets/AGENTS.md.template`:
+
+1. **Mandatory Sections**:
+   - Section 1: `## 1. Project Overview` (Tech stack, architecture, modularity)
+   - Section 2: `## 2. Commands` (3-column markdown table: `Command Type`, `Exact Command Line`, `Purpose / Scope`)
+   - Section 3: `## 3. Workflow` (9-stage closed loop Mermaid diagram `graph TD` and 9 numbered steps)
+   - Section 4: `## 4. Forbidden Antipattern Redlines` (3-column markdown table: `Forbidden Action`, `Why It Is Prohibited`, `Required Behavior`)
+2. **File Size Limit**:
+   - Strictly `<= 32,768 bytes` (32 KiB).
+3. **Automated Validation**:
+   - Run `python3 skills/neo-harness/scripts/generate-agents-md.py --target-dir <repo-path> --validate`.
+

package/skills/neo-harness/scripts/generate-agents-md.py

@@ -202,9 +202,51 @@ def enforce_size_limit(content: str) -> str:
     return pruned_content
 
 
+def validate_agents_md_structure(content: str) -> list[str]:
+    """
+    Validate content against assets/AGENTS.md.template structural requirements.
+    Returns a list of error validation messages (empty list if compliant).
+    """
+    errors = []
+
+    # 1. Size limit check
+    byte_size = len(content.encode("utf-8"))
+    if byte_size > MAX_BYTES:
+        errors.append(f"File size ({byte_size} bytes) exceeds maximum limit of 32 KiB ({MAX_BYTES} bytes).")
+
+    # 2. Section 1 check
+    if "## 1. Project Overview" not in content:
+        errors.append("Missing required section: '## 1. Project Overview'")
+
+    # 3. Section 2 check
+    if "## 2. Commands" not in content:
+        errors.append("Missing required section: '## 2. Commands'")
+    else:
+        if "| Command Type | Exact Command Line | Purpose / Scope |" not in content:
+            errors.append("Section 2 missing required table header: '| Command Type | Exact Command Line | Purpose / Scope |'")
+
+    # 4. Section 3 check
+    if "## 3. Workflow" not in content:
+        errors.append("Missing required section: '## 3. Workflow'")
+    else:
+        if "```mermaid" not in content or "graph TD" not in content:
+            errors.append("Section 3 missing required Mermaid diagram ('```mermaid' with 'graph TD').")
+        if "1. **Perceive Task**" not in content or "9. **Handoff upon Pass**" not in content:
+            errors.append("Section 3 missing standard 9-stage closed loop workflow steps.")
+
+    # 5. Section 4 check
+    if "## 4. Forbidden Antipattern Redlines" not in content:
+        errors.append("Missing required section: '## 4. Forbidden Antipattern Redlines'")
+    else:
+        if "| Forbidden Action | Why It Is Prohibited | Required Behavior |" not in content:
+            errors.append("Section 4 missing required table header: '| Forbidden Action | Why It Is Prohibited | Required Behavior |'")
+
+    return errors
+
+
 def main():
     parser = argparse.ArgumentParser(
-        description="Non-interactive AGENTS.md generator for neo-harness."
+        description="Non-interactive AGENTS.md generator and validator for neo-harness."
     )
     parser.add_argument(
         "--target-dir",
@@ -228,6 +270,11 @@ def main():
         action="store_true",
         help="Overwrite output file if it already exists",
     )
+    parser.add_argument(
+        "--validate",
+        action="store_true",
+        help="Validate target AGENTS.md against AGENTS.md.template design specification",
+    )
 
     args = parser.parse_args()
 
@@ -238,6 +285,25 @@ def main():
 
     output_path = Path(args.output) if args.output else target_dir / "AGENTS.md"
 
+    if args.validate:
+        if not output_path.exists():
+            log_diag(f"Validation Error: Target file '{output_path}' does not exist.")
+            sys.exit(1)
+
+        log_diag(f"Validating AGENTS.md file: {output_path}")
+        with open(output_path, "r", encoding="utf-8") as f:
+            target_content = f.read()
+
+        val_errors = validate_agents_md_structure(target_content)
+        if val_errors:
+            log_diag("AGENTS.md Template Validation Failed:")
+            for err in val_errors:
+                log_diag(f"  - {err}")
+            sys.exit(1)
+        else:
+            log_diag(f"AGENTS.md Template Validation Passed for '{output_path}'.")
+            sys.exit(0)
+
     log_diag(f"Scanning target directory: {target_dir}")
     facts = detect_project_facts(target_dir)
     log_diag(f"Detected project name: {facts['project_name']}, tech stack: {facts['tech_stack']}")
@@ -245,6 +311,12 @@ def main():
     content = generate_agents_md_content(facts)
     content = enforce_size_limit(content)
 
+    val_errors = validate_agents_md_structure(content)
+    if val_errors:
+        log_diag("Warning: Generated AGENTS.md failed template validation:")
+        for err in val_errors:
+            log_diag(f"  - {err}")
+
     byte_size = len(content.encode("utf-8"))
     log_diag(f"Generated AGENTS.md size: {byte_size} bytes ({byte_size/1024:.2f} KiB)")
 
@@ -264,3 +336,4 @@ def main():
 
 if __name__ == "__main__":
     main()
+