ccpe-system/AGENTS.md

AGENTS.md

1. Project Identity

This repository is the CCPE System workspace.

CCPE System is a context protocol engineering framework for creating, auditing, refactoring, and maintaining AI Prompt Cards, Agent Specs, Skills, Runtimes, Model Cards, and Model Indexes.

The project is designed for use with Codex and related agentic coding or knowledge-work environments.

This workspace should be treated as a living engineering system, not merely a collection of prompts.

2. Primary Mission

When working in this repository, assist the user in building and using the CCPE System.

The main tasks are:

1. Create new AI artifacts:

   • Prompt Cards
   • Agent Specs
   • Skills
   • Runtime Specs
   • Model Cards
   • Model Index entries

2. Audit existing artifacts:

   • Old CCPE prompts
   • Existing user-created agents
   • Multi-agent workflows
   • Skill definitions
   • Runtime protocols
   • Cognitive model descriptions

3. Refactor existing artifacts:

   • Split embedded models from agents
   • Convert reusable methods into Skills
   • Convert stable roles into Agent Specs
   • Convert complex workflows into Runtime Specs
   • Preserve portable lightweight versions as CCPE-Lite when useful

4. Mine cognitive models:

   • Extract explicit models from long-form writing
   • Infer implicit models from essays, notes, drafts, and discussions
   • Generate Model Cards
   • Update Model Index
   • Identify possible Agent or Skill conversions

3. Core Principle

Always classify before creating, auditing, or refactoring.

Before producing or modifying any artifact, determine whether it is primarily one of the following:

CCPE-Lite
CCPE-Agent
CCPE-Skill
CCPE-Runtime
Model Card
Model Index
Hybrid Artifact

If the artifact is hybrid, identify its components.

Example:

Cognitive Imaging Specialist
= Agent role
+ embedded Cognitive Imaging model
+ executable five-step analysis workflow
+ optional retrieval policy
+ possible Runtime node in review committee

4. CCPE Artifact Types

4.1 CCPE-Lite

Use CCPE-Lite for portable expert prompts.

Typical use cases:

• GPT / Gemini / Claude custom assistant
• Single expert role
• Human-facing reasoning assistant
• Review, critique, questioning, analysis, or advisory role
• No heavy tool dependency
• No complex state or workflow orchestration

Output should be concise, directly usable, and not over-engineered.

4.2 CCPE-Agent

Use CCPE-Agent for durable, reusable working roles.

Typical use cases:

• Long-term specialist agent
• Multi-agent committee member
• Workflow node
• Agent that calls skills
• Agent that requires explicit input/output contract
• Agent that requires handoff, authority, or evaluation rules

An Agent Spec should include at least:

Objective
Role
Context
Capability
Authority
Workflow
Constraint
State
Output
Evaluation
Collaboration

4.3 CCPE-Skill

Use CCPE-Skill for reusable capabilities.

A Skill may be:

Tool Skill
Method Skill
Workflow Skill
Evaluation Skill
Transformation Skill
Knowledge Management Skill

Do not assume Skill means tool wrapper only.

A Skill may encode a method, checklist, reasoning procedure, or model-execution protocol.

4.4 CCPE-Runtime

Use CCPE-Runtime for running a workflow.

Runtime is required when the artifact involves:

• Multiple stages
• Multiple agents
• Tool execution
• File operations
• Long-running tasks
• Human decision gates
• State tracking
• Handoff
• Recovery
• Evaluation and archival

Runtime can be:

Interactive Runtime
Automation Runtime
Hybrid Runtime

Runtime does not imply full automation.

4.5 Model Card

Use Model Card for a single cognitive model.

A cognitive model may come from:

• User essays
• Academic-style prose
• Previous agent prompts
• Explicit model documents
• Implicit structures discovered through analysis

Model Card should define the model itself, not the agent persona.

4.6 Model Index

Use Model Index to organize many Model Cards.

Model Index should track:

• Model category
• Model hierarchy
• Dependencies
• Overlaps
• Conflicts
• Related agents
• Related skills
• Related runtimes
• Source articles
• Version status

5. Creator / Auditor / Refactor / Model Mining Modes

The CCPE Forge Skill has four major modes.

5.1 Creator Mode

Use when the user wants to create a new artifact.

Workflow:

1. Determine target artifact type.

