SuperAPI AI Directory

harness-engineering

General & other

View repository

Updated 10-16 09:30

About this skill

Harness Engineering framework

One-click initialize the complete Harness Engineering development framework in any project directory.

This skill combines practices from OpenAI (Codex), Anthropic (three-agent collaboration), and LangChain (self-verification loop). The initialization includes:

  • 3-agent architecture: Planner (spec), Generator (implementation), Evaluator (testing)
  • Codex + Claude dual entry points:AGENTS.md and CLAUDE.md
  • Sprint Contract: Define machine-verifiable "completion criteria" before coding
  • Dual Hook runtime:Claude hooks(.claude)+ Codex hooks(.codex)
  • Slash commands:/plan、/build、/qa、/sprint
  • Golden principles: 10 non-negotiable rules uniformly enforced across agents

Applicable scenarios

  • Starting a new project and hoping to quickly establish a structured AI collaborative development process
  • Need to implement in the current project Plan -> Build -> Verify -> Fix workflow
  • User mentions similar intents such as "harness / init harness / setup framework"

Initialization process

Step 1: Collect project information

Before generating files, first confirm with the user:

  1. Project name(or automatically identify it from the current directory name)
  2. Tech stack(optional, e.g. "React + Node.js", "Python FastAPI", "Go microservices")
  3. Project type(web application, API service, CLI tool, library, etc.)

If the user provides a description through /harness <description> , extract the above information directly from the context.

Step 2: Generate framework files

Run the scaffolding script:

python3 {{SKILL_PATH}}/scripts/scaffold.py --project-name "<PROJECT_NAME>" --tech-stack "<TECH_STACK>" --project-type "<PROJECT_TYPE>" --target-dir "<CURRENT_PROJECT_DIR>"

The following structure will be generated in the current project:

<project>/
  AGENTS.md                        # Codex 指南 / 入口
  CLAUDE.md                        # 项目地图(<80 行)
  .codex/
    config.toml                    # 启用 Codex hooks
    hooks.json                     # Codex hook 注册表
    hooks/
      loop-detector.py             # PreToolUse 循环守卫
      pre-completion-check.py      # Stop 阶段检查提醒
      context-injector.py          # UserPromptSubmit 上下文注入
  .claude/
    agents/
      planner.md                   # 规格生成智能体
      generator.md                 # 实现智能体
      evaluator.md                 # 测试/评分智能体
      doc-gardener.md              # 文档新鲜度智能体
    commands/
      plan.md                      # /plan 命令
      build.md                     # /build 命令
      qa.md                        # /qa 命令
      sprint.md                    # /sprint 命令
    hooks/
      loop-detector.py             # 文件编辑循环检测
      pre-completion-check.py      # 任务完成检查清单
      context-injector.py          # 会话上下文中间件
  docs/
    architecture.md                # 系统设计
    golden-principles.md           # 不可妥协规则
    sprint-workflow.md             # 冲刺流程
    contracts/
      TEMPLATE.md                  # 冲刺契约模板
    specs/                         # (由 planner 产出)
    plans/                         # (由 planner 产出)

Step 3: Configure Hooks

scaffold.py will automatically complete the Hook configuration:

  • Claude hooks: merge-write into .claude/settings.json(create if it does not exist)
  • Codex hooks: merge-write into .codex/hooks.json(create if it does not exist), and generate .codex/config.toml

Step 4: Verify installation result

Confirm that key files have been generated:

ls -la AGENTS.md CLAUDE.md .codex/ .codex/hooks/ .claude/agents/ .claude/commands/ .claude/hooks/ docs/

Run Codex hook self-check:

test -f .codex/config.toml && \
test -f .codex/hooks.json && \
test -f .codex/hooks/context-injector.py && \
test -f .codex/hooks/loop-detector.py && \
test -f .codex/hooks/pre-completion-check.py && \
python3 -m py_compile .codex/hooks/context-injector.py .codex/hooks/loop-detector.py .codex/hooks/pre-completion-check.py && \
echo "Codex hooks: OK"

Expected result:

  • Command exit code is 0
  • Output includes Codex hooks: OK

Finally report to the user "what was created" and "how to start using it".

How to use after initialization is complete

Command Purpose
/plan <description> Generate a feature spec based on 1-4 sentences
/build Implement the latest spec according to the sprint process
/qa Evaluate the current code
/sprint <description> Execute the complete Plan-Build-Verify cycle from scratch

Codex users can trigger the same process through a prompt:

  • plan <description>
  • build <spec>
  • qa <contract>
  • sprint <description>

The Codex hook runtime will be generated at:

  • .codex/config.toml
  • .codex/hooks.json
  • .codex/hooks/*.py

Codex's execution details (intent routing, output contract, stop conditions) are defined in the generated AGENTS.md .

Core principles

The framework will enforce the following rules (after installation, see docs/golden-principles.md):

  1. Spec before code: No implementation is allowed without a written spec
  2. Criteria testable: Every feature must have machine-verifiable acceptance criteria
  3. Self-check before evaluation: Before the Evaluator runs, the Generator must first complete a self-check
  4. Loop awareness: Editing the same file more than 5 times must stop for a retrospective
  5. Contract-driven: Before coding, define "done" through a Sprint Contract

Architecture flow

For complete details, please read the docs/architecture.mdgenerated after installation. The key flow is as follows:

用户需求 → Planner(产出 spec)→ Generator + Evaluator 协商契约
→ Generator 实现 → Evaluator 测试 → 修复循环(最多 3 轮)→ 完成