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.mdandCLAUDE.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 -> Fixworkflow - 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:
- Project name(or automatically identify it from the current directory name)
- Tech stack(optional, e.g. "React + Node.js", "Python FastAPI", "Go microservices")
- 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):
- Spec before code: No implementation is allowed without a written spec
- Criteria testable: Every feature must have machine-verifiable acceptance criteria
- Self-check before evaluation: Before the Evaluator runs, the Generator must first complete a self-check
- Loop awareness: Editing the same file more than 5 times must stop for a retrospective
- 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 轮)→ 完成