harness

Harness — Codex agent and skill design

Generates and verifies roles, execution procedures, and collaboration contracts suited to the project. The main session is the orchestrator. Agents define roles, and skills define reusable procedures.

Invocation contract and target project

• If the user explicitly specifies $harness or $codex-harness:harness, interpret harness construction/update as the default task. Even if the accompanying work is a generic request such as "research this topic and write an article," first configure a reusable harness in the target project and perform the accompanying work in that project. An empty directory can also be the target. If the user prohibits writing files or requests only an audit or explanation, follow that restriction.
• Without an explicit invocation, apply this skill only when the user requests construction, modification, or inspection of the harness itself. Do not turn ordinary research, writing, code changes, or questions about agent concepts into a request for automatic harness construction.
• The target project is the project path specified by the user, or, if none is specified, the project in the current working directory. Do not mistake the plugin cache where the skill is installed or this skill's source repository for the target project. If multiple projects are specified, verify each project's boundaries separately.
• The role definitions you create always go in the target project's .codex/agents/*.toml. Skills,AGENTS.md, required project settings,.harness/ execution records, and _workspace/communications/ records also go under the target project. Do not create project roles in personal-scope ~/.codex/agents/or in the plugin cache. Native agent threads are not files, and creating a role TOML and creating a thread are separate steps.

Basic principles

• Place project agents in the target project's .codex/agents/<name>.toml, and skills in .agents/skills/<name>/SKILL.md. Even if there is a separate request to install a skill in personal scope, place project role definitions and execution records in the target project.
• Create the project-local role definitions needed for the task, confirm that the parent session's actual working directory is the target project, and then create the native agent for the task. In the current spawn_agent call there is no cwd argument, so if the parent session is in a different directory, specifying only the tool-specific workdircannot guarantee the child's project root. In this case, target project files require an explicit workdirbut do not create child agents for project work. Start a new Codex session in the target project and then re-verify role discovery and execution. Do not assume that the current session will discover the new role immediately after the role file is created. If the parent session is in the target project but the new role is not exposed, read the definition, specify a fallback execution that instructs a built-in role, and report the role actually used.
• First check the currently exposed subagent tools and schemas, then native execution pre-check in the execution guide. Do not judge that execution is possible based only on tool exposure or static validation. Fan out after the actual ID of the first waiting child is returned, and reuse successful children for the first task.
• Parallelize work that can be completed independently. After confirming the first creation, expand to 2–3 useful child tasks and match the actual concurrency limit. If there is no tool or it fails without an ID due to a parent thread error, stop creating more and perform the same substantive work sequentially in the main session. Record the incomplete state and limitations of native execution separately.
• The main agent owns dependencies, file ownership, shared configuration, agent lifetime, integration, and completion determination. Give workers exclusive modification scopes and specify that they must not revert changes made by other workers.
• Actively communicate discoveries, questions, blocking reasons, and handoffs that affect colleagues, and respond promptly. Record important messages in _workspace/communications/. Native sending and local recording are separate operations, and the main agent confirms contract and ownership changes.
• The model and reasoning level inherit the parent settings. Do not pin a specific model unless there is an explicit requirement. Do not change global settings.
• Continue reversible work already permitted by the user's request. Do not add habitual plan approval or waiting for feedback after completion.

Project-local bootstrap

When building or updating via explicit invocation, inspect existing files in Phase 0, then perform the following in the target project before starting companion work. If already installed, update only the differences and preserve existing user content, model, and permission settings.

1. Check the actual source form. If scripts/install.py가 actually exists in the repository checkout, that installer can be used as --targetin the target project path. Do not assume that an environment with only the plugin installed has an installer at the repository root.
2. If there is no installer, place the files of the currently loaded harness skill bundle as a project-local copy in the target project .agents/skills/harness/, and create the necessary roles in the target project using the Phase 3 procedure .codex/agents/. Safely merge AGENTS.md's harness pointer and necessary project settings into the existing content. If there is a conflict with existing files, do not overwrite unconditionally; check the differences and preserve them. Do not record results in the plugin cache or personal settings.
3. Complete the role, skill, and orchestrator connections that will actually be reused in the target project, and verify the structure. Place the outputs of accompanying work inside the target project as well. Do not report that native roles have been loaded into the current session or that the work succeeded merely because harness files were created.

If writes to .agents/skills/ or .codex/agents/ in the target project are rejected in the active sandbox due to Operation not permitted , report the failed path and the original error, and leave harness construction incomplete. Do not write the necessary skill and role definitions to .harness/, the plugin cache, or the personal scope instead. Do not arbitrarily change the permission mode or the user's existing permission preferences.

Phase 0: Current State Audit

