Skip to content

chore(harness): reconcile decoded Hybrid 2.5 docs after Codex reactivation #618

@thxforall

Description

@thxforall

Context

Sources:

  • AGENTS.md describes Codex under Hybrid 2.5 and says repo-local AGENTS.md is the canonical cross-tool entry.
  • .harness/routing.md now documents Direct Codex Session and Hybrid Worker Lane.
  • docs/wiki/wiki/harness/codex-cli.md says Codex is active again and describes root .tasks / .handoff Hybrid worker mode.
  • docs/agent/ai-playbook-summary.md still says Codex is deprecated as of 2026-04-23, which now conflicts with the active routing docs.
  • docs/agent/skills.md lists /grill-docs, while the local requested flow used /grill-me-docs; the actual skill body available here is grill-with-docs.

Problem

The repo now has enough Hybrid 2.5 / Codex Fast+Strict routing to use it again, but the documentation set still contains stale or conflicting guidance. Future agents may choose the wrong operating mode, treat Codex as deprecated, or miss the single-file Fast invariant.

Scope

  • Reconcile Codex status across docs/agent/ai-playbook-summary.md, .harness/routing.md, docs/wiki/wiki/harness/codex-cli.md, and pointer docs.
  • Preserve the distinction between:
    • Direct Codex Session: human-supervised, scoped autonomous work.
    • Hybrid Worker Lane: .tasks/TASK-*.md driven, codex-fast execute, codex-strict review, Claude/human final accept.
  • Make the root .tasks / .handoff location explicit; call package-local task artifacts legacy if still relevant.
  • Make the Fast invariant explicit: scope: single-file, exactly one path in files:, return NEEDS_SPLIT if a second file is required.
  • Clarify skill naming/aliases for /grill-docs vs /grill-me-docs vs grill-with-docs, or document the supported command name only.

Grill-docs question

Question: should Codex be documented as a first-class tool again, or only as a worker behind Claude-owned task cards?

Recommended answer: document both modes, but keep acceptance boundaries strict. Direct Codex may implement and verify scoped work; Hybrid Codex remains a one-file worker/reviewer pair; only Claude or a human accepts/rejects.

Acceptance criteria

  • No agent-facing doc claims Codex is deprecated without also explaining the current active replacement/routing.
  • The canonical routing chain is clear: AGENTS.md -> .harness/routing.md + docs/wiki/wiki/harness/codex-cli.md.
  • Direct mode vs Hybrid Worker mode are not conflated.
  • Single-file Fast behavior and NEEDS_SPLIT are visible in the docs future agents read first.
  • Skill naming around grill-with-docs is either normalized or clearly mapped.

Out of scope

  • Editing global harness scripts under /Users/kiyeol/dotfiles/harness.
  • Changing Codex profiles outside this repo.
  • Dispatching real worker tasks.
  • Changing product docs in the same PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationtech-debt기술 부채

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions