# 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. CCPE System is a supplier and architecture forge for the user's work projects. Concrete projects such as `writing-workbench`, `knowledge-vault`, `video-workbench`, and future `work-projects` should provide actual requirements first; CCPE supplies the relevant Prompt Cards, Agent Specs, Runtime protocols, Model Cards, evaluation rubrics, invocation contracts, and integration registrations. CCPE System is not a factory for every requested prompt. Its core value is the forging of expert agents, cognitive models, reusable methods, and invocation contracts. Before accepting an external or user-requested artifact into CCPE, test whether it requires expert hidden experience, a stable cognitive model, a reusable method, a durable role, a cross-project contract, or high-risk cognitive boundary management. If it does not, return the request to the business or project repository instead of manufacturing a CCPE artifact. CCPE may design both development agents for the user's own work and production/business agents for deployed systems. For production systems, CCPE owns the specification and governance layer only. The target development project owns framework implementation, LangGraph/CrewAI or similar adapters, server deployment, production state, monitoring, and application-specific runtime behavior. ## 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 5. Supply assets to project repositories: * Read concrete requirement files from project workbenches when provided * Build only the CCPE assets required by those requirements * Avoid inventing project execution workflows before a project asks for them * Keep project runbooks, process records, returned outputs, drafts, and decision logs in the project repository 6. Register external capabilities: * Record architecture dependencies on `skills-vault`, MCP servers, CLI tools, APIs, or installed local capabilities * Do not copy external implementation source into CCPE * Capture authority, allowed operations, validation, failure behavior, and known consumers ## 3. Core Principle Always apply the CCPE value gate and then classify before creating, auditing, or refactoring. Before classification, apply the CCPE value gate: ```text CCPE accepts work when it forges at least one of: - expert agent capability - cognitive model structure - reusable method - durable invocation contract CCPE returns work when it is primarily: - project-local prompt glue - one-off output formatting - immature model trial work - project-specific orchestration or run records - a business-project decision about when to invoke an existing agent or Skill ``` Passing the value gate does not mean CCPE must create every possible artifact layer. It means CCPE may proceed to classification and choose the lightest useful artifact. Failing the value gate means the correct action is to explain the boundary and route the work back to the owning project. Before producing or modifying any artifact, determine whether it is primarily one of the following: ```text CCPE-Lite CCPE-Agent CCPE-Skill CCPE-Runtime CCPE-Committee Model Card Model Index Integration Registration Project Runbook automation Skill source external tool / MCP / CLI / API Hybrid Artifact Out of Scope ``` 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 ``` ### 3.1 Boundary Check Before Work After classification, determine whether the artifact belongs in CCPE. Use this routing: ```text CCPE owns: - CCPE-Lite prompt cards - durable Agent Specs - Committees - CCPE-Skill specs for cognitive, method, workflow, or evaluation capabilities - Runtime specs - Model Cards - Model Index entries - external capability registrations - invocation contracts for CCPE-owned agents, Skills, runtimes, and model-backed methods Project repositories own: - project runbooks - project-specific execution records - article materials and drafts - returned participant reports for one project - user decision logs - publication metadata - project-local adapters, glue prompts, sample runs, and decisions about when to invoke existing CCPE artifacts - immature model exploration before the model reaches a stable enough version for CCPE forging skills-vault owns: - automation Skill source - installable tool skills - scripts, tests, fixtures, examples, and install notes development application repositories own: - deployed production agent implementation - LangGraph, CrewAI, or other framework adapters - server runtime, persistence, monitoring, and application operations ``` Do not migrate project runbooks, automation Skill source, MCP implementations, or production application code into CCPE. If a CCPE Agent or Runtime depends on such a capability, create or propose an Integration Registration instead. ## 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 / Source Judgment Mode Use when the user wants to inspect an existing artifact. In this CCPE-System workspace, when the user provides an original prompt and says they are preparing to upgrade it, terms such as audit, judgment, review, inspection, or evaluation all mean the pre-migration source judgment for that original prompt. For original CCPE 2.0 agent upgrades, do not create a generic audit report. Create an Original Source Judgment Report. 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. Source judgment output rule: ```text Default report path for original CCPE 2.0 agent upgrades: workbench/analysis/{artifact-slug}-original-source-judgment-report.md The required first report is the Original Source Judgment Report, not a generic audit report. Source judgment reports should be written as report documents, not printed in full in the chat. The final chat response should state the report path and wait for the user's next action. ``` ### 5.3 Refactor Mode Use when the user wants to upgrade an existing artifact. Workflow: 1. Produce the Original Source Judgment Report first. 2. Align the judgment with the user's decision, Gemini / original-agent review, rejection, or a new source prompt version. 3. Generate `original-kernel-minimal-lite`; this step is mandatory before later upgrade layers. 4. Optional refined Lite optimization: run A/B tests only when the user chooses to spend the budget for a high-value or high-frequency agent. 5. Only then decide whether to upgrade into Model Card, Skill, Agent Spec, Runtime, or Model Index layers. 6. Preserve original intent and intellectual flavor. 7. Split components only when beneficial and after the minimal-kernel lane and any chosen refined Lite optimization are complete. Known migration status examples: ```text Cognitive Imaging: refined Lite success after multiple A/B rounds. Giant Cognition: intentionally stopped at original-kernel-minimal-lite. Zhang Liao: intentionally stopped at original-kernel-minimal-lite. ``` 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 or planning `original-kernel-minimal-lite` for any mature original CCPE 2.0 agent, always produce a distinct Original Source Judgment Report. Do not collapse the Original Source Judgment Report into a general audit summary. If no visible source-level risks are found, the report must explicitly record: ```text no blocking source-level risks found source decision: use source as-is ``` If visible risks are found, the report must classify each finding and recommend a source decision before migration proceeds. 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 CCPE-Skill specs. These are cognitive, method, workflow, evaluation, transformation, or knowledge-management capability specifications. They are not the canonical source for deterministic automation Skill implementation. Subdirectories: ```text skills/cognitive/ skills/tool/ skills/workflow/ skills/evaluation/ ``` If a capability is primarily script-backed automation, its implementation source belongs in `skills-vault`. CCPE should register it only when a CCPE Agent, Committee, Skill, or Runtime formally depends on it. ### 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 ``` ### 11.12 `integrations/` Stores architecture registrations for external capabilities only when concrete registration files are needed. Future subdirectories may include: ```text integrations/skills-vault/ integrations/mcp/ integrations/cli-tools/ integrations/api-services/ ``` Do not create these directories merely because the category exists. Create them when a CCPE artifact or a project requirement needs a real registration. ## 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. ### 14.1 Agent Invocation and No-Simulation Safety When a Runtime, Agent, or cross-workspace workflow depends on a CCPE participant, define a real invocation boundary before accepting that participant's output. Use an Agent Invocation Packet or equivalent dispatch record for: ```text CCPE-Lite prompt CCPE-Agent spec CCPE-Skill spec CCPE-Runtime node Native platform agent External GPT / Gemini / Claude participant Human-run participant ``` The packet must include: ```text canonical_artifact_path invocation_mode role_integrity_requirement task_context input_files context_files output_contract continuity_policy session_logging return_path no_simulation_requirement ``` Hard rule: ```text Do not simulate canonical participant output. ``` If a participant cannot be truly invoked, stop after producing the invocation packet or `prompt-to-send.md`, mark the stage as: ```text blocked_waiting_for_participant_output ``` and wait for real returned output. If the user explicitly asks for simulation, label it: ```text simulation-only excluded-from-synthesis not-a-formal-report ``` For local Skill execution, write a Skill execution record that identifies the canonical Skill path, input files, output files, completed procedure steps, validation checks, and skipped or failed steps. ## 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. Apply the CCPE value gate. 2. If it fails, return it to the owning project or repository with a short reason. 3. If it passes, classify it. 4. Identify embedded components. 5. Recommend target forms. 6. Produce a plan. 7. Wait for confirmation before major rewrite. If the user asks to create a new agent: 1. Apply the CCPE value gate. 2. If it does not require expert agent capability, cognitive model structure, reusable method, or durable invocation contract, return it to the business/project repository. 3. Build a Creation Brief only after the gate passes. 4. Decide whether Lite, Agent, Skill, Runtime, Model Card, or Hybrid is appropriate. 5. 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.