@moon791017/neo-skills 1.1.24 → 1.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.24",
+  "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-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()
+