neo-harness · diff
v1.0.0 to v1.0.0
17 added, 12 removed. Audit A to A.
---
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.
+ > **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).
---
## 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
+
+ # 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
```
---
## 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 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 Size & Quality Gate
- 1. Check the file size of the generated `AGENTS.md`:
+ ### 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.