1. After confirming the target project root and execution location, check the AGENTS.md, .codex/config.toml, .codex/agents/, .agents/skills/under it and the existing execution records. If this is a migration, also read the existing harness and extract the behaviors to preserve.
2. Cross-check actual files, skill references, and AGENTS.md pointers to find missing, duplicate, or outdated connections. Preserve the user's existing edits.
3. For new construction or updates via explicit invocation, start with the project-local bootstrap above and proceed from Phase 1. For adding roles, use Phases 2, 3, 5, and 6; for modifying skills, use Phase 4, Phase 6, and the affected integration parts; for structural changes, perform only the affected scope starting from Phase 2. For checks and synchronization, follow Phase 7.
4. Briefly report the discovered inconsistencies and the scope of progress, then execute the permitted work. Confirm only the essential inputs that determine the outcome.

Phase 1: Domain Analysis

1. Organize the goals, inputs, final deliverables, completion criteria, and existing constraints. For a codebase, identify the stack, modules, test commands, and shared boundaries.
2. Distinguish recurring work from one-off work. If existing agents and skills are sufficient, reuse them.
3. Match the level of explanation to the user's context. Verify uncertain environment facts with actual files, tools, and official documentation.

Phase 2: Team Architecture Design

Read the agent design patternsand select an appropriate combination from the following six patterns.

Pattern	Execution Criteria
Pipeline	Execute the next task after the previous stage's approved deliverable
Fan-out/Fan-in	Perform independent tasks in parallel, then the main integrates them
Expert Pool	Selectively invoke only the needed specialist roles
Generate-Verify	Independently review and QA completed implementation sections and iterate limited fixes
Supervisor	The main dynamically allocates based on remaining work and available slots
Hierarchical Delegation	Divide domains hierarchically, but flatten execution around the main

For each task, define the project root, immutable inputs and fingerprints, confirmed decisions, required skill paths, dependencies, responsible roles, write-allowed paths, deliverables, verification methods, and retry limits. Give independent tasks small, self-contained packets, and have them re-read changed inputs even when reusing the same topic. Do not assume full conversation inheritance or specific fork options. By default, children do not delegate recursively and return additional split proposals to the main. Tasks that modify the same file are serialized or integrated by the main.

Phase 3: Create agent definitions

1. Compare with existing roles. If the responsibility is subsumed, reuse it, and create a custom agent only when a stable specialized responsibility is added. One-off exploration may be sufficient with the current runtime's built-in roles.
2. Built-in roles harness_explorer, harness_architect, harness_worker, harness_reviewer, harness_qa Invoke only the ones you need. The number of role files and the number of concurrent executions are different.
3. Of the target project, .codex/agents/<name>.toml에 name, description, developer_instructionsWrite the instructions to include responsibilities, input/output contracts, ownership, collaboration, and error/follow-up handling. Create this definition before creating a working agent.
4. Distinguish read-only exploration/review from execution QA. QA may need workspace-writedue to test caches and temporary artifacts. Product code changes are handled by workers and re-verified by QA. Do not have the QA role also modify the product.

For repeated generation, use the scripts/create_agent.pyof this skill copied into the target project. The command below is an example run from the target project root. Prepare the instruction input file inside the target project.

python3 .agents/skills/harness/scripts/create_agent.py \
  --target . --name domain_worker \
  --description '도메인 변환 규칙을 구현하는 워커' \
  --instructions-file .harness/domain-worker-instructions.md \
  --sandbox-mode workspace-write

Role templates and reuse criteria are in design patterns, and application examples are in team examples.

Phase 4: Create skills

1. skill authoring guide. Do not duplicate skills that overlap with existing functionality under a new name.
2. .agents/skills/<lowercase-hyphen-name>/SKILL.mdand put only name, descriptionin the frontmatter. In the description, write the specific task, starting and follow-up triggers, and boundaries with adjacent tasks.
3. Keep the core procedure in the body within 500 lines. Put optional detailed information to read in references/, actual repeated deterministic tasks in scripts/, and deliverable templates in assets/.
4. Link information so it is read in the order metadata → body → necessary references. For each link, write when it should be read.
5. In role instructions or delegation prompts, specify the required skill paths and the parts to read. Do not assume skills are auto-loaded for children. Do not assume a separate Skill invocation tool.

Phase 5: Integration and orchestration

orchestrator templateto configure the domain orchestrator. For actual initialization, result registration, reuse, and communication logging, follow the CLI and native tool boundaries of execution guide.

