Protocol

Protocol

$protocol is the primary Codex Copilot entrypoint for new work.

Use it at the start of a task to decide how the work should proceed.

Purpose

It should behave like the Claude Copilot /protocol command in intent:

• classify the request
• choose the correct specialist workflow
• require the right kind of thinking before implementation
• route the work through the correct agents

In Codex, that means:

• invoke specialist skills in the main session by default
• use spawn_agent only when the user explicitly asks for subagents or parallel execution
• use tc as the durable record for substantial work

Repository Decision Instruments

Before routing substantial work, check whether the repository defines its own decision instruments:

• If a root SOUL.md exists, read it before substantial product-facing work. Use it to decide whether the product direction should be built, reshaped, or rejected before specialist routing continues.
• If docs/01-architecture/12-architecture-guiding-principles.md exists, read it before durable technical, architecture, migration, data, security, performance, AI pipeline, or productized implementation work. Use it as the technical decision lens.

Keep these instruments separate:

• SOUL.md answers whether the product direction fits the product's purpose, taste, anti-patterns, and quality bar.
• architecture principles answer how accepted product direction should be built safely, scalably, efficiently, and securely.

Request Classification

Required behavior

1. check repository decision instruments when they apply
2. classify the task
3. state the workflow
4. ensure tc context exists for substantial work
5. load known references and memory when cc is configured
6. for third-party API work, require Live Docs before planning or implementation
7. record QA-required implementation tasks with metadata.requiresQa=true
8. use docs/40-initiatives/NN-slug/ for formal multi-phase initiative knowledge while keeping live execution state in tc
9. perform the next appropriate specialist step
10. do not jump straight to implementation when earlier specialist work is warranted
11. do not use spawn_agent unless the user explicitly asked for delegation or parallel work

For experience work that does not materially change screens, components, or interface states, $uid may be skipped only when the checkpoint states why.

Fixed Delivery Boundary

Before implementation, state the deliverable, required acceptance criteria, affected consumers, verification lane/cap and exclusions in tc. Freeze this batch scope; use the engineering/QA Proportional Verification fixed finish line. After current source-bound QA approval satisfies every required criterion, close the task, report completion and separately pending work, then stop. Unrelated findings do not authorize another improvement cycle. Missing required evidence or an exhausted cap remains incomplete; never weaken acceptance to declare completion.

User-Facing Output

• Lead with what is now true—the answer, decision, result, or blocker—not what was investigated.
• Include only what the user needs to trust the result, decide, or act. Preserve required findings, uncertainty, citations, QA evidence, safety warnings, blockers, and next actions.
• Default to at most 6 sentences or 5 bullets; exceed that only when requested or required by risk, complexity, or completeness.
• Keep progress updates to one sentence: material result plus next active step. Lead completion reports with the outcome, then give only changed scope, verification, and any remaining caveat or action.
• Omit preambles, generic closers, self-narration, repeated findings, evidence inventories, command traces, and chronology unless requested or necessary.
• Store detailed analysis and evidence in tc work products. Content outranks form; length never removes a required fact, artifact, verdict, identifier, or blocker.

Unknowns

Every design-stage lens ($sd, $uxd, $uids, $ind, $ta) ends with an unknowns: line. unknowns: none is permitted and is a claim you own; omitting the line is not.

An unknown that would change the work escalates rather than being noted:

QUESTION: [the one thing that changes the answer]
OPTIONS: [A — consequence] | [B — consequence]
CONTEXT: [why this cannot be resolved from what you were given]

One question, not a checklist. Each option carries its consequence so the user can decide in one pass. CONTEXT: states what you already ruled out — that is what makes it a question rather than a request to be told what to do.

Resolving a genuine ambiguity silently is a defect, not efficiency. Measured on an identical brief carrying a real contradiction ("Level 4 finish throughout" against "Garage included"): the arm with no framework asked, got the answer, and priced 25 fewer labour hours. The arm running the full design chain asked nothing and priced a guess. Inferring an answer where the brief is undecided converts the user's decision into your hidden assumption and buries it in a deliverable, where it resurfaces as rework. Guessing is acceptable only when the guess is stated as one.

This applies with more force here than in a delegating framework, not less: running the lenses inline means no handoff document exists where an unstated assumption might be caught by the next specialist reading it.

Checkpoints

For design-heavy flows, stop after major design stages unless the user clearly asked for uninterrupted execution.

Checkpoint stages:

• after sd
• after uxd
• after uids
• after ta when the plan materially shapes implementation

Each checkpoint follows references/checkpoints.md: outcome first, only real decision-specific options, and no evidence inventory. Include soul, architecture, QA, or next-step context only when it changes the decision.

Main-session pattern

Use these native skills directly:

• $sd
• $uxd
• $uids
• $uid
• $ta
• $me
• $qa
• $ind
• $sec
• $doc
• $do

Optional pack specialists (kc, cco, cw, cs, cpa) are activated per project when the user needs knowledge, creative, copywriting, customer success, or financial advisory work.

Delegated pattern

If the user explicitly asks for delegation or parallel work, use $launcher to map the needed specialists onto native Codex spawned-agent roles.

Task Copilot

For substantial work:

• create or use a PRD/task in tc
• store long outputs as work products
• keep the main response concise

References

Read references/generated-workflows.md for the catalog-derived specialist sequences, references/flows.md for routing details, and references/checkpoints.md for checkpoint behavior.

Design Quality Routing

For material product-facing work, carry one named surface contract through service/interaction design, visual design, implementation and QA. Use cc design guide for focused actions and cc design context for explicit source authority; retain the existing specialist chain and required walkthroughs. Record initial critique before detector evidence, inspect the rendered result, and leave approval to task-bound QA. Static findings and screenshot comparisons inform judgment; neither replaces behavioral verification.

For optional context selection, apply the full contract in ../specialist-agents/references/shared-behaviors.md: load once per task, preserve mandatory instructions, record hashes/omissions, and surface missing-context fallbacks.

Task Acceptance and Tested Identity

Current QA-required work uses tc 2 evidence binding. Before implementation, register a JSON acceptance contract with tc task contract <id> --file <path>: schemaVersion: 2, criteria: [{id, expected}], and explicit project-relative sources files/directories covering implementation, dependencies and relevant configuration. Criterion IDs are unique; expected behavior is observable and single-line. Keep generated review outputs outside source scopes.

Before running verification, capture tc task evidence-identity <id> and retain its exact IDENTITY: line in the task work product. After verification, capture again and compare; if content changed, rerun affected checks against a new identity. Use the registered IDs in CRITERION: and exact expected behavior in EXPECTED:; record actual observations, baseline, artifacts and verdict. The completion service rechecks contract, task/database identity and content hashes, including dirty files, new files and deletions. It also enforces unfinished task dependencies. Do not downgrade requiresQa or replace source evidence with prose.

A v1 packet for pending work must be migrated with a registered contract and fresh verification. Historical completed records remain readable and explicitly historical; they are not current strict QA evidence. cc design review/report checks the named database's acceptance contract and source coverage; detector or report readiness still never grants task approval. CLI/API and native adapters share the same tc authority. Missing current capabilities require a verified tc installation; legacy artifact inspection is not a current completion proof.