Codex Thread Coordinator Skill

Codex Thread Coordinator is a Codex skill for long-running engineering work: multi-step fixes, multi-agent audits, visible thread handoffs, context-compaction recovery, and durable task ledgers.

This repository ships one skill: codex-thread-coordinator. The examples/, reports/, and scripts/ folders are supporting materials, not extra skills.

CC Switch is optional. Most users can install this directly as a Codex private skill under ~/.codex/skills/codex-thread-coordinator. CC Switch users can install the same skill under ~/.cc-switch/skills/codex-thread-coordinator.

Its main rule is simple:

No durable ledger, no long-running continuation.

The skill helps Codex stop relying on chat memory alone. It forces long tasks to record a coordination contract, checkpoint progress, assign ownership, reconcile worker state, and avoid claiming completion before fresh verification exists.

What It Solves

Without this skill, long Codex tasks often fail in predictable ways:

• The model forgets context after compaction.
• The user has to repeat the same instructions.
• Multiple agents inspect or edit the same files.
• A worker says DONE, and the coordinator treats that as final completion.
• Progress exists only in chat, so a new thread starts over.
• The final answer says "fixed" before tests or evidence support it.

This skill turns those failure modes into explicit gates.

Key Features

• Mandatory long-run preflight: Long tasks start by defining or recovering the coordination contract and ledger.
• Durable ledger requirement: Long-running work must use a ledger such as docs/agent-tasks/current.md.
• Checkpoint 0: Every long task starts with objective, done definition, scope, verification ladder, current phase, next action, and claims that are not allowed yet.
• Path-specific ownership: Workers need explicit read and write ownership. Unknown or broad ownership counts as overlap.
• Safe delegation: Worker prompts must be self-contained and include ledger path, checkpoint requirement, evidence requirement, and stop conditions.
• Compaction recovery: After resume or compaction, Codex reads the ledger, task contract, newest checkpoint, and newest user instruction before continuing.
• Completion claim control: The coordinator cannot claim "complete", "fixed", "stable", or "tests passed" without ledger evidence, fresh verification, and final review.

When To Use

Use it for:

• Long-running product or repo work
• Multi-step bug fixes
• /goal style objectives
• Multi-agent audits
• Parallel review or verification
• Thread handoff
• Context-compaction recovery
• Work where repeated debugging or lost context is expensive

Do not use it for:

• One-line questions
• Small edits
• Simple command output
• Tasks that do not need durable state

Before And After

Area	Without This Skill	With This Skill
Progress tracking	Chat memory	Durable ledger and checkpoints
Context compaction	Often loses the plan	Reads ledger and newest checkpoint
Multi-agent work	Easy to duplicate or conflict	Path-specific ownership
Worker results	DONE may be over-trusted	Coordinator verifies and integrates
User reminders	Frequent manual reminders	Preflight runs automatically when triggered
Final claims	May overstate completion	Claims require evidence and final review
Handoff	Informal summary	Contract, ledger, checkpoint, and risks

Repository Layout

.
├── README.md
├── README.zh-TW.md
├── README.zh-CN.md
├── skills/
│   └── codex-thread-coordinator/
│       ├── SKILL.md
│       ├── agents/
│       │   ├── interface.yaml
│       │   └── openai.yaml
│       └── references/
│           └── ledger-template.md
├── examples/
│   ├── compaction-recovery.md
│   ├── long-running-task-ledger.md
│   └── worker-prompt.md
├── reports/
│   └── output_quality_scorecard.md
└── scripts/
    ├── install.ps1
    └── install.sh

Install

Windows PowerShell

git clone https://github.com/YLongger/codex-thread-coordinator-skill.git
cd codex-thread-coordinator-skill
.\scripts\install.ps1

Default target is Codex private skills and does not require CC Switch:

%USERPROFILE%\.codex\skills\codex-thread-coordinator

To install into CC Switch instead, use:

.\scripts\install.ps1 -Target CcSwitch

macOS or Linux

git clone https://github.com/YLongger/codex-thread-coordinator-skill.git
cd codex-thread-coordinator-skill
chmod +x scripts/install.sh
./scripts/install.sh

Default target is Codex private skills and does not require CC Switch:

~/.codex/skills/codex-thread-coordinator

To install into CC Switch instead:

./scripts/install.sh --target cc-switch

Update

When this repository is updated:

cd codex-thread-coordinator-skill
git pull
./scripts/install.sh

On Windows:

cd codex-thread-coordinator-skill
git pull
.\scripts\install.ps1

Quick Usage

After installation, ask Codex to use it for long-running work:

Use codex-thread-coordinator for this long-running task. Create or recover the durable ledger first, then proceed one checkpoint at a time.

For a project, keep the ledger at:

docs/agent-tasks/current.md

See examples/long-running-task-ledger.md for a starting template.

Trust Boundary

This package contains only the reusable skill, examples, documentation, and installer scripts. It does not include:

• Local cc-switch.db
• Backups
• Project logs
• Captures
• Runtime dumps
• Tokens or credentials
• Private project instructions

License

MIT License. See LICENSE.