# 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: ```text CCPE-Lite CCPE-Agent CCPE-Skill CCPE-Runtime Model Card Model Index Hybrid Artifact ``` If the artifact is hybrid, identify its components. Example: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text Agent role Cognitive model Reusable method Workflow Tool policy Output format Runtime role ``` Then decide whether to split it into: ```text Model Card Skill Agent Spec Lite Prompt Card Runtime node ``` Preferred pattern: ```text 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: ```text 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. ### 7.1 Original Kernel Means Verbatim Kernel In Fast Migration Lane, `Original Kernel` must preserve the original CCPE 2.0 prompt body verbatim. Allowed in the wrapper: ```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 `Original Kernel`: ```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 becomes a `refined-lite candidate` and must enter Refinement Lane. ### 7.2 Pre-Migration Source Judgment Gate Before generating `original-kernel-minimal-lite`, inspect the original CCPE 2.0 prompt for visible source-level risks and produce an Original Source Judgment Report when needed. The report should classify each finding as: ```text source defect platform incompatibility kernel feature ambiguous finding ``` The report should recommend one source decision: ```text use source as-is patch only in wrapper repair source first enter Refinement Lane ``` The user may give this judgment report to the original CCPE agent on its native platform, such as Gemini, for second judgment. Do not silently repair, translate, deduplicate, reorder, or smooth the source body before the user chooses the source decision. ## 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: ```text {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: ```text Creator Mode Auditor Mode Refactor Mode Model Mining Mode ``` ### 11.3 `workbench/raw/` Stores temporary or unclassified raw input: * Old agents not yet stored in `knowledge-vault/prompts/` * Old prompts not yet stored in `knowledge-vault/prompts/` * Drafts * Articles * Notes * Unprocessed model material Current maintained prompt assets should be treated as source material in: ```text C:\Users\wangq\Documents\Codex\knowledge-vault\prompts\ ``` When upgrading legacy prompts, the user should provide the exact source path from `knowledge-vault/prompts/`; `workbench/raw/` is no longer the default prompt archive. ### 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: ```text agents/lite/ agents/agent-specs/ agents/committees/ ``` ### 11.8 `skills/` Stores finalized reusable skills. Subdirectories: ```text skills/cognitive/ skills/tool/ skills/workflow/ skills/evaluation/ ``` ### 11.9 `runtimes/` Stores workflow and runtime protocols. Subdirectories: ```text runtimes/interactive/ runtimes/automation/ runtimes/hybrid/ ``` ### 11.10 `model-cards/` Stores finalized Model Cards. Subdirectories: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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.