Harness — The Codex Workflow Factory

English | 한국어 | 日本語

Harness is a Codex-native workflow factory. Say "build a harness for this project", "하네스 구성해줘", or "ハーネスを構成して", and it turns a project or domain brief into Codex-ready guidance, repo skills, optional custom subagents, and repeatable workflows.

Overview

Harness analyzes a codebase or domain and generates the operating context Codex needs for repeatable work:

• AGENTS.md pointers for durable project guidance
• .agents/skills/**/SKILL.md workflows for reusable procedures
• optional .codex/agents/*.toml custom agents for stable specialist roles
• _workspace/ conventions for intermediate artifacts and audits

Harness does not depend on a separate team runtime. Codex remains the parent agent: it reads the generated guidance, chooses skills, and spawns subagents only when the user explicitly asks for parallel or delegated agent work.

Category — Where Harness Sits

Harness sits at the L3 Meta-Factory / Codex Workflow Factory layer. It generates project-specific operating systems for Codex rather than solving one domain directly.

Layer	What it does	Neighbor
L3 — Codex Workflow Factory	Domain/project brief -> AGENTS.md + skills + optional custom agents	Harness
L3 — Runtime Configuration Factory	Deterministic runtime and environment setup	Archon-style tools
L2 — Workflow Standardization	Rules, hooks, and shared practices across generated harnesses	cross-harness tooling
L1 — Domain Harness	A concrete generated harness for one repo or domain	generated output

Key Features

• Codex artifact generation — creates AGENTS.md, repo skills, optional custom agents, and workspace conventions.
• Parent-led orchestration — uses Codex patterns such as explorer-first, fan-out/fan-in review, disjoint workers, and reviewer validation.
• Skill authoring guidance — keeps skills concise, triggerable, and progressively disclosed.
• Migration path — converts older harness layouts into Codex-native artifacts.
• Validation loop — includes structure checks, trigger checks, dry-runs, and project validation commands.

Workflow

Phase 0: Current-state audit
    ↓
Phase 1: Project/domain analysis
    ↓
Phase 2: Codex orchestration pattern selection
    ↓
Phase 3: Artifact design
    ↓
Phase 4: AGENTS.md, skills, and optional custom agents generation
    ↓
Phase 5: Runbook/orchestrator writing
    ↓
Phase 6: Validation and trigger checks
    ↓
Phase 7: Evolution from feedback

Installation

Add this repo as a Codex marketplace

codex plugin marketplace add <repo-or-local-path>

For local development from this checkout:

cd /path/to/harness
codex plugin marketplace add .

Restart Codex after adding the marketplace, then open the plugin directory:

codex
/plugins

Choose the Harness Local marketplace/source, then install harness. If it does not appear, use an absolute path (codex plugin marketplace add /path/to/harness), restart Codex, and reopen /plugins. For local marketplaces, refresh by codex plugin marketplace remove harness-local followed by codex plugin marketplace add /path/to/harness; upgrade is for Git-backed marketplaces.

This repository is the marketplace root. The installable plugin lives under plugins/harness because current Codex local marketplace discovery expects source.path to point to a child directory inside the marketplace root.

Direct skill usage during development

You can also invoke the bundled skill from this repo after the plugin is installed:

$harness build a Codex harness for this project

Plugin Structure

harness/
├── .agents/
│   └── plugins/
│       └── marketplace.json
├── plugins/
│   └── harness/
│       ├── .codex-plugin/
│       │   └── plugin.json
│       ├── assets/
│       └── skills/
│           └── harness/
│               ├── SKILL.md
│               └── references/
└── README.md

Generated Output

Harness generates files in the target project:

your-project/
├── AGENTS.md
├── .agents/
│   └── skills/
│       ├── domain-workflow/
│       │   ├── SKILL.md
│       │   └── references/
│       └── validation/
│           └── SKILL.md
├── .codex/
│   └── agents/
│       └── domain-reviewer.toml
└── _workspace/

Custom agents are optional. Harness prefers built-in explorer, worker, and default unless a reusable specialist role needs its own sandbox, model, MCP, or instructions.

Use Cases

Code review

Build a Codex harness for comprehensive code review. It should support correctness, security, performance, and test coverage review, then merge findings into one report.

Full-stack delivery

Build a harness for full-stack feature work. It should map the codebase first, split frontend/backend/test work safely, and run final validation.

Documentation

Build a harness that generates API documentation from this codebase and verifies examples against implementation.

Migration

Build a Codex harness for a framework migration. It should inventory affected files, plan batches, and validate each migrated slice.

FAQ

Is this a single agent or multi-agent system?

Harness generates Codex workflows. Most runs can stay single-threaded. When the user explicitly asks for subagents or parallel work, the generated runbooks tell the parent Codex agent how to spawn explorers, workers, or reviewers with clear ownership.

Why AGENTS.md instead of putting everything in skills?

AGENTS.md is persistent project guidance loaded before work starts, so it is ideal for a small pointer and validation expectations. Detailed workflows live in skills to avoid bloating every thread.

When should Harness create custom agents?

Only for reusable roles. One-off work should use built-in explorer, worker, or default. Custom .codex/agents/*.toml files are useful when sandbox, model effort, MCP tools, or strict role instructions should persist.

License

Apache-2.0