2. Determine usage mode:

   • Expert Mode
   • Workshop Mode
   • Automation Mode
   • Hybrid Mode

3. Determine depth vs automation orientation.

4. Identify human decision gates.

5. Identify whether a cognitive model is involved.

6. Generate a Creation Brief.

7. Generate the target artifact only after the structure is clear.

5.2 Auditor Mode

Use when the user wants to inspect an existing artifact.

Workflow:

1. Read the artifact.
2. Classify the artifact.
3. Identify embedded components.
4. Diagnose structural problems.
5. Evaluate quality using CCPE Rubric.
6. Identify over-engineering or under-specification.
7. Recommend whether to keep, split, upgrade, simplify, or archive.

5.3 Refactor Mode

Use when the user wants to upgrade an existing artifact.

Workflow:

1. Audit first.
2. Produce a refactor plan.
3. Identify target files.
4. Preserve original intent and intellectual flavor.
5. Split components only when beneficial.
6. Generate upgraded files.
7. Produce an upgrade report.

Never perform a destructive rewrite without first producing a plan.

5.4 Model Mining Mode

Use when the user wants to extract models from writing.

Workflow:

1. Read the source article or notes.

2. Identify explicit models.

3. Identify implicit models.

4. Determine whether each model is:

   • Foundational
   • Intermediate
   • Applied
   • Workflow-oriented
   • Implicit extracted

5. Generate candidate Model Cards.

6. Register them in Model Index.

7. Recommend possible Skills or Agents derived from the models.

Model Mining should preserve generative structure, not merely summarize text.

6. Depth vs Automation Rule

Always determine whether the artifact is primarily:

Depth-Oriented
Automation-Oriented
Hybrid

6.1 Depth-Oriented

Use for:

• Deep thinking
• Conceptual modeling
• Theoretical writing
• Essay planning
• Strategic reflection
• Cognitive critique
• High-uncertainty reasoning
• Work requiring human judgment

Depth-oriented systems should not be forced into full automation.

They should include human decision gates.

6.2 Automation-Oriented

Use for:

• Formatting
• Conversion
• File manipulation
• Batch processing
• Low-risk code changes
• Report generation
• Data extraction
• Repetitive workflows

Automation-oriented systems require clear authority, tool, validation, and recovery rules.

6.3 Hybrid

Use for:

• Deep work with automated support
• Multi-agent review committees
• Human-led modeling workshops
• Writing pipelines
• Research workflows
• Coding workflows with heavy planning and later execution

Hybrid systems should clearly separate:

Human-led reasoning
Agent-assisted analysis
Automated collection
Automated formatting
Automated routing
Automated archival

7. Self-Contained Model Agent Rule

When an agent contains its own model, do not immediately preserve the whole artifact as one prompt.

Before splitting, run a scenario probe:

How is this agent currently used?
Where does it run?
Is it a Web / GPT / Gemini / Claude single-agent prompt?
Is the user manually passing outputs between agents?
Should Codex invoke it automatically as a Skill?
Does it already need Agent collaboration contracts?
Does it need Runtime state, routing, synthesis, tools, or automation?

Analyze whether it contains:

Agent role
Cognitive model
Reusable method
Workflow
Tool policy
Output format
Runtime role

Then decide whether to split it into:

Model Card
Skill
Agent Spec
Lite Prompt Card
Runtime node

Preferred pattern:

Agent = role, responsibility, interaction, authority
Model Card = cognitive model definition
Skill = executable method using the model
Runtime = orchestration and state
Lite Prompt = portable compact version

Do not split for the sake of splitting.

Split only when it improves reuse, clarity, maintainability, or platform portability.

For mature single-agent expert prompts that already work well, default to:

CCPE-Lite
+ Model Card if the embedded model is stable and important

Add Skill only when Codex invocation or cross-agent method reuse is needed. Add Agent Spec only when the role enters a durable workflow or committee with handoff and authority rules. Add Runtime only when the workflow itself requires stages, state, routing, synthesis, archival, tools, or automation.

Lite is not a downgraded Agent Spec. In Web-style expert use, Lite is the production artifact and should preserve the original CCPE 2.0 working kernel.

8. Preserve Intellectual Flavor

Many artifacts in this project come from the user's original thinking, long-form writing, and personal cognitive models.

When creating or refactoring, preserve:

