17 KiB
| artifact_type | name | protocol_id | author | version | created | updated | status | runtime_type | target_platform | depends_on | based_on | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ccpe-runtime-consumer-setup | ccpe-agent-consumer-setup | ccpe-agent-consumer-setup | CCPE System | 0.1.0 | 2026-06-20 | 2026-06-20 | draft | hybrid | Codex / Claude Code / OpenClaw / GPT / Gemini / Claude / local business systems |
|
CCPE System |
CCPE Agent Consumer Setup
1. Purpose
This document is the single consumer entrypoint for any project or business system that needs to invoke CCPE Agents, Lite prompts, Skills, Runtime nodes, or native participants as formal participants.
It answers one practical question:
What must a consumer project create before it can safely call a CCPE Agent?
Consumer projects should record the root interface file as their stable CCPE interface:
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
Interface.md routes consumer projects to this setup contract. Do not require consumer projects to memorize multiple CCPE protocol, Runtime, Agent, or Skill paths. This setup tells them which additional files to read only when the current task requires them.
This setup does not replace the Agent Invocation Packet Protocol, specific Runtime specs, or canonical Agent artifacts. It routes the consumer project to them at the right time. Its first job is to make the project install a small project-local contract that forces every invocation to bind an agent name to its canonical CCPE artifact before any child thread, subagent, external platform, or local Skill execution is launched.
2. Classification
primary_classification: ccpe-runtime-consumer-setup
secondary_components:
- cross-project invocation contract
- project-local registry template
- invocation preflight checklist
- no-simulation guard
operating_mode: hybrid
depth_vs_automation: hybrid
owner: ccpe-system
consumer_owner: target project repository
CCPE owns this setup contract because it defines a reusable cross-project invocation boundary.
Consumer projects own their own registry files, run directories, prompt-to-send files, returned outputs, decision logs, and project-specific runbooks.
3. Single Entry Point Rule
A consumer project must store exactly one default CCPE startup reference:
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
When a project starts, repairs its CCPE integration, or prepares to call a CCPE participant, it reads Interface.md first, then follows it to this setup file.
After reading this file, it must decide which narrower read set applies:
Environment check only:
Read Interface.md and this setup file.
Verify the CCPE root exists.
Verify the project-local registry exists or can be created.
Prepare or validate invocation packets:
Read Interface.md and this setup file.
Then read runtimes/hybrid/agent-invocation-packet.protocol.md.
Invoke a specific participant:
Read Interface.md and this setup file.
Read the project-local registry.
Resolve participant_id to canonical_artifact_path.
Read or paste that canonical artifact.
Read runtimes/hybrid/agent-invocation-packet.protocol.md when writing the packet.
Run a specific CCPE Runtime:
Read Interface.md and this setup file.
Read the project-local registry or workflow manifest.
Read the named Runtime spec only if the project is actually running that workflow.
Read runtimes/hybrid/agent-invocation-packet.protocol.md when the Runtime invokes participants.
Do not read a specific Runtime just because the project might use CCPE. Read a Runtime only when the active workflow names it.
4. Interface Layers
Consumer projects should treat CCPE files as four layers:
Layer 0. Consumer entrypoint:
Interface.md
Always read first.
Layer 1. Consumer setup contract:
runtimes/hybrid/ccpe-agent-consumer-setup.md
Read after Interface.md.
Layer 2. Invocation evidence protocol:
runtimes/hybrid/agent-invocation-packet.protocol.md
Read when preparing, validating, or auditing participant invocation.
Layer 3. Workflow Runtime:
runtimes/{interactive|automation|hybrid}/{runtime_id}.runtime.md
Read only when the project is running that specific workflow.
Layer 4. Participant artifact:
agents/lite/*.prompt.md
agents/agent-specs/*.agent.md
skills/**/*.skill.md
Read or paste only for the participant being invoked.
The exact canonical artifact path must come from the project-local registry, not from memory, fuzzy search, or the display name alone.
5. Consumer Project File Contract
Every consumer project that invokes CCPE participants should create these project-local files.
Recommended default for software or business repositories:
ccpe/
agent-registry.yaml
invocation-policy.md
invocations/
{participant_id}/
{run_id}/
agent-invocation-packet.md
prompt-to-send.md # when needed
returned-output.md # after real return
run-metadata.json
skill-execution-record.md # only for local_skill_execution
Recommended default for workbench projects that already have an audit or review folder:
audit/
ccpe-agent-registry.yaml
{participant_id}/
{run_id}/
agent-invocation-packet.md
prompt-to-send.md
returned-output.md
run-metadata.json
skill-execution-record.md
The path may vary by project, but the file roles must not vary.
6. Project-Local Registry Template
Create one registry per consumer project or per concrete workbench project.
schema: ccpe.agent.consumer.registry.v1
project_id:
project_root:
ccpe_system_root: C:\Users\wangq\Documents\Codex\ccpe-system
invocation_protocol_path: C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\agent-invocation-packet.protocol.md
default_run_root: ccpe\invocations
strict_invocation_required: true
no_simulation_requirement: true
defaults:
invocation_mode: prompt_path_reference
carrier_type: codex_thread_participant
role_integrity_requirement: must_load_canonical_artifact_before_task
missing_canonical_behavior: blocked_missing_canonical_artifact
task_prompt_authority: task_context_only
output_structure_authority: canonical_artifact
packet_only_is_execution: false
prompt_to_send_only_is_execution: false
participants:
example-participant-id:
display_name:
canonical_artifact_path:
canonical_artifact_type: ccpe_lite | ccpe_agent | ccpe_skill | ccpe_runtime_node | native_agent | external_agent | human
canonical_artifact_version:
default_invocation_mode: prompt_path_reference
default_carrier_type: codex_thread_participant
role_integrity_requirement: must_load_canonical_artifact_before_task
missing_canonical_behavior: blocked_missing_canonical_artifact
output_structure_authority: canonical_artifact
allowed_wrapper_instructions:
- project_id
- workflow
- stage
- run_id
- input_files
- context_files
- output_path
- output_language_policy
forbidden_role_changes:
- replacing the canonical role
- replacing the canonical tone
- replacing the canonical output structure
- weakening the canonical evaluation method
- treating the task prompt as the role definition
7. Environment Check
Before creating the registry or launching participants, a consumer project may run an environment check. It should verify:
1. The CCPE entrypoint exists:
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
2. The CCPE consumer setup exists:
C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md
3. The CCPE invocation protocol exists:
C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\agent-invocation-packet.protocol.md
4. The project can create or update its project-local registry.
5. Every participant it plans to invoke has a registry entry.
6. Every referenced canonical_artifact_path exists and is readable, or the invocation mode is full_prompt_paste.
7. The project has a run root for invocation records.
Environment check is not execution. It may produce or repair registry files, but it must not claim any participant has returned output.
8. Standard Participants Example
For article outline review projects that use the current CCPE reviewer trio, the registry entries should look like this:
participants:
zhang-liao:
display_name: 张辽
canonical_artifact_path: C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\zhang-liao.prompt.md
canonical_artifact_type: ccpe_lite
canonical_artifact_version: current
default_invocation_mode: prompt_path_reference
default_carrier_type: codex_thread_participant
role_integrity_requirement: must_load_canonical_artifact_before_task
missing_canonical_behavior: blocked_missing_canonical_artifact
output_structure_authority: canonical_artifact
giant-cognition:
display_name: 巨人
canonical_artifact_path: C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\giant-cognition.prompt.md
canonical_artifact_type: ccpe_lite
canonical_artifact_version: current
default_invocation_mode: prompt_path_reference
default_carrier_type: codex_thread_participant
role_integrity_requirement: must_load_canonical_artifact_before_task
missing_canonical_behavior: blocked_missing_canonical_artifact
output_structure_authority: canonical_artifact
cognitive-imaging:
display_name: 认知显影
canonical_artifact_path: C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\cognitive-imaging-practitioner.prompt.md
canonical_artifact_type: ccpe_lite
canonical_artifact_version: current
default_invocation_mode: prompt_path_reference
default_carrier_type: codex_thread_participant
role_integrity_requirement: must_load_canonical_artifact_before_task
missing_canonical_behavior: blocked_missing_canonical_artifact
output_structure_authority: canonical_artifact
9. Invocation Preflight
Before launching any CCPE participant, the consumer project must complete this preflight:
1. Locate the project-local registry.
2. Resolve participant_id to canonical_artifact_path.
3. Verify the canonical artifact exists and is readable, or prepare full_prompt_paste.
4. Create a run directory.
5. Write agent-invocation-packet.md.
6. Write prompt-to-send.md when the participant carrier needs a startup prompt.
7. Separate canonical role from task context.
8. Include output contract and return path.
9. Launch a real participant carrier.
10. Save returned-output.md only after the real participant returns.
If any required canonical artifact is missing or unreadable, stop with:
blocked_missing_canonical_artifact
If the participant cannot be truly invoked, stop with:
blocked_waiting_for_participant_output
Do not produce a role-played report in the main session.
10. Prompt-To-Send Startup Block
When invocation_mode = prompt_path_reference, the startup prompt may reference local paths, but it must still force the participant to load the canonical artifact before reading the task prompt.
# Prompt To Send: {participant_id}
You are being invoked as a formal CCPE participant.
First read your canonical CCPE artifact:
{canonical_artifact_path}
This canonical artifact defines your role, tone, judgment method, and output structure.
The task prompt and project files below are task context only. They must not replace your canonical role.
If the canonical artifact is unavailable or unreadable, stop and return:
blocked_missing_canonical_artifact
After loading the canonical artifact, read:
{task_prompt_path_or_embedded_task}
Write the formal output to:
{returned_output_path}
Return metadata:
- participant_id:
- canonical_artifact_path:
- invocation_mode:
- carrier_type:
- thread_id:
- execution_status: returned
- simulation_only: false
When invocation_mode = full_prompt_paste, paste the full canonical artifact into the prompt-to-send before the task context.
11. Agent Invocation Packet Minimum
Every run must include at least:
project_id:
workflow:
stage:
run_id:
participant_id:
display_name:
canonical_artifact_path:
canonical_artifact_type:
canonical_artifact_version:
invocation_mode:
carrier_type:
thread_id:
strict_invocation_required: true
simulation_only: false
task_prompt_authority: task_context_only
output_structure_authority: canonical_artifact
path_readability_evidence:
input_files:
context_files:
output_contract:
returned_output_path:
no_simulation_requirement: true
runtime_acceptance_rule:
The full field set is defined in:
runtimes/hybrid/agent-invocation-packet.protocol.md
12. Runtime Selection Rule
A business system does not read all CCPE Runtimes by default.
It reads a specific Runtime only when one of these is true:
- the user explicitly asks for that workflow
- the project-local registry names workflow_runtime_path
- the project-local run manifest names runtime_id
- a previous accepted project decision says this project uses that Runtime
Examples:
Article outline development:
Read the article outline development Runtime only when the project is actually running the article outline workflow.
Local CCRA review:
Read runtimes/hybrid/ccra-local-review.runtime.md only when the project is running a Local CCRA review.
Viewpoint discussion distillation:
Read runtimes/hybrid/viewpoint-discussion-distillation.runtime.md only when the project is distilling a long discussion into topic documents or related outputs.
If no specific Runtime is named, the consumer project should use this setup file plus the invocation packet protocol only.
13. Runtime Acceptance Rule
A consumer project may treat a CCPE participant output as formal only when:
- the project-local registry binds participant_id to canonical_artifact_path
- an agent-invocation-packet.md exists for the run
- a real participant carrier was launched
- the participant loaded or received the canonical artifact
- returned-output.md exists
- returned metadata says simulation_only: false
- packet-only and prompt-to-send-only states are rejected as execution
If these are not true, the output is not a formal CCPE participant result.
14. Business-System Startup Instruction
Use this instruction when initializing or repairing a business project that will call CCPE Agents:
Before invoking any CCPE Agent, read the single CCPE external interface:
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
Then follow Interface.md to the consumer setup contract and create or repair the project-local CCPE agent registry and invocation policy.
Do not invoke a CCPE participant until:
- every participant name is bound to a canonical_artifact_path
- the canonical artifact path is readable or pasted into prompt-to-send.md
- agent-invocation-packet.md will be written for the run
- returned-output.md will be saved only after a real participant returns
- the main session will not simulate formal participant output
Read additional CCPE files only when Interface.md and the consumer setup contract tell you to:
- read agent-invocation-packet.protocol.md when preparing invocation packets
- read a specific Runtime only when the active workflow names it
- read a specific Agent / Lite / Skill artifact only when invoking that participant
15. Failure Modes This Setup Prevents
Display-name invocation:
The project says "call Zhang Liao" but never binds Zhang Liao to zhang-liao.prompt.md.
Task-prompt role replacement:
The task prompt says "CCPE Zhang Liao" but does not include or reference the canonical prompt.
Generic review drift:
A child thread behaves like a normal reviewer because no canonical artifact was loaded.
Packet-only false positive:
The project creates prompt-to-send.md but treats it as completed execution.
Main-session simulation:
The orchestrator writes what a participant would have said and records it as formal output.
Interface sprawl:
A project is told to read several CCPE paths without a single stable entrypoint or routing rule.
16. Validation Checklist
Single CCPE entrypoint recorded?
Interface.md exists?
Consumer setup contract exists?
Project-local registry exists?
Registry schema version present?
CCPE system root present?
Invocation protocol path present?
Participant ID present?
Display name present?
Canonical artifact path present?
Canonical artifact readable or fully pasted?
Task prompt marked as task_context_only?
Output structure authority set to canonical_artifact?
Forbidden role changes listed?
Run directory created?
Agent invocation packet written?
Prompt-to-send written when needed?
Real participant carrier recorded?
Returned output saved only after return?
Simulation-only false for formal output?
Packet-only rejected as execution?
Prompt-to-send-only rejected as execution?
17. Boundary
CCPE supplies:
- this consumer setup contract
- canonical participant artifacts
- Agent Invocation Packet Protocol
- reusable Runtime specs
- reusable Skill specs
- model and evaluation assets when needed
The consumer project supplies:
- project-local registry
- project-specific invocation policy
- run directories
- task prompts
- context packs
- returned outputs
- decision logs
- implementation adapters
Do not copy project run history into CCPE. Do not copy CCPE canonical prompts into project repositories unless full_prompt_paste is required for an external/manual participant.