codex-harness

Skill: Codex Harness Orchestrator

Required before starting: Match the references/usage-examples.md scenarios against the user's utterance.

Core Principles

1. 7 Architecture Patterns: Pipeline · Fan-out/Fan-in · Expert Pool · Producer-Reviewer · Supervisor · Hierarchical · Handoff
2. Agent Definition: TOML format — .codex/agents/{name}.toml
3. Skill Format: SKILL.md — .codex/skills/{name}/SKILL.md
4. Project Context: AGENTS.md — Path hierarchy: global ~/.codex/AGENTS.md → repo AGENTS.md → subdirectory (more specific file takes precedence). Short and precise files are better than long and vague ones.
5. State Persistence: _workspace/ file-based brokering
6. Permission Control: TOML sandbox_mode field — read-only | workspace-write | danger-full-access
7. Subagent Constraint: Only the orchestrator may spawn subagents. max_depth=1 (default) enforced.
8. File I/O: Prefer apply_patch (surgical edits). New files via shell write.
9. Zero-Tolerance Failure Protocol: Arbitrary skipping is strictly prohibited. Maximum 2 retries (3 attempts total) → Blocked.

Plan Mode

Always run the Plan Mode procedure before building a multi-stage harness.

• Activation: Collect context via request_user_input → clarifying questions → build a solid plan, then implement
• Required cases: New builds, architecture changes, Stage additions
• May be skipped: Simple single-item tasks with a clearly scoped change (e.g., minor skill checklist edits)

Plan Mode Procedure (request_user_input-based)

PROCEDURE plan_mode(user_request):
    // 1. Context collection
    questions ← []
    IF domain/goal is unclear:
        questions.append("Please describe the goal and domain of the harness you want to build in detail.")
    IF pattern cannot be determined:
        questions.append("Do you have a preference for the agent team structure (Pipeline, Fan-out, Supervisor, etc.)?")
    IF agent count/roles are unclear:
        questions.append("Please list the agent roles you need.")

    IF questions is not empty:
        CALL request_user_input(questions)   // Bundle all questions into one call
        RETURN                               // Re-enter after receiving responses

    // 2. Plan presentation and user approval
    plan_summary ← Summary of domain, pattern, agent list, Stage/Step structure
    CALL request_user_input(
        "We will build the harness with the following plan. Shall we proceed?\n\n{plan_summary}"
    )
    RETURN                                   // Enter Phase 1 after approval