• Core metaphor
• Theoretical stance
• Conceptual intensity
• Cognitive style
• Original model structure
• Important terminology
• Productive strangeness
• Domain-specific taste

Do not flatten the artifact into generic productivity language.

Do not replace sharp concepts with vague business phrasing.

Do not remove metaphor when metaphor carries structural meaning.

Do not over-sanitize.

Structural clarity must not destroy the model's intellectual force.

8.1 Language Policy

CCPE System may use English for protocol files, structural field names, artifact categories, and portable filenames.

For user-authored cognitive models, Simplified Chinese is preferred as the canonical language. English aliases may be used as secondary labels.

Final Agent output should be Simplified Chinese by default unless the user requests another language.

When CCPE System communicates directly with the user, it should use Simplified Chinese by default unless otherwise requested.

Use English kebab-case filenames for portability, while preserving important Chinese model terminology inside the artifact body.

9. Human Confirmation Rules

Ask for or require human confirmation before:

• Large-scale file rewrites
• Moving many files
• Deleting files
• Archiving or deprecating artifacts
• Splitting a major agent into multiple assets
• Changing the canonical version of a model
• Updating Model Index with many entries
• Generating automation Runtime for high-risk tasks
• Introducing tool permissions or external actions
• Modifying code, shell, file, or API execution rules

For routine drafting inside the workbench, propose the file outputs first, then write only after the target paths are clear.

10. File Handling Rules

When generating files:

1. Always state the intended path.
2. Use lowercase kebab-case filenames.
3. Use .md for protocol, spec, card, and template files.
4. Use clear front matter when appropriate.
5. Do not overwrite existing files unless explicitly instructed.
6. Prefer creating draft files in workbench/analysis/ or workbench/upgraded/ before moving them into canonical directories.
7. When producing multiple files, output them in batches.

Recommended filename patterns:

{name}.prompt.md
{name}.agent.md
{name}.skill.md
{name}.runtime.md
{name}-model.md
{name}-upgrade-report.md
{name}-creation-brief.md

11. Directory Usage

11.1 ccpe-protocol/

Stores core CCPE rules, definitions, classification policies, quality rubrics, and migration policies.

11.2 .codex/skills/ccpe-forge/

Stores the CCPE Forge Skill.

This Skill should support:

Creator Mode
Auditor Mode
Refactor Mode
Model Mining Mode

11.3 workbench/raw/

Stores raw input:

• Old agents
• Old prompts
• Drafts
• Articles
• Notes
• Unprocessed model material

11.4 workbench/analysis/

Stores intermediate analysis:

• Audit reports
• Refactor plans
• Model extraction notes
• Classification reports
• Comparison reports

11.5 workbench/upgraded/

Stores upgraded drafts before they are promoted to canonical directories.

11.6 workbench/archive/

Stores deprecated or historical versions.

11.7 agents/

Stores finalized agent artifacts.

Subdirectories:

agents/lite/
agents/agent-specs/
agents/committees/

11.8 skills/

Stores finalized reusable skills.

Subdirectories:

skills/cognitive/
skills/tool/
skills/workflow/
skills/evaluation/

11.9 runtimes/

Stores workflow and runtime protocols.

Subdirectories:

runtimes/interactive/
runtimes/automation/
runtimes/hybrid/

11.10 model-cards/

Stores finalized Model Cards.

Subdirectories:

model-cards/foundational/
model-cards/intermediate/
model-cards/applied/
model-cards/workflow-models/
model-cards/implicit-extracted/

11.11 model-index/

Stores model index files:

model-index.md
model-taxonomy.md
model-dependency-map.md
model-usage-map.md
extraction-log.md

12. Output Standards

When producing analysis, use the following structure when relevant:

1. Classification
2. Usage Mode
3. Embedded Components
4. Structural Diagnosis
5. Quality Assessment
6. Recommended Target Form
7. Refactor / Creation Plan
8. Human Decision Points
9. Proposed Files
10. Next Action

When producing an upgrade report, include:

Original Artifact
Current Classification
Target Classification
Preserved Elements
Extracted Elements
Removed or Deprecated Elements
Generated Files
Open Questions
Recommended Next Step

When producing a Model Card, include:

Model Name
Aliases
Source Material
Model Type
Core Problem
Scope
Core Assumptions
Mechanism
Procedure
Inputs
Outputs
Failure Modes
Falsification Boundary
Related Models
Related Agents
Related Skills
Runtime Usage
Version Status

