Codex Collab

Keep Codex as the controller. Use Claude for independent review and Grok/DeepSeek Harness for bounded implementation tasks. Choose agents by task fit, availability, modality, and dependencies; do not require every agent for every request.

Locate the installation

This skill ships with a Python CLI. Resolve this SKILL.md through any symlink: its containing directory is <repo>/skill, and the installation root is <repo>. Run python3 <repo>/scripts/collab.py. If installed as a copied standalone file without the sibling CLI, explain that the full repository is required; do not guess a machine-specific path.

On first use, read <repo>/README.md and <repo>/docs/INSTALL.md, then run doctor and list. Doctor checks installation, not account availability. Do not install dependencies, change accounts, or launch paid workers beyond the user's task authorization.

Run a bounded task

1. Read the user's project instructions. Define the goal, owner, allowed files, input commit, and concrete acceptance check.
2. Run worktree <absolute-repository> <unique-name>. Source inputs must be committed; do not silently omit dirty changes. Use the returned directory and full SHA.
3. Write a JSON contract with id, role, cwd, objective, allowed_paths, acceptance, input_revision, and timeout_seconds. Roles: claude-reviewer, grok-worker, dsh-worker. Use specific relative allowed paths, never the repository root. Unknown contract fields are rejected.
4. Run dispatch <contract.json>, then inspect status <id>. Parallel tasks need isolated worktrees. A submitted task is not automatically resubmitted; recovery or retries must preserve the original record.
5. Read actual outputs and run acceptance checks. delivered is only a transport/scope milestone. Independently review meaningful changes, then call accept <id> <nonempty-evidence-file> only after verification.

Use Chinese or English according to the user. Generate contracts yourself; do not require users to write orchestration JSON.

Models, review, and child agents

• DSH defaults to tier=flash, formally mapped to deepseek-flash by the pinned project overlay. pro maps to deepseek-v4-pro. Supported effort values are off, high, max; choose proportionately. Verify actual availability instead of assuming a model name is current.
• DSH defaults to the standard preset with native subagent tools. Explicit minimal does not have the same tool set. Native describe_image uses DeepSeek vision through a bridge; this is not direct image input in the coding conversation.
• Claude supports contract model and thinking. Grok uses its isolated native model/effort settings; the adapter rejects unsupported shortcuts. grok models can fail to refresh while showing cached entries—report that distinction.
• Each parent may use native child agents within the user's authorization. Inherit file boundaries and memory, avoid overlapping writes, choose supported models/effort, wait for child results, and report unknown telemetry honestly. Preserve native recursion/concurrency protections.
• If Claude hits quota/authentication trouble, refresh the same account's persisted settings by rebuilding only the owned, already-finished CCB session; make at most one small health check. If still unavailable and the task permits reviewer substitution, use an independent GPT subagent. Record requested/actual reviewer, original task, failure reason, and model. Never label a controller self-review or GPT review as Claude's work.

Shared memory and handoffs

Read <repo>/docs/ARCHITECTURE.md for the state machine and <repo>/docs/CONTEXT_MEMORY.md for commands.

• Dispatch freezes the input commit's docs/project-memory/TEAM.md and PROJECT.md when present. memory_paths appends other reviewed files; it cannot remove default rules. Receipts and prompts carry the same SHA-256 snapshot. Uncommitted edits do not become shared truth.
• Workers propose memory in allowed files. The controller verifies and accepts the task, then uses memory-promote to check the delivered digest and freshness. Review and commit the promoted file before using it in future snapshots. Never store credentials, full private conversations, or hidden reasoning in shared memory.
• Register manageable sessions with context register; bind contracts using context_session_id. Use actual current/estimated pressure, not cumulative billing tokens. Unknown or stale readings stay unknown. A bounded manual override needs an explicit reason and a timeout of at most 600 seconds.
• Start handoff at ceil(0.8 * min(256000, known-window)). Parent and child sessions both inherit this rule. DSH pressure polling can request cancellation; arbitrary desktop and native child sessions are not universally auto-monitored.
• Create a hashed handoff-package, register a standby successor, and prepare. Verify native predecessor/child termination before stop. Give the successor the immutable package plus the later stop certificate/evidence. Only after it actually reads and verifies them call ack. abort may undo a preparation before stop; it cannot revive a stopped owner.
• Do not claim control-plane registration is OS-enforced stopping, or that a local ack proves a model read the package. A fresh DSH job is a fresh native session; CCB can reuse panes, so new-context work should use a new isolated unit and verify identity.

Recover without inventing success

cancel is a request: confirm the native terminal state. unknown keeps the worktree occupied. If a runner disappeared, use reconcile, inspect the native job/trace, then resolve <id> delivered|failed|cancelled <evidence> --note <reason>. A late native completion still needs scope and output verification before acceptance.

Operate only this installation's worktrees, CCB namespaces, and DSH hub. Do not stop unrelated processes, modify global credentials, merge, push, publish, or message others unless the user's task authorizes it.

Shared project task skills

Contracts accept skills: ["lark-doc", "langfuse"]. Omission uses explicit domain keywords; skills: [] disables selection. skills list reports the registered installed catalog; skills check <names> freezes and validates the selected dependency closure. With no names, skills check checks entries individually. Missing sources fail explicitly; third-party skill content is not bundled with this repository.

At dispatch, freeze selected UTF-8 text resources and SHA-256 hashes; materialize them under the target workspace's .collab-skills/<task-id>/. Keep that directory outside allowed write paths. Read the bundled collab-tool-guide before selected tool skills and validate dependencies with the target Python interpreter. Credentials, CLI installations and MCP access are not shared automatically.

Parents pass the same package entrypoints, root and expected hash to native children. Inheritance is instruction-only, not universally intercepted or proven. This pool selects registered installed skills per project task; it does not discover arbitrary project-local skill folders. Read <repo>/docs/SHARED_SKILLS.md and <repo>/docs/TOOL_SKILLS.md for limits and checks. Default list/status omit snapshot bodies; --full exposes complete records.

Bounded recursive self-improvement

When the user authorizes improving this adapter, use it to dispatch isolated implementation, independent review, and successor validation. Fix each round's input SHA, owner, allowed paths, acceptance checks and stopping conditions. A review finding may start a new bounded repair task with a new ID; re-run verification against the resulting version. Stop when the authorized objective is met or a blocking condition requires user input.

Native children may assist within harness recursion/concurrency limits. Do not delegate this control plane recursively to workers, expand authorization, or run an unattended endless improvement loop. The controller reads actual changes, runs checks and records evidence before adopting an improved version. Preserve the previous revision and use a reviewed revert if validation fails. See <repo>/docs/SELF_IMPROVEMENT.md.