wantsong
/
ccpe-system
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ccpe-system/ccpe-protocol/ccpe-migration-policy.md

1111 lines
24 KiB
Markdown
Raw Blame History

# CCPE Migration Policy
## 1. Purpose
This document defines how to migrate older CCPE 2.0 artifacts into the new CCPE System.
The migration policy applies to:
```text id="tkiqa5"
Old CCPE 2.0 prompts
Custom GPT / Gem instructions
Single-agent expert prompts
Self-contained model-backed agents
Multi-agent committees
Old Skill-like procedures
Workflow descriptions
Prompt templates
```
The goal is not to rewrite everything into a heavier format.
The goal is to identify what each artifact really contains and move each component into its most useful form.
Migration must begin with scenario probing. The same source artifact may become only a Lite prompt, or may become Lite + Model Card + Skill + Agent + Runtime, depending on how the user actually uses it.
## 2. Migration Principle
The central migration principle is:
> Preserve cognitive power while improving structure.
For mature single-agent expert prompts, preserve the working prompt kernel before extracting components.
Migration should improve:
```text id="hlv3nb"
Clarity
Reusability
Maintainability
Portability
Safety
Evaluation
Model fidelity
```
Migration should not destroy:
```text id="bf1z9d"
Original metaphor
Conceptual force
Distinctive terminology
User's intellectual intent
Useful personality
Domain-specific sharpness
```
Do not turn powerful cognitive tools into bland generic templates.
## 2.1 Scenario Probe
Before migrating an old CCPE 2.0 artifact, determine:
```text
current_usage:
- Web / GPT / Gemini / Claude single-agent prompt?
- Codex local workspace artifact?
- committee member manually invoked by the user?
- automated workflow node?
planned_usage:
- copy-paste prompt?
- Codex-callable Skill?
- durable Agent Spec?
- multi-agent Runtime?
orchestration:
- human manually passes context?
- a lead agent routes work?
- system automation routes and synthesizes outputs?
depth_orientation:
- deep expert thinking?
- workflow execution?
- hybrid?
```
If scenario information is unavailable, produce a scenario assumption and mark it as a migration risk.
## 2.2 Mature Agent Minimal Expansion Rule
For a proven old agent that is mainly used as a single expert in chat:
```text
default_migration: CCPE-Lite
recommended_addition: Model Card if the embedded model is stable and valuable
defer: Agent Spec, Skill, Runtime
```
Create additional layers only when the scenario requires them:
```text
Skill:
Needed when Codex should invoke the method automatically, or the method is reused across agents.
Agent Spec:
Needed when the role participates in a durable workflow or committee and needs handoff, authority, and evaluation rules.
Runtime:
Needed when multiple roles, stages, state, synthesis, archival, tools, or automation must be coordinated.
```
Do not treat four-layer expansion as a default migration outcome.
## 2.3 Minimal-Kernel First Rule
For mature CCPE 2.0 single-agent expert prompts, the default first migration should be:
```text
original-ccpe-2
→ original-kernel-minimal-lite
→ small regression test
→ temporary production Lite if kernel force is preserved
```
This rule exists because a full Lite rewrite can improve structure while losing the old prompt's working kernel.
`original-kernel-minimal-lite` should preserve:
```text
original objective
original method pressure
original report behavior
distinctive terminology
core metaphor when structurally meaningful
domain worldview
productive sharpness
```
### 2.3.1 Original Kernel Means Verbatim Kernel
In Fast Migration Lane, `Original Kernel` means the original CCPE 2.0 prompt kernel is preserved verbatim.
Allowed outside the `Original Kernel` block:
```text
front matter
classification note
minimal Lite wrapper
platform boundary
source / retrieval boundary
hidden chain-of-thought disclosure repair
output validation discipline
minimal conflict override notes
```
Forbidden inside the `Original Kernel` block:
```text
translation
paraphrase
deduplication
section reordering
terminology replacement
workflow rewrite
style smoothing
template normalization
```
If any forbidden operation is performed on the original prompt body, the artifact is no longer `original-kernel-minimal-lite`. It is a `refined-lite candidate` and must enter Refinement Lane before production promotion.
It should add only minimal migration repairs:
```text
platform boundary
hidden reasoning disclosure repair
source / retrieval boundary if needed
output validation discipline
version or status metadata
```
Do not use a full refined Lite rewrite as the default first move for every mature agent.
### 2.3.2 Pre-Migration Source Judgment Gate
Before generating `original-kernel-minimal-lite`, run a source judgment pass for the original CCPE 2.0 prompt.
The purpose is to decide whether the current source version is good enough to preserve verbatim, or whether the source prompt itself should be repaired first.
This gate must produce an `Original Source Judgment Report` before migration when the prompt shows visible source-level risks.
Judgment categories:
```text
Source defect:
A real flaw in the original prompt body that may degrade output quality.
Platform incompatibility:
A statement that is acceptable in the old prompt but unsafe or false in the current target platform.
Kernel feature:
A sharp, strange, severe, or distinctive behavior that looks risky but is part of the prompt's useful force.
Ambiguous finding:
A possible defect that requires review by the user or by the original CCPE agent.
```
Typical findings:
```text
omniscience or retrieval claims
hidden chain-of-thought disclosure risk
duplicated sections
contradictory authority rules
outdated tool claims
unsafe factual confidence
unclear output contract
valuable but severe critique style
```
The report must recommend one of these source decisions:
```text
Use source as-is:
Generate original-kernel-minimal-lite with the current source body verbatim.
Patch only in wrapper:
Keep source verbatim, and resolve platform or disclosure conflicts through the wrapper.
Repair source first:
Create a revised source version, such as v1.2, then use that chosen source version verbatim.
Enter Refinement Lane:
Do not claim original-kernel-minimal-lite; produce a refined-lite candidate instead.
```
Human decision gate:
```text
The user must choose the source decision before Fast Migration Lane generates the final minimal-kernel artifact.
The report may be sent to the original CCPE agent on its native platform for second judgment.
Codex must not silently repair, translate, deduplicate, reorder, or smooth the original source body before this decision.
```
### 2.3.3 Fast Migration Lane
Use Fast Migration Lane when:
```text
the old agent already works
the target is short-term migration or batch upgrade
the user needs low evaluation burden
the artifact is mainly a portable single-agent expert prompt
```
Fast Migration Lane workflow:
```text
1. Audit the original artifact.
2. Classify it, usually as CCPE-Lite for single-agent expert use.
3. Run Source Judgment Gate when source-level risks are visible.
4. Let the user choose the source decision.
5. Preserve the chosen CCPE 2.0 source version verbatim under `## Original Kernel`.
6. Generate original-kernel-minimal-lite.
7. Run a small regression comparison against the original.
8. Promote only if production safety is improved and kernel force is not worse.
9. Keep original and any full rewrite candidates as regression references.
```
If the minimal-kernel version performs acceptably, stop the migration for now.
### 2.3.4 Refinement Lane
Use Refinement Lane only when:
```text
the agent is high-value or high-frequency
the user explicitly wants deeper optimization
the minimal-kernel version has a clear weakness
the current Lite must improve production stability
there is time and budget for A/B testing
```
Refinement Lane workflow:
```text
1. Start from original-kernel-minimal-lite.
2. Identify a concrete regression or improvement target.
3. Add targeted discipline rules.
4. Avoid wholesale rewrite unless the kernel itself is broken.
5. Compare original, minimal-kernel, and refined-lite candidates.
6. Promote refined Lite only if it improves production stability without losing kernel force.
```
If refined Lite loses kernel force, pause and keep the minimal-kernel version.
### 2.3.5 A/B Budget Rule
Do not spend multi-round A/B testing on every migrated agent.
Default test budget:
```text
Fast Migration Lane:
one small regression batch
Refinement Lane:
multiple A/B rounds only for high-value agents
```
Manual result inspection is a real migration cost and should be reserved for artifacts where the improvement is worth it.
## 3. Old CCPE 2.0 Layer Mapping
Old CCPE 2.0 used four major layers:
```text id="rp6kkn"
Core Layer
Execution Layer
Constraint Layer
Operation Layer
```
The new CCPE System expands these into more precise structures.
For CCPE-Lite migration, these four layers remain the preferred prompt-construction kernel:
```text
Core Layer
Execution Layer
Constraint Layer
Operation Layer
```
Do not collapse a Web-style Lite prompt into an Agent Spec outline if the target use is direct single-agent deployment.
### 3.1 Core Layer Migration
Old:
```text id="n4jlin"
Core Layer
= identity, role, professional background, style, values, reasoning preference
```
New:
```text id="o2nyw1"
Objective Layer
Role Layer
Model Layer if cognitive model is embedded
Collaboration Layer if role participates in workflow
```
Migration action:
* Extract objective from role description.
* Preserve meaningful role identity.
* Move cognitive model content into Model Layer or Model Card.
* Move collaboration-related content into Collaboration Layer or Runtime.
### 3.2 Execution Layer Migration
Old:
```text id="iyw8qq"
Execution Layer
= functional range, skills, knowledge base, tools, decision authority
```
New:
```text id="o96kei"
Capability Layer
Context Layer
Tool Layer
Authority Layer
Skill references
Model references
```
Migration action:
* Separate capability from authority.
* Separate knowledge assumptions from source policy.
* Separate internal methods from reusable Skills.
* Separate tool abilities from general reasoning abilities.
* Replace omniscience with evidence and uncertainty rules.
### 3.3 Constraint Layer Migration
Old:
```text id="vtu6vs"
Constraint Layer
= hard constraints, soft constraints, safety boundaries, conflict resolution
```
New:
```text id="168nze"
Constraint Layer
Authority Layer
Safety Rules
Refusal Conditions
Conflict Resolution
Evaluation Layer
```
Migration action:
* Keep hard constraints.
* Mark soft constraints as preferences.
* Move permission-related rules to Authority Layer.
* Add testable refusal conditions.
* Add evaluation rules where constraints imply quality standards.
### 3.4 Operation Layer Migration
Old:
```text id="b7likk"
Operation Layer
= input processing, context, memory, workflow, output, validation, feedback, exceptions
```
New:
```text id="qw7p36"
Context Layer
Workflow Layer
State Layer
Output Layer
Evaluation Layer
Runtime Layer
Collaboration Layer if multi-agent
```
Migration action:
* Separate input handling from workflow.
* Separate state from memory.
* Replace chain-of-thought requirements with auditable reasoning summaries.
* Move output format to Output Layer.
* Move validation to Evaluation Layer.
* Move long-running process rules to Runtime Layer.
## 4. Migration Decision Tree
Before migrating, classify the artifact.
### 4.1 If it is a portable expert prompt
Target:
```text id="m2dk5a"
CCPE-Lite
```
Actions:
* Keep concise.
* Preserve persona.
* Preserve the four-layer CCPE 2.0 working kernel when the prompt is deep or expert-like.
* Keep necessary workflow, output, validation, and feedback rules.
* Add minimal objective, boundary, and evaluation rules without weakening the original effect.
* Do not extract components unless reuse, indexing, Codex invocation, or workflow participation is likely.
### 4.2 If it is a durable work role
Target:
```text id="degvph"
CCPE-Agent
```
Actions:
* Add input/output contract.
* Add authority rules.
* Add collaboration rules if applicable.
* Add evaluation criteria.
* Reference Skills and Models instead of embedding everything.
### 4.3 If it contains a reusable procedure
Target:
```text id="68z4dk"
CCPE-Skill
```
Actions:
* Extract trigger conditions.
* Define inputs and outputs.
* Define procedure.
* Add validation and failure handling.
* Reference the Skill from relevant Agents.
### 4.4 If it contains a cognitive model
Target:
```text id="ea70zl"
Model Card
```
Actions:
* Extract model name, scope, assumptions, mechanism, procedure, failure modes, and falsification boundary.
* Keep source trace.
* Add related agents and skills.
* Register in Model Index if accepted.
### 4.5 If it coordinates multiple roles or stages
Target:
```text id="ysdc8s"
CCPE-Runtime
```
Actions:
* Define stages.
* Define participants.
* Define handoff.
* Define state.
* Define human decision gates.
* Define automation boundaries.
* Define outputs and archival rules.
## 5. Self-Contained Model Agent Migration
Many old agents combine:
```text id="y6zibx"
Role
Model
Method
Workflow
Output format
Tool policy
```
This is common and acceptable in CCPE 2.0.
In the new system, inspect whether to split.
### 5.1 Migration Pattern
Preferred pattern:
```text id="hc1wia"
Original self-contained agent
→ Portable Lite Prompt
→ Durable Agent Spec
→ Model Card
→ Executable Skill
→ Runtime node if needed
```
Not all outputs are always required.
For mature Web-style expert agents, the preferred initial pattern is:
```text
Original self-contained agent
→ Portable Lite Prompt preserving the original working kernel
→ Model Card if the embedded model is stable
→ Regression test against the original agent
→ Additional Agent / Skill / Runtime only if the usage scenario requires it
```
The Lite version is not a byproduct. In single-agent scenarios it is the primary production artifact.
For mature expert prompts, prefer this staged pattern before full refinement:
```text
Original self-contained agent
→ original-kernel-minimal-lite
→ small regression comparison
→ temporary production Lite or refinement candidate
→ refined Lite only when cost is justified
```
Do not confuse a refined Lite success case with a default migration requirement.
### 5.2 Example Pattern
Original:
```text id="80wjxv"
Cognitive Imaging Specialist
```
Possible migration:
```text id="89xear"
cognitive-imaging-specialist.prompt.md
cognitive-imaging-specialist.agent.md
cognitive-imaging-model.md
cognitive-imaging.skill.md
review-committee.runtime.md reference
```
### 5.3 Keep Lite Version When
* The user wants copy-paste deployment.
* The agent is used in GPT / Gemini / Claude.
* The model is short enough to embed.
* Platform cannot load external references.
* One-piece portability matters.
### 5.4 Extract Model Card When
* The model is an intellectual asset.
* The model appears in multiple agents.
* The model comes from long-form writing.
* The model deserves indexing.
* The model has independent value.
### 5.5 Extract Skill When
* The method is reusable.
* The method has stable steps.
* The method can be called by multiple agents.
* The method has clear inputs and outputs.
* The method can be validated.
### 5.6 Create Agent Spec When
* The role will be maintained over time.
* The role participates in workflows.
* The role needs authority and collaboration rules.
* The role calls Skills or tools.
* The role has evaluation criteria.
### 5.7 Create Runtime When
* Multiple agents are involved.
* Outputs are routed or synthesized.
* Human approval gates exist.
* State must be tracked.
* Automation is introduced.
## 6. CoT and Reasoning Migration
Old prompts may include instructions such as:
```text id="v27ug5"
Must include internal thought
Must show chain of thought
Must reveal full reasoning process
```
Migrate these instructions.
### 6.1 Replace With
```text id="3zjj27"
Reasoning Summary
Decision Criteria
Validation Checklist
Assumptions
Evidence Used
Uncertainty Notes
Intermediate Findings
Self-Check Results
```
### 6.2 Do Not Require
```text id="w49vl0"
Full hidden chain-of-thought
Private internal reasoning
Raw scratchpad
```
### 6.3 Acceptable Pattern
```text id="k03mfq"
Before final output, perform internal analysis.
In the response, provide:
- Key assumptions
- Reasoning summary
- Main checks performed
- Uncertainty or failure points
- Final conclusion
```
## 7. Retrieval and Source Policy Migration
Old prompts may say:
```text id="grrl3c"
Can use online search
Can use latest facts
Can retrieve external data
```
Migrate to explicit Source Policy.
### 7.1 Required Fields
```text id="zu8u7v"
When retrieval is required
What sources are acceptable
How retrieved facts are treated
How source conflicts are handled
How uncertainty is marked
Whether retrieved material is evidence, raw material, or context
```
### 7.2 Example
```text id="4ej1xe"
Retrieved data is not self-evident truth.
It is treated as raw observational material.
The agent must distinguish:
- reported fact
- interpretation
- correlation
- causal claim
- noise
```
## 8. Tool Policy Migration
Old prompts may mention tools informally.
Migrate informal tool rules into Tool Layer and Authority Layer.
### 8.1 Required Fields
```text id="m1as8m"
Tool Name
Purpose
Allowed Use
Trigger Conditions
Input
Output
Permission Level
Failure Handling
Validation
```
### 8.2 Authority Mapping
Separate:
```text id="5mzlwg"
Can propose tool use
Can invoke tool automatically
Requires confirmation
Forbidden tool use
```
## 9. Output Format Migration
Old prompts may contain long report formats.
Migrate output formats into Output Layer.
### 9.1 Keep
```text id="rk0qly"
Distinctive report sections
Useful terminology
Required analysis fields
Downstream usability
```
### 9.2 Remove or Simplify
```text id="alr6kq"
Duplicate sections
Ceremonial headings with no function
Excessive mandatory verbosity
Unclear formatting
```
### 9.3 Add
```text id="ybluv7"
Concise mode if needed
Full report mode if needed
Follow-up discussion mode if needed
Delivery checklist
Output hierarchy rules
```
### 9.4 Output Structure Discipline
When migrating old prompts with report formats, preserve useful sections but repair hierarchy.
```text
Keep:
Distinctive section names, required fields, and downstream-useful report shape.
Repair:
Flattened list levels, ambiguous heading hierarchy, repeated fields, and formatting that hides conclusions.
Require:
Each major section should begin with a clear judgment, followed by supporting evidence or subpoints.
```
## 10. Constraint Migration
Old hard constraints should be preserved when still useful.
But separate:
```text id="37a548"
Safety constraint
Quality constraint
Role boundary
Permission rule
Evaluation requirement
```
### 10.1 Example
Old:
```text id="5py4vo"
Must always follow five-step workflow.
```
Possible migration:
```text id="pwhbz1"
For full report mode, execute five-step workflow.
For follow-up discussion mode, use the relevant step only.
For non-CAS input, refuse or switch to general analysis.
```
This preserves rigor while reducing unnecessary rigidity.
## 10A. Concept and Reconstruction Discipline
When migrating critique, review, modeling, or pressure-test agents, add rules that prevent false targets.
### 10A.1 Concept Function Discipline
Before testing or refactoring a concept, classify its function:
```text
lens
claim
metaphor
mechanism
generator
procedure
constraint
output form
```
Do not force a lens, metaphor, or local heuristic to carry full causal-generator responsibility unless the source artifact explicitly or implicitly assigns that role.
### 10A.2 Reconstruction Discipline
When testing implicit claims:
```text
1. Separate explicit source claims from reconstructed claims.
2. Mark reconstructed claims before testing them.
3. Use the strongest plausible reconstruction, not a straw version.
4. Note uncertainty when source intent is ambiguous.
```
## 11. Multi-Agent Migration
Old multi-agent systems may exist as separate prompts manually coordinated by the user.
Do not assume immediate automation. First determine whether the current system is:
```text
Manual committee:
The user manually invokes each agent and passes context.
Lead-agent committee:
A director / project manager agent coordinates known members.
Automated Runtime:
The system routes, stores, synthesizes, and resumes work.
```
Migrate into full Runtime only when state, handoff, synthesis, archival, or automation is actually needed:
```text id="i3lzhk"
Runtime Spec
+ Member Agent Specs
+ Shared Skills
+ Human Decision Gates
+ Output Synthesis Rules
+ Archival Rules
```
### 11.1 Pre-Composed Committee Pattern
Use this pattern for stable human-led committees.
```text id="kpbhdr"
Committee Runtime
├── Director Agent
├── Specialist Agents
├── Shared Skills
├── State Rules
├── Human Decision Gates
├── Synthesis Rules
└── Knowledge Archival Rules
```
### 11.2 Do Not Default to Dynamic Agent Creation
If roles are already known and valuable, preserve them.
Dynamic role generation is optional, not default.
## 12. Model Index Migration
When extracting models from old artifacts or articles, update Model Index.
### 12.1 Required Index Fields
```text id="vn7yps"
Model Name
Model Type
Layer
Status
Source
Related Models
Related Agents
Related Skills
Runtime Usage
Canonical Path
Review Status
```
### 12.2 Candidate vs Canonical
Do not promote extracted models to canonical status automatically.
Use statuses:
```text id="umzv4j"
candidate
draft
active
deprecated
archived
```
Human confirmation is required to promote important models.
## 13. Migration Output Format
Every migration should produce an Upgrade Report.
Use this format:
```text id="oqxwgj"
# CCPE Upgrade Report
## 1. Original Artifact
Name:
Path:
Version:
Original Format:
## 2. Original Classification
Primary:
Secondary Components:
Operating Mode:
Depth vs Automation:
## 3. Target Classification
Primary:
Secondary Outputs:
Runtime Need:
## 4. Preserved Elements
...
## 5. Extracted Elements
...
## 6. Modified Elements
...
## 7. Deprecated or Removed Elements
...
## 8. Generated Files
...
## 9. Model Index Updates
...
## 10. Human Decisions Required
...
## 11. Next Step
...
```
## 14. Migration Severity
Use severity labels for problems:
```text id="s0s4oh"
S = Must fix before reuse
A = Major issue
B = Should improve
C = Minor cleanup
```
### 14.1 S-Level Issues
Examples:
```text id="fjkx10"
Unsafe tool authority
Contradictory instructions
No clear objective
High-risk automation without human approval
Model flattened into false universality
```
### 14.2 A-Level Issues
Examples:
```text id="5ikd98"
Model and role too tightly coupled
No source policy for retrieval
No evaluation criteria
Workflow unclear
Scope boundary vague
```
### 14.3 B-Level Issues
Examples:
```text id="w7pwey"
Output format too long
Duplicate sections
Skill extraction opportunity
Missing version metadata
```
### 14.4 C-Level Issues
Examples:
```text id="arwdj5"
Naming inconsistency
Minor formatting issues
Section order could improve
```
## 15. Migration Safety Rules
Before modifying files:
1. Read the artifact.
2. Classify it.
3. Produce a migration plan.
4. List proposed output files.
5. Ask for confirmation before large changes.
6. Write upgraded drafts first.
7. Do not overwrite originals.
8. Preserve an archive copy if replacing canonical versions.
## 16. Migration Completion Criteria
A migration is complete when:
```text id="9u9vg9"
Scenario probe is documented.
The artifact has a clear target form.
Embedded models are handled.
Reusable Skills are identified or extracted.
Runtime needs are addressed or explicitly rejected.
Agent Spec and Skill extraction are justified by usage scenario.
Human decision gates are defined where needed.
Output format is usable.
Evaluation criteria exist.
Model Index is updated when relevant.
Original intent is preserved.
Original working prompt kernel is preserved when target is Lite.
Regression test or comparison is planned for mature agents.
Fast Migration Lane or Refinement Lane is explicitly chosen for mature Lite migrations.
Kernel Force and Production Stability are both considered before promotion.
```
## 17. Final Rule
Migration is not modernization theater.
Do not split an artifact just because the new system has more categories.
Split only when it improves reuse, clarity, safety, evaluation, or long-term maintenance.
Preserve the portable Lite form when it remains useful.
Upgrade the structure without sanding off the mind behind it.
Reference in New Issue View Git Blame Copy Permalink