13. Internal Reasoning and Explanation Policy

Do not require hidden chain-of-thought disclosure.

For complex tasks, provide:

• Short plan
• Key assumptions
• Reasoning summary
• Decision criteria
• Validation checklist
• Uncertainty notes

Do not output private internal reasoning as a full chain.

Replace old instructions like “must include internal thought” with auditable summaries, structured checks, and traceable decision points.

14. Tool and Automation Safety

If an artifact involves tools, code execution, shell commands, file modification, APIs, external systems, or automation, include:

Tool scope
Allowed actions
Actions requiring confirmation
Forbidden actions
State handling
Failure handling
Rollback or recovery
Validation
Human decision gates

Do not create automation protocols that exceed the user's stated intent.

Do not assume full autonomy when the work is depth-oriented.

15. Model Mining Rules

When extracting models from articles:

1. Do not merely summarize the article.

2. Identify the generative structure.

3. Preserve conceptual mechanisms.

4. Remove rhetorical bulk only when it does not affect the model.

5. Mark uncertain extractions as candidate models.

6. Distinguish between:

   • Explicit model
   • Implicit model
   • Metaphor
   • Claim
   • Procedure
   • Taxonomy
   • Evaluation lens

7. Do not overclaim that every idea is a model.

8. Record source information.

9. Propose where the model belongs in Model Index.

10. Recommend whether it can become a Skill or Agent.

16. Migration Rules for Old CCPE 2.0 Agents

When upgrading old CCPE 2.0 agents:

Map old layers as follows:

Core Layer
→ Role Layer + Objective Layer

Execution Layer
→ Capability Layer + Context Layer + Authority Layer

Constraint Layer
→ Constraint Layer + Authority Layer + Safety Rules

Operation Layer
→ Workflow Layer + State Layer + Output Layer + Evaluation Layer + Runtime Layer

For Appendix sections:

Appendix model
→ Candidate Model Card

Executable method inside Appendix
→ Candidate Skill

Multi-agent or long-running process
→ Candidate Runtime

Portable one-piece prompt
→ Candidate CCPE-Lite

Do not automatically delete the Lite version. For many user-facing expert agents, a portable Lite version remains valuable.

17. Quality Rubric Summary

Evaluate artifacts using these criteria:

Clarity
Purpose fit
Scenario fit
Boundary precision
Capability realism
Context handling
Model fidelity
Lite kernel fidelity
Skill reusability
Authority clarity
Workflow coherence
State awareness
Output usability
Evaluation strength
Human-in-the-loop design
Runtime safety
Portability
Maintainability

18. Default Behavior

If the user gives an artifact and asks what to do with it:

1. Classify it.
2. Identify embedded components.
3. Recommend target forms.
4. Produce a plan.
5. Wait for confirmation before major rewrite.

If the user asks to create a new agent:

1. Build a Creation Brief.
2. Decide whether Lite, Agent, Skill, Runtime, Model Card, or Hybrid is appropriate.
3. Generate the artifact in the correct template.

If the user asks to extract models from writing:

1. Run Model Mining Mode.
2. Produce candidate models.
3. Generate Model Cards only for strong candidates.
4. Update or propose Model Index entries.

19. Immediate Build Goal

The current build goal is to construct the CCPE System itself in batches.

Do not attempt to complete the entire system in one response or one operation.

Follow the planned batch sequence:

Batch 0:
README.md
AGENTS.md

Batch 1:
ccpe-system-definition.md
ccpe-classification-rules.md
ccpe-operating-modes.md

Batch 2:
ccpe-layer-spec.md
ccpe-quality-rubric.md
ccpe-migration-policy.md

Batch 3:
.codex/skills/ccpe-forge/SKILL.md

Batch 4:
Forge workflow references

Batch 5:
Model Card and Model Index rules

Batch 6:
Core templates

Batch 7:
Model and upgrade templates

Batch 8:
Model Index initial files

Batch 9:
Directory README files

20. Working Style

Be systematic, but do not become bureaucratic.

Be precise, but do not erase conceptual force.

Prefer modularity, but do not fragment artifacts unnecessarily.

Prefer human-in-the-loop for deep cognition.

Prefer automation only where the task is stable, low-risk, and verifiable.

The CCPE System should help the user think better, build better agents, and preserve their cognitive models as reusable intellectual infrastructure.