1. the main run.py initwith .harness/runs/<run-id>/plan.jsonand per task input.md. The v2 plan records the project root, input and contract fingerprints, and decision and skill paths. The modification target is ownership, and the unchanging contracts and references go in inputs, while prior artifacts are passed via dependencies.
2. Execute only tasks whose dependencies are satisfied. First check whether the parent session's actual cwdmatches the target project and whether the required project role definitions have been created. If it is a different cwd, do not bypass the absence of spawn_agent의 cwd via tool-specific workdir, and do not create a waiting child for project work either. Leave native execution as not executed until a new session is started in the target project. Even when running in the same cwd, specify each task tool's workdirand the packet's absolute project root as the target project, and check whether the new role's current session has been discovered. Check native execution using the actual creation result of the first waiting child, register the successful child, then increase parallel work and assign the latest packet. If the parent thread cannot be found, follow the sequential fallback procedure without per-role retries or fake ID registration. While children are executing, the main performs independent work such as shared contracts and integration preparation.
3. run.py resultand distinguish task status from native session status. The main updates the registry only after confirming an actual idle or stopped response, and does not reassign write ownership before the previous writer's stop or idle is confirmed. A local state change does not stop the agent or return the slot.
4. Proactively communicate important findings, specific questions and answers, contract proposals, input preparation, blocking reasons, meaningful milestones, and handoffs. Roles with write permission first record the outgoing content as communication.py logand then send it with the actual tool, linking the send result separately. Read-only roles request recording and delivery from the main. After peer discussion, the main finalizes contracts and ownership.
5. Identify the cause of failure, and for temporary task errors perform the default one additional attempt or a limited reassignment. Do not apply this per-role retry to parent thread errors in the native execution pre-check. Failure of a required task blocks harness completion. Record the impact and reason for omitting an optional task.
6. Perform QA as soon as module boundaries are ready, and do final verification after integration. Run tests and builds that share the same cache sequentially to avoid conflicts.
7. AGENTS.mdadd only the goal and orchestrator pointer inside the domain management marker. Distinguish the installer-managed codex-harness:start/end bootstrap block from the domain block so that domain connections are preserved even on reinstall. Preserve existing content and do not duplicate long execution rules or role lists.

<!-- codex-harness:domain:start -->
## 프로젝트 하네스
{도메인} 작업의 생성·수정·부분 재실행에는 `.agents/skills/{domain}-orchestrator/SKILL.md`를 읽는다.
하네스 자체의 구축·점검·동기화에는 `.agents/skills/harness/SKILL.md`를 읽는다.
<!-- codex-harness:domain:end -->

For follow-up requests, run.py resumecreate a new run. Re-execute the task if changed inputs, contracts, results, or sub-dependencies are invalidated. Reused agents also read the updated packet and do not overwrite past runs.

Phase 6: Verification and Testing

1. In the target project root, run python3 .agents/skills/harness/scripts/validate.py --project .. This command inspects the structure and does not prove actual agent execution success.
2. Check agent TOML, skill frontmatter, reference paths, pointers, ownership duplication, and dependency cycles. Before execution is complete, verify required results, deliverables, inspection evidence, and freshness with validate.py --project . --run <run-id> --complete.
3. QA guide, compare both producer and consumer. Classify test and review results as pass/fail/not run.
4. Skill testing guide, verify realistic normal, error, and partial re-execution cases. If the native execution pre-check succeeds, perform a small real execution of workers handling different files and independent verification. Smoke tests that verify native execution are not treated as passed via sequential fallback work.
5. After fixing issues, re-run the affected checks. QA fixes iterate up to a default maximum of 2 times, and required failures remain failures even after the limit. Do not report tests that were not run as passed.

Phase 7: Evolution, Operations, and Maintenance

1. Compare actual role and skill files against the orchestrator and pointers to create a drift list. Record the reason for changes and the targets in the execution log.
2. For result quality issues, fix the relevant skill; for role issues, the agent; for order and communication issues, the orchestrator; for missing triggers, the description.
3. Apply the requested changes in small units and synchronize references and pointers together. For role merging and deletion, check the impact on callers as well.
4. Structural changes are verified down to execution cases, and local document changes are verified focusing on structure and references. General improvements discovered from repeated failures are reflected within scope.
5. In the final report, write the changed files, the checks actually run and their results, and the remaining limitations. Do not interpret absence of feedback as approval or test passing.

Completion Conditions

• The required roles, skills, orchestrator, and AGENTS.md pointers match.
• There are contracts for tool use, input updates, independent ownership, session lifetime, dependencies, retries, and partial re-execution suited to the actual runtime.
• Important collaboration events and actual sends/responses are linked by correlation ID, and the scope of unrecorded and unsent items is specified.
• There are no unresolved failures in required tasks and checks, and unrun checks are specified.
• Existing project files and global settings were not changed unnecessarily.