@moon791017/neo-skills 1.1.21 → 1.1.23

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

@@ -0,0 +1,266 @@
+# /// script
+# dependencies = []
+# ///
+
+"""
+generate-agents-md.py - Automated non-interactive AGENTS.md generator for neo-harness.
+
+Analyzes a target repository, detects build/test/lint toolchains, and generates
+a strict AGENTS.md file that enforces AI agent harness laws and sensor gates.
+Enforces a hard limit of 32 KiB (32,768 bytes) on the generated AGENTS.md.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+MAX_BYTES = 32768  # 32 KiB limit
+
+
+def log_diag(msg: str) -> None:
+    """Print diagnostic messages to stderr."""
+    print(f"[generate-agents-md] {msg}", file=sys.stderr)
+
+
+def detect_project_facts(target_dir: Path) -> dict:
+    """Scan the target repository and extract toolchains and project facts."""
+    facts = {
+        "project_name": target_dir.name,
+        "tech_stack": "General",
+        "test_command": "echo 'No test command configured'",
+        "lint_command": "echo 'No lint command configured'",
+        "typecheck_command": "echo 'No typecheck command configured'",
+        "build_command": "echo 'No build command configured'",
+    }
+
+    # 1. Node.js / TypeScript
+    pkg_json_path = target_dir / "package.json"
+    if pkg_json_path.exists():
+        try:
+            with open(pkg_json_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            facts["project_name"] = data.get("name", target_dir.name)
+            scripts = data.get("scripts", {})
+            facts["tech_stack"] = "Node.js / JavaScript"
+            if (target_dir / "tsconfig.json").exists():
+                facts["tech_stack"] = "Node.js / TypeScript"
+                facts["typecheck_command"] = "npx tsc --noEmit"
+
+            if "test" in scripts:
+                facts["test_command"] = "npm test"
+            if "lint" in scripts:
+                facts["lint_command"] = "npm run lint"
+            if "build" in scripts:
+                facts["build_command"] = "npm run build"
+            if "typecheck" in scripts:
+                facts["typecheck_command"] = "npm run typecheck"
+        except Exception as e:
+            log_diag(f"Warning: Failed to parse package.json: {e}")
+
+    # 2. Python
+    pyproject_path = target_dir / "pyproject.toml"
+    setup_py_path = target_dir / "setup.py"
+    if pyproject_path.exists() or setup_py_path.exists() or list(target_dir.glob("*.py")):
+        facts["tech_stack"] = "Python"
+        test_cmds = []
+        if (target_dir / "tests").exists() or (target_dir / "test").exists():
+            test_cmds.append("pytest")
+        facts["test_command"] = " && ".join(test_cmds) if test_cmds else "pytest"
+        facts["lint_command"] = "ruff check ."
+        facts["typecheck_command"] = "mypy ."
+        facts["build_command"] = "python3 -m build"
+
+    # 3. Rust
+    cargo_path = target_dir / "Cargo.toml"
+    if cargo_path.exists():
+        facts["tech_stack"] = "Rust"
+        facts["test_command"] = "cargo test"
+        facts["lint_command"] = "cargo clippy -- -D warnings"
+        facts["typecheck_command"] = "cargo check"
+        facts["build_command"] = "cargo build"
+
+    # 4. Go
+    go_mod_path = target_dir / "go.mod"
+    if go_mod_path.exists():
+        facts["tech_stack"] = "Go"
+        facts["test_command"] = "go test ./..."
+        facts["lint_command"] = "golangci-lint run"
+        facts["typecheck_command"] = "go vet ./..."
+        facts["build_command"] = "go build ./..."
+
+    # 5. .NET / C#
+    if list(target_dir.glob("*.csproj")) or list(target_dir.glob("*.sln")):
+        facts["tech_stack"] = ".NET / C#"
+        facts["test_command"] = "dotnet test"
+        facts["lint_command"] = "dotnet format --verify-no-changes"
+        facts["typecheck_command"] = "dotnet build --no-incremental"
+        facts["build_command"] = "dotnet build"
+
+    # 6. Neo Skills Syntax Check
+    syntax_script = target_dir / "scripts" / "check-skills-syntax.py"
+    if syntax_script.exists():
+        facts["syntax_command"] = "python3 scripts/check-skills-syntax.py"
+
+    return facts
+
+
+def generate_agents_md_content(facts: dict) -> str:
+    """Generate the AGENTS.md Markdown content based on project facts."""
+    rows = []
+    if facts.get("test_command") and not facts["test_command"].startswith("echo 'No"):
+        rows.append(f"| **Unit / Integration Tests** | `{facts['test_command']}` | Verify behavioral correctness |")
+    if facts.get("syntax_command") and not facts["syntax_command"].startswith("echo 'No"):
+        rows.append(f"| **Skill Syntax Check** | `{facts['syntax_command']}` | Verify skill markdown and frontmatter syntax |")
+    if facts.get("typecheck_command") and not facts["typecheck_command"].startswith("echo 'No"):
+        rows.append(f"| **Type Check** | `{facts['typecheck_command']}` | Verify static type contracts |")
+    if facts.get("lint_command") and not facts["lint_command"].startswith("echo 'No"):
+        rows.append(f"| **Lint & Format** | `{facts['lint_command']}` | Enforce code style and syntax rules |")
+    if facts.get("build_command") and not facts["build_command"].startswith("echo 'No"):
+        rows.append(f"| **Build Check** | `{facts['build_command']}` | Confirm clean compilation |")
+
+    table_header = "| Command Type | Exact Command Line | Purpose / Scope |\n| :--- | :--- | :--- |"
+    table_body = "\n".join(rows) if rows else "| **None** | `echo 'No commands configured'` | N/A |"
+    commands_table = f"{table_header}\n{table_body}"
+
+    content = f"""# {facts['project_name']} AGENTS.md
+
+---
+
+## 1. Project Overview
+
+- **Primary Technology Stack**: `{facts['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:
+
+{commands_table}
+
+---
+
+## 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. |
+"""
+    return content
+
+
+def enforce_size_limit(content: str) -> str:
+    """Ensure the content size does not exceed 32 KiB (32,768 bytes)."""
+    encoded = content.encode("utf-8")
+    if len(encoded) <= MAX_BYTES:
+        return content
+
+    log_diag(f"Warning: Content size ({len(encoded)} bytes) exceeds 32 KiB limit. Pruning...")
+    # Truncate lines from bottom if necessary, preserving structure
+    lines = content.splitlines()
+    while lines and len("\n".join(lines).encode("utf-8")) > MAX_BYTES:
+        lines.pop()
+    
+    pruned_content = "\n".join(lines) + "\n\n<!-- Truncated to fit within 32 KiB limit -->\n"
+    return pruned_content
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Non-interactive AGENTS.md generator for neo-harness."
+    )
+    parser.add_argument(
+        "--target-dir",
+        type=str,
+        default=".",
+        help="Path to target project directory (default: current directory)",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default="",
+        help="Output path for AGENTS.md (default: <target-dir>/AGENTS.md)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Output content to stdout without writing file",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite output file if it already exists",
+    )
+
+    args = parser.parse_args()
+
+    target_dir = Path(args.target_dir).resolve()
+    if not target_dir.exists() or not target_dir.is_dir():
+        log_diag(f"Error: Target directory '{target_dir}' does not exist or is not a directory.")
+        sys.exit(1)
+
+    output_path = Path(args.output) if args.output else target_dir / "AGENTS.md"
+
+    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']}")
+
+    content = generate_agents_md_content(facts)
+    content = enforce_size_limit(content)
+
+    byte_size = len(content.encode("utf-8"))
+    log_diag(f"Generated AGENTS.md size: {byte_size} bytes ({byte_size/1024:.2f} KiB)")
+
+    if args.dry_run:
+        sys.stdout.write(content)
+        return
+
+    if output_path.exists() and not args.force:
+        log_diag(f"Warning: Output file '{output_path}' exists. Use --force to overwrite.")
+        sys.exit(1)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    log_diag(f"Successfully generated '{output_path}' ({byte_size} bytes).")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,127 +0,0 @@
----
-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, 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
-
-## Trigger On
-- The user asks to design or improve an AI agent development workflow.
-- 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
-1. Inspect the repository before asking questions:
-   - Project instructions: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`.
-   - Skill or prompt assets: `skills/`, `.codex/skills/`, `.claude/skills/`, `.github/skills/`.
-   - 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.
-
-## Reason
-Analyze the project through these dimensions:
-
-1. **Feedforward guides**
-   - What should the agent know before editing?
-   - Examples: project rules, coding style, architecture boundaries, task decomposition, testing strategy, domain vocabulary, safe file ownership.
-2. **Feedback sensors**
-   - What can check the agent's work after each change?
-   - Examples: typecheck, tests, lint, build, static analysis, security checks, architecture tests, review agents, smoke tests.
-3. **Control type**
-   - Prefer computational controls for fast deterministic checks.
-   - Use inferential controls for semantic review, architecture judgment, test-quality review, and risk assessment.
-4. **Regulation category**
-   - Maintainability: readability, duplication, complexity, style, testability.
-   - Architecture fitness: module boundaries, performance, observability, security, deployability.
-   - 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 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:
-
-### 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 `高`.
-- Explain the rating with concrete evidence from the repository.
-
-### 3. Feedforward Guides 設計
-- List the rules, docs, skills, templates, or examples agents should receive before work starts.
-- Mark each item as existing, needs update, or missing.
-
-### 4. Feedback Sensors 設計
-- List fast local checks, CI checks, security checks, semantic reviews, and manual checks.
-- Distinguish computational from inferential checks.
-
-### 5. 開發前改善清單
-- 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.
-- If a command is unknown, state the missing fact instead of inventing one.
-
-## Constraints
-- Do not treat AI-generated tests as sufficient proof of behaviour correctness.
-- Do not replace deterministic tooling with LLM judgment when a fast tool can check the same thing.
